Skip to content

Latest commit

 

History

History
130 lines (103 loc) · 7.75 KB

CONTRIBUTING.md

File metadata and controls

130 lines (103 loc) · 7.75 KB
Raw

Contributing to Haste SDK for .NET

Haste SDK for .NET is a large project and contributions are more than welcome, so thank you for wanting to contribute to Haste SDK for .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 develop. See below for why.
  • No merge-commits If you have commits that looks like this "Merge branch 'my-branch' into develop" or "Merge branch 'develop' of https://github.com/nhnent/toast-haste.sdk.dotnet into develop" 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/haste.sdk.net
  • Add an upstream remote.
git remote add upstream https://github.com/nhnent/toast-haste.sdk.dotnet

You now have two remotes: upstream points to https://github.com/nhnent/toast-haste.sdk.dotnet, and origin points to your fork on GitHub.

  • Make changes. See below.

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 develop 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 develop
git fetch upstream
git merge --ff-only upstream/develop
git push origin develop     #(optional) this makes sure develop 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 develop. 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

See also: Understanding the GitHub Flow (we're using develop as our master branch)

Handling updates from upstream

While you're working away in your branch it's quite possible that your upstream develop may be updated. If this happens you should:

  • Stash any un-committed changes you need to
git stash
  • Update your local develop by fetching from upstream
git checkout develop
git fetch upstream
git merge --ff-only upstream/develop

git checkout my-new-branch-123
git rebase develop
git push origin develop     #(optional) this makes sure develop 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 develop 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 develop.

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 develop. How do I get them to a new branch?

If all commits are on develop you need to move them to a new feature branch.

You can rebase your local develop on upstream/develop (to remove any merge commits), rename it, and recreate develop

git checkout develop
git rebase upstream/develop
git branch -m my-new-branch-123
git branch develop upstream/develop

Or you can create a new branch off of develop and then cherry pick the commits

git checkout -b my-new-branch-123 upstream/develop
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 develop old-develop     #rename develop
git branch develop upstream/develop   #create a new develop

Props to Akka.NET and NancyFX, and DotNetty from which we've "borrowed" this text.