From 7e8bc7fca55d844474f842454bb54cfe17476675 Mon Sep 17 00:00:00 2001 From: Aaron Stannard Date: Mon, 3 Aug 2015 15:03:03 -0700 Subject: [PATCH] added a contributing procedure file --- CONTRIBUTING.MD | 136 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 CONTRIBUTING.MD diff --git a/CONTRIBUTING.MD b/CONTRIBUTING.MD new file mode 100644 index 0000000..a377e01 --- /dev/null +++ b/CONTRIBUTING.MD @@ -0,0 +1,136 @@ +# Contributing to dotNetty +dotNetty is a large project and contributions are more than welcome, so thank you for wanting to contribute to dotNetty! + +--- + +### Checklist before creating a Pull Request +Submit only relevant commits. We don't mind many commits in a pull request, but they must be relevant as explained below. + +- __Use a feature branch__ The pull request should be created from a feature branch, and not from _dev_. See below for why. +- __No merge-commits__ +If you have commits that looks like this _"Merge branch 'my-branch' into dev"_ or _"Merge branch 'dev' of https://github.com/Azure/DotNetty into dev"_ you're probaly using merge instead of [rebase](https://help.github.com/articles/about-git-rebase) locally. See below on _Handling updates from upstream_. +- __Squash commits__ Often we create temporary commits like _"Started implementing feature x"_ and then _"Did a bit more on feature x"_. Squash these commits together using [interactive rebase](https://help.github.com/articles/about-git-rebase). Also see [Squashing commits with rebase](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html). +- __Descriptive commit messages__ If a commit's message isn't descriptive, change it using [interactive rebase](https://help.github.com/articles/about-git-rebase). Refer to issues using `#issue`. Example of a bad message ~~"Small cleanup"~~. Example of good message: _"Removed Security.Claims header from FSM, which broke Mono build per #62"_. Don't be afraid to write long messages, if needed. Try to explain _why_ you've done the changes. The Erlang repo has some info on [writing good commit messages](https://github.com/erlang/otp/wiki/Writing-good-commit-messages). +- __No one-commit-to-rule-them-all__ Large commits that changes too many things at the same time are very hard to review. Split large commits into smaller. See this [StackOverflow question](http://stackoverflow.com/questions/6217156/break-a-previous-commit-into-multiple-commits) for information on how to do this. +- __Tests__ Add relevant tests and make sure all existing ones still passes. Tests can be run using the command +- __No Warnings__ Make sure your code do not produce any build warnings. + +After reviewing a Pull request, we might ask you to fix some commits. After you've done that you need to force push to update your branch in your local fork. + +####Title and Description for the Pull Request#### +Give the PR a descriptive title and in the description field describe what you have done in general terms and why. This will help the reviewers greatly, and provide a history for the future. + +Especially if you modify something existing, be very clear! Have you changed any algorithms, or did you just intend to reorder the code? Justify why the changes are needed. + + +--- + +### Getting started +Make sure you have a [GitHub](https://github.com/) account. + +- Fork, clone, add upstream to the dotNetty repository. See [Fork a repo](https://help.github.com/articles/fork-a-repo) for more detailed instructions or follow the instructions below. + +- Fork by clicking _Fork_ on https://github.com/Azure/DotNetty +- Clone your fork locally. +``` +git clone https://github.com/YOUR-USERNAME/DotNetty +``` +- Add an upstream remote. +``` +git remote add upstream https://github.com/Azure/DotNetty +``` +You now have two remotes: _upstream_ points to https://github.com/Azure/DotNetty, and _origin_ points to your fork on GitHub. + +- Make changes. See below. + +Unsure where to start? Issues marked with [_up for grabs_](https://github.com/Azure/DotNetty/labels/up%20for%20grabs) are things we want help with. + +See also: [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/) + +New to Git? See https://help.github.com/articles/what-are-other-good-resources-for-learning-git-and-github + +### Making changes +__Never__ work directly on _dev_ or _master_ and you should never send a pull request from master - always from a feature branch created by you. + +- Pick an [issue](https://github.com/Azure/DotNetty/issues). If no issue exists (search first) create one. +- Get any changes from _upstream_. +``` +git checkout dev +git fetch upstream +git merge --ff-only upstream/dev +git push origin dev #(optional) this makes sure dev in your own fork on GitHub is up to date +``` + +See https://help.github.com/articles/fetching-a-remote for more info + +- Create a new feature branch. It's important that you do your work on your own branch and that it's created off of _dev_. Tip: Give it a descriptive name and include the issue number, e.g. `implement-lengthframeencoder-323` or `295-implement-recvbuffer`, so that others can see what is being worked on. +``` +git checkout -b my-new-branch-123 +``` +- Work on your feature. Commit. +- Rebase often, see below. +- Make sure you adhere to _Checklist before creating a Pull Request_ described above. +- Push the branch to your fork on GitHub +``` +git push origin my-new-branch-123 +``` +- Send a Pull Request, see https://help.github.com/articles/using-pull-requests to the _dev_ branch. + +See also: [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) (we're using `dev` as our master branch) + +### Handling updates from upstream + +While you're working away in your branch it's quite possible that your upstream _dev_ may be updated. If this happens you should: + +- [Stash](http://git-scm.com/book/en/Git-Tools-Stashing) any un-committed changes you need to +``` +git stash +``` +- Update your local _dev_ by fetching from _upstream_ +``` +git checkout dev +git fetch upstream +git merge --ff-only upstream/dev +``` +- Rebase your feature branch on _dev_. See [Git Branching - Rebasing](http://git-scm.com/book/en/Git-Branching-Rebasing) for more info on rebasing +``` +git checkout my-new-branch-123 +git rebase dev +git push origin dev #(optional) this makes sure dev in your own fork on GitHub is up to date +``` +This ensures that your history is "clean" i.e. you have one branch off from _dev_ followed by your changes in a straight line. Failing to do this ends up with several "messy" merges in your history, which we don't want. This is the reason why you should always work in a branch and you should never be working in, or sending pull requests from _dev_. + +If you're working on a long running feature then you may want to do this quite often, rather than run the risk of potential merge issues further down the line. + +### Making changes to a Pull request +If you realize you've missed something after submitting a Pull request, just commit to your local branch and push the branch just like you did the first time. This commit will automatically be included in the Pull request. +If we ask you to change already published commits using interactive rebase (like squashing or splitting commits or rewriting commit messages) you need to force push using `-f`: +``` +git push -f origin my-new-branch-123 +``` + +### All my commits are on dev. How do I get them to a new branch? ### +If all commits are on _dev_ you need to move them to a new feature branch. + +You can rebase your local _dev_ on _upstream/dev_ (to remove any merge commits), rename it, and recreate _dev_ +``` +git checkout dev +git rebase upstream/dev +git branch -m my-new-branch-123 +git branch dev upstream/dev +``` +Or you can create a new branch off of _dev_ and then cherry pick the commits +``` +git checkout -b my-new-branch-123 upstream/dev +git cherry-pick rev #rev is the revisions you want to pick +git cherry-pick rev #repeat until you have picked all commits +git branch -m dev old-dev #rename dev +git branch dev upstream/dev #create a new dev +``` + +## Code guidelines + +See our [C# Coding Style](https://github.com/Azure/DotNetty/wiki/C%23-Coding-Style) for more information on following the project's conventions. + +--- +Props to [Akka.NET](http://getakka.net/) and [NancyFX](https://github.com/NancyFx/Nancy) from which we've "borrowed" this text.