From 42853c16dd5a2d952740ae03edbd506caa036e09 Mon Sep 17 00:00:00 2001 From: Andreas Richter Date: Mon, 20 Jul 2020 14:22:41 +0200 Subject: [PATCH] docs: update CONTRIBUTING.md --- CONTRIBUTING.md | 134 ++++++++++++++++++++++++++++-------------------- 1 file changed, 78 insertions(+), 56 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97f36b9..a0e1e03 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,5 +1,3 @@ - - # Contributing 🎉🏅 Thanks for helping us improve this project! 🙏 @@ -8,12 +6,13 @@ This document outlines some of the practices we care about. If you have any questions or suggestions about the process, feel free to [open an issue](#reporting-issues) or [reach out to us directly](#contact). + ## How Can I Contribute? ### Reporting Issues If you find any mistakes in the docs or a bug in the code, -please [open an issue in Github](https://github.com/testiumjs/testium-example-app/issues/new) so we can look into it. +please [open an issue in Github](https://github.com/testiumjs/testium-core/issues/new) so we can look into it. You can also [create a PR](#contributing-code) fixing it yourself, or course. If you report a bug, please follow these guidelines: @@ -22,18 +21,22 @@ If you report a bug, please follow these guidelines: * Include instructions on how to reproduce the issue. The instructions should be as minimal as possible and answer the three big questions: - 1. What are the exact steps you took? This includes the exact versions of node, npm, and any packages involved. + 1. What are the exact steps you took? This includes the exact versions of + node, npm, and any packages involved. 1. What result are you expecting? 1. What is the actual result? ### Improving Documentation -For small documentation changes, you can use [Github's editing feature](https://help.github.com/articles/editing-files-in-another-user-s-repository/). +For small documentation changes, you can use [Github's editing feature][ghedit]. The only thing to keep in mind is to prefix the commit message with "docs: ". -The detault commit message generated by Github will lead to a failing CI build. +The default commit message generated by Github will lead to a failing CI build. + +[ghedit]: https://help.github.com/articles/editing-files-in-another-user-s-repository/ For larger updates to the documentation -it might be better to follow the [instructions for contributing code below](#contributing-code). +it might be better to follow the +[instructions for contributing code below](#contributing-code). ### Contributing Code @@ -44,40 +47,41 @@ only to discover that it conflicts with plans the maintainers might have. The general steps for creating a pull request are: -1. Create a branch for your change. - Always start your branch from the latest `master`. - We often prefix the branch name with our initials, e.g. `jk-a-change`. -1. Run `npm install` to install the dependencies. -1. If you're fixing a bug, be sure to write a test *first*. - That way you can validate that the test actually catches the bug and doesn't pass. -1. Make your changes to the code. - Remember to update the tests if you add new features or change behavior. -1. Run the tests via `npm test`. This will also run style checks and other validations. - You might see errors about uncommitted files. - This is expected until you commit your changes. -1. Once you're done, `git add .` and `git commit`. - Please follow the [commit message conventions](#commits--commit-messages) described below. +1. Create a branch for your change. Always start your branch from the latest + `master`. We recommend using `git wf start some-feature-name` by using + [git workflow][gitwf]. Run `npm install` to install the dependencies. +1. If you're fixing a bug, be sure to write a test *first*. That way you can + validate that the test actually catches the bug and doesn't pass. +1. Make your changes to the code. Remember to update the tests if you add new + features or change behavior. +1. Run the tests via `npm test`. This will also run style checks and other + validations. You might see errors about uncommitted files. This is + expected until you commit your changes. +1. Once you're done, `git add .` and `git commit`. Please follow the + [commit message conventions](#commits--commit-messages) described below. 1. Push your branch to Github & create a PR. +[gitwf]: https://github.com/groupon/git-workflow + #### Code Style -In addition to any linting rules the project might include, -a few general rules of thumb: +In addition to any linting rules the project might include, a few general rules +of thumb: * Try to match the style of the rest of the code. * We prefer simple code that is easy to understand over terse, expressive code. -* We try to structure projects by semantics instead of role. - E.g. we'd rather have a `tree.js` module that contains tree traversal-related helpers - than a `helpers.js` module. -* Actually, if you create helpers you might want to put those into a separate package. - That way it's easier to reuse them. +* We try to structure projects by semantics instead of role. E.g. we'd rather + have a `tree.js` module that contains tree traversal-related helpers than + a `helpers.js` module. +* Actually, if you create helpers you might want to put those into a separate + package. That way it's easier to reuse them. #### Commits & Commit Messages -Please follow the [angular commit message conventions](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#-git-commit-guidelines). -We use an automated tool for generating releases -that depends on the conventions to determine the next version and the content of the changelog. -Commit messages that don't follow the conventions will cause `npm test` (and thus CI) to fail. +Please follow the [angular commit message conventions][angular-commits]. We +use an automated tool for generating releases that depends on the conventions +to determine the next version and the content of the changelog. Commit messages +that don't follow the conventions will cause `npm test` (and thus CI) to fail. The short summary - a commit message should look like this: @@ -91,37 +95,55 @@ The short summary - a commit message should look like this: