|
| 1 | +# Contributing to Akka.NET |
| 2 | +Akka.NET is a large project and contributions are more than welcome, so thank you for wanting to contribute to Akka.NET! |
| 3 | + |
| 4 | +--- |
| 5 | + |
| 6 | +### Checklist before creating a Pull Request |
| 7 | +Submit only relevant commits. We don't mind many commits in a pull request, but they must be relevant as explained below. |
| 8 | + |
| 9 | +- __Use a feature branch__ The pull request should be created from a feature branch, and not from _dev_. See below for why. |
| 10 | +- __No merge-commits__ |
| 11 | +If you have commits that looks like this _"Merge branch 'my-branch' into dev"_ or _"Merge branch 'dev' of github .com/akkadotnet/akka.net 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_. |
| 12 | +- __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). |
| 13 | +- __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). |
| 14 | +- __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. |
| 15 | +- __Tests__ Add relevant tests and make sure all existing ones still passes. Tests can be run using the command |
| 16 | +- __No Warnings__ Make sure your code do not produce any build warnings. |
| 17 | + |
| 18 | +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. |
| 19 | + |
| 20 | +####Title and Description for the Pull Request#### |
| 21 | +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. |
| 22 | + |
| 23 | +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. |
| 24 | + |
| 25 | + |
| 26 | +--- |
| 27 | + |
| 28 | +### Getting started |
| 29 | +Make sure you have a [GitHub](https://github.com/) account. |
| 30 | + |
| 31 | +- Fork, clone, add upstream to the Akka.NET repository. See [Fork a repo](https://help.github.com/articles/fork-a-repo) for more detailed instructions or follow the instructions below. |
| 32 | + |
| 33 | +- Fork by clicking _Fork_ on https://github.com/akkadotnet/akka.net |
| 34 | +- Clone your fork locally. |
| 35 | +``` |
| 36 | +git clone https://github.com/YOUR-USERNAME/akka.net |
| 37 | +``` |
| 38 | +- Add an upstream remote. |
| 39 | +``` |
| 40 | +git remote add upstream https://github.com/akkadotnet/akka.net |
| 41 | +``` |
| 42 | +You now have two remotes: _upstream_ points to https://github.com/akkadotnet/akka.net, and _origin_ points to your fork on GitHub. |
| 43 | + |
| 44 | +- Make changes. See below. |
| 45 | + |
| 46 | +Unsure where to start? Issues marked with [_up for grabs_](https://github.com/akkadotnet/akka.net/labels/up%20for%20grabs) are things we want help with. |
| 47 | + |
| 48 | +See also: [Contributing to Open Source on GitHub](https://guides.github.com/activities/contributing-to-open-source/) |
| 49 | + |
| 50 | +New to Git? See https://help.github.com/articles/what-are-other-good-resources-for-learning-git-and-github |
| 51 | + |
| 52 | +### Making changes |
| 53 | +__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. |
| 54 | + |
| 55 | +- Pick an [issue](https://github.com/akkadotnet/akka.net/issues). If no issue exists (search first) create one. |
| 56 | +- Get any changes from _upstream_. |
| 57 | +``` |
| 58 | +git checkout dev |
| 59 | +git fetch upstream |
| 60 | +git merge --ff-only upstream/dev |
| 61 | +git push origin dev #(optional) this makes sure dev in your own fork on GitHub is up to date |
| 62 | +``` |
| 63 | + |
| 64 | +See https://help.github.com/articles/fetching-a-remote for more info |
| 65 | + |
| 66 | +- 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-testkits-eventfilter-323` or `295-implement-tailchopping-router`, so that others can see what is being worked on. |
| 67 | +``` |
| 68 | +git checkout -b my-new-branch-123 |
| 69 | +``` |
| 70 | +- Work on your feature. Commit. |
| 71 | +- Rebase often, see below. |
| 72 | +- Make sure you adhere to _Checklist before creating a Pull Request_ described above. |
| 73 | +- Push the branch to your fork on GitHub |
| 74 | +``` |
| 75 | +git push origin my-new-branch-123 |
| 76 | +``` |
| 77 | +- Send a Pull Request, see https://help.github.com/articles/using-pull-requests to the _dev_ branch. |
| 78 | + |
| 79 | +See also: [Understanding the GitHub Flow](https://guides.github.com/introduction/flow/) (we're using `dev` as our master branch) |
| 80 | + |
| 81 | +### Handling updates from upstream |
| 82 | + |
| 83 | +While you're working away in your branch it's quite possible that your upstream _dev_ may be updated. If this happens you should: |
| 84 | + |
| 85 | +- [Stash](http://git-scm.com/book/en/Git-Tools-Stashing) any un-committed changes you need to |
| 86 | +``` |
| 87 | +git stash |
| 88 | +``` |
| 89 | +- Update your local _dev_ by fetching from _upstream_ |
| 90 | +``` |
| 91 | +git checkout dev |
| 92 | +git fetch upstream |
| 93 | +git merge --ff-only upstream/dev |
| 94 | +``` |
| 95 | +- Rebase your feature branch on _dev_. See [Git Branching - Rebasing](http://git-scm.com/book/en/Git-Branching-Rebasing) for more info on rebasing |
| 96 | +``` |
| 97 | +git checkout my-new-branch-123 |
| 98 | +git rebase dev |
| 99 | +git push origin dev #(optional) this makes sure dev in your own fork on GitHub is up to date |
| 100 | +``` |
| 101 | +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_. |
| 102 | + |
| 103 | +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. |
| 104 | + |
| 105 | +### Making changes to a Pull request |
| 106 | +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. |
| 107 | +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`: |
| 108 | +``` |
| 109 | +git push -f origin my-new-branch-123 |
| 110 | +``` |
| 111 | + |
| 112 | +### All my commits are on dev. How do I get them to a new branch? ### |
| 113 | +If all commits are on _dev_ you need to move them to a new feature branch. |
| 114 | + |
| 115 | +You can rebase your local _dev_ on _upstream/dev_ (to remove any merge commits), rename it, and recreate _dev_ |
| 116 | +``` |
| 117 | +git checkout dev |
| 118 | +git rebase upstream/dev |
| 119 | +git branch -m my-new-branch-123 |
| 120 | +git branch dev upstream/dev |
| 121 | +``` |
| 122 | +Or you can create a new branch off of _dev_ and then cherry pick the commits |
| 123 | +``` |
| 124 | +git checkout -b my-new-branch-123 upstream/dev |
| 125 | +git cherry-pick rev #rev is the revisions you want to pick |
| 126 | +git cherry-pick rev #repeat until you have picked all commits |
| 127 | +git branch -m dev old-dev #rename dev |
| 128 | +git branch dev upstream/dev #create a new dev |
| 129 | +``` |
| 130 | + |
| 131 | +## Code guidelines |
| 132 | + |
| 133 | +See [Contributor Guidelines](http://akkadotnet.github.io/wiki/Contributor%20guidelines) on the wiki. |
| 134 | + |
| 135 | +--- |
| 136 | +Props to [NancyFX](https://github.com/NancyFx/Nancy) from which we've "borrowed" some of this text. |
0 commit comments