Skip to content

Latest commit

 

History

History
161 lines (125 loc) · 8.82 KB

CONTRIBUTING.md

File metadata and controls

161 lines (125 loc) · 8.82 KB
Raw

Contributing to Akka.NET

Akka.NET is a large project and contributions are more than welcome, so thank you for wanting to contribute to Akka.NET!

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 github .com/akkadotnet/akka.net into dev" you're probaly using merge instead of 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. Also see Squashing commits with rebase.
  • Descriptive commit messages If a commit's message isn't descriptive, change it using interactive 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.
  • 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 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 account.

git clone https://github.com/YOUR-USERNAME/akka.net
  • Add an upstream remote.
git remote add upstream https://github.com/akkadotnet/akka.net

You now have two remotes: upstream points to https://github.com/akkadotnet/akka.net, and origin points to your fork on GitHub.

  • Make changes. See below.

Unsure where to start? Issues marked with up for grabs are things we want help with.

See also: Contributing to Open Source on GitHub

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. 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-testkits-eventfilter-323 or 295-implement-tailchopping-router, 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

See also: Understanding the GitHub 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 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

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

The build server isn't picking up a Pull request that I've modified

The build server relies on git commit timestamps to keep track of new builds that it needs to perform. When updating a PR, sometimes the timestamp of the latest commit in the PR isn't updated. This leads the build server to think that the PR has already been built and tested. In order to force the build server to rebuild and test the updated PR, please follow the instructions outlined in this post How can one change the timestamp of an old commit in Git?.

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

What to do with feature branch after the pull request is merged and closed ?

After a pull request has been merged and closed you can delete the feature branch.

Get latest changes from the upstream

git checkout dev
git fetch upstream
git merge --ff-only upstream/dev
git push origin dev

Remove the branch locally

git branch -d my-new-branch-123

Remove the branch on remote

git push origin --delete my-new-branch-123

Code guidelines

See our Contributor Guidelines for more information on following the project's conventions.

Props to NancyFX from which we've "borrowed" some of this text.