-
Notifications
You must be signed in to change notification settings - Fork 9
/
contributing.html
69 lines (68 loc) · 4.37 KB
/
contributing.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
---
layout: general_page
title: Contributing
permalink: /contributing/
---
<h2>Contributing code to CloudRouter repos</h2>
<p>The CloudRouter Project welcomes contributions from all members of the community. We ask that when making contributions, you follow these simple guidelines.</p>
<p></p>
<h3>Packaging Guidelines</h3>
<p>
<p>The CloudRouter Project has adopted packaging guidelines from the <a href="https://getfedora.org/">Fedora Project</a>. Please see <a href="https://cloudrouter.atlassian.net/wiki/display/CPD/Packaging+Guidelines">Packaging Guidelines</a> for more information.
<p></p>
<h3>Forks and pull requests</h3>
<p>
<p>In order to contribute code to any CloudRouter Project repo, please maintain a personal fork and commit your changes there first. Once you are ready to submit your changes for review and merging into a CloudRouter Project repo, create a pull request. The Travis CI system will automatically run some basic tests on your pull request before it is reviewed by a CloudRouter Project committer. The Project is also utilizing <a href="https://ci.cloudrouter.org">Jenkins CI</a>. It is encouraged that you use a <a href="https://www.atlassian.com/git/tutorials/comparing-workflows/feature-branch-workflow/">feature branch</a> when contributing code or fixing a bug.</p>
<p></p>
<h3>Sign-off on all commits</h3>
<p>
<p>The <a href="{{ site.baseurl }}/developer-certificate/">Developer's Certificate of Origin</a> requires that all commits be signed off. Commits can be <a href="http://git-scm.com/docs/git-commit">signed off</a> by adding the "--signoff" or "-s" flag to your git commit command. A Travis CI test checks that commits are signed off, and all pull requests containing any commits missing sign off will be rejected.</p>
<p>Git hooks that automatically sign off all commits, or reject commits that are not signed off are <a href="https://github.com/cloudrouter/cloudrouter/tree/master/contrib/hooks">available here</a>.</p>
<p></p>
<h3>Merging pull requests</h3>
<p>
<p>Committers who merge pull request should <strong>NOT</strong> use the green merge button provided by the github web interface. The merge button adds a merge commit, which is problematic for several reasons. The merge commit will not be signed off by default, violating the rule requiring all commits to be signed off. Furthermore, merge commits add significant noise to logs and complicate the syncing of branches and forks. Pull requests should also not be merged until the Travis CI jobs successfully run.</p>
<p>There are several possible scenarios where merging pull requests. See below for instructions on merging in each case.</p>
<p></p>
<h3>Master branch</h3>
<p>
<p>The simpliest case is a pull request with changes on the fork's master branch. In this case, run the following commands. Note that $FORK should be replaced with the namespace of the fork, i.e. the name of the user who created it. $REPO should be replaced with the repo name, e.g. cloudrouter.</p>
<p>
<pre>
git checkout -b $FORK-master master
git pull https://github.com/$FORK/$REPO.git master
git checkout master
git merge --no-commit $FORK-master
git push origin/master
</pre>
<p></p>
<h3>Feature branch</h3>
<p>
<p>If the pull request contains changes on a feature branch, run the following commands. Note that $FEATURE_BRANCH should be replaced with the name of the feature branch.
<p>
<pre>
git checkout -b $FORK-$FEATURE_BRANCH master
git pull https://github.com/$FORK/$REPO.git $FEATURE_BRANCH
git checkout master
git merge --no-commit $FORK-$FEATURE_BRANCH
git push origin/master
</pre>
<p></p>
<h3>Complex merges</h3>
<p>
<p>In some cases, the merge scenario may be more complex. For example, there may be two pull requests both based on the same commit in the upstream master repo. The first can be merged as noted above, but the second will now be one or more commits behind master. There are two ways of handling this.</p>
<p>
<p>1. Cherry-picking commits</p>
<p>
<p>This approach is <a href="http://git-scm.com/docs/git-cherry-pick">documented here</a>. Note that this approach can also be used when you only wish to merge part of a pull request.</p>
<p>
<p>2. Rebase before merge</p>
<p>
<p>This approach is better when you are dealing with a large number of commits.
<p>
<pre>
git remote add $FORK https://github.com/$FORK/$REPO
git fetch $FORK
git checkout -b $FORK-$FEATURE_BRANCH $FORK/$FEATURE_BRANCH
git pull --rebase origin master
</pre>