From a39becb86d493a57f483ed845745be796bc7ec1b Mon Sep 17 00:00:00 2001 From: Seth Atwood Date: Thu, 6 Oct 2016 15:10:59 -0400 Subject: [PATCH] docs: add CONTRIBUTING.md Closes #51 --- CONTRIBUTING.md | 232 ++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 +- 2 files changed, 234 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..dca7323 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,232 @@ +# Git Workflow + +This is the process I use for all my open-source projects to manage a clean tree. + +## Feature Branches + +We should perform all work on “feature branches”, which is to say that we should never do any work on the master branch. For each new task, we create a separate branch, especially if that amounts to multiple feature branches at a time. + +We should be sure to keep all cloned master branches (both those on our local machine and those on GitHub) up to date with the current upstream master to ensure our code will fit in well with any changes that beat you to the proverbial punch. + +With the exception of the feature or bug on which we are working, the tree should remain absolutely pristine with respect to master. That is, there should be no unrelated changes in our feature branch, including minor documentation errors or misspellings in comments on unrelated features. It’s great to catch and fix them, but they should be done in their own feature branch on their own pull request. Or we should open an issue for them. + +## Pull Requests + +When code is ready to be peer-reviewed, merged, or for some other reason presented, we should push our feature branch to our clone and open a pull request for that branch against the upstream master branch. Any further changes we make on that feature branch should, without exception, be in service of that pull request (e.g. incorporation of feedback). + +When the pull request is opened, the continuous integration process will automatically be triggered and its results displayed in the body of the request. This may catch the occasional bug, but it is generally accepted that if our tests pass locally, they should pass in the cloud. We must be sure to test before submitting a pull request. + +Along the same lines, each pull request must be accompanied by any tests and documentation necessary. If a new feature is added, it must be thoroughly unit tested and fully documented. We must make no changes to existing unit tests without adequate documentation for the change in order to ensure all code performs to the agreed spec, now and in the future. + +Further, all code should be easy to read. We should avoid any stylistic or language features that make code more difficult to read. Where possible, our code changes should attempt to match the style of the code that surrounds it. + +## Commit Messages + +The commit message structure is stolen from a loving homage to the conventions used by Google and friends on their open-source libraries. In general, commits should follow the format below, and any line of the commit message should not be longer 100 characters to ensure readability in any git tool. + +``` +(): + + + +