Difference between revisions of "Pull Requests"

From D Wiki
Jump to: navigation, search
(Make your changes in a branch: syntax highlighting)
(syntax highlight)
Line 35: Line 35:
 
Before you submit your changes, it's a good idea to test it thoroughly first. It's also a good idea to run the unittests for druntime and phobos:
 
Before you submit your changes, it's a good idea to test it thoroughly first. It's also a good idea to run the unittests for druntime and phobos:
  
<pre>
+
<syntaxhighlight lang=bash>
% cd /usr/src/d/druntime
+
cd /usr/src/d/druntime
% make -f posix.mak unittest
+
make -f posix.mak unittest
% cd ../phobos
+
cd ../phobos
% make -f posix.mak unittest
+
make -f posix.mak unittest
</pre>
+
</syntaxhighlight>
  
 
Pull requests that fail unittests will not be accepted by the maintainers.
 
Pull requests that fail unittests will not be accepted by the maintainers.
Line 66: Line 66:
 
For example, you may be working on your changes:
 
For example, you may be working on your changes:
  
<pre>
+
<syntaxhighlight lang=bash>
% cd /usr/src/d/phobos
+
cd /usr/src/d/phobos
% git checkout mybranch
+
git checkout mybranch
% vim std/algorithm.d  # apply lots of cool changes here
+
vim std/algorithm.d  # apply lots of cool changes here
</pre>
+
</syntaxhighlight>
  
 
First, before you resync with master, make sure all your changes are checked in (or stashed):
 
First, before you resync with master, make sure all your changes are checked in (or stashed):
  
<pre>
+
<syntaxhighlight lang=bash>
% git commit -a
+
git commit -a
</pre>
+
</syntaxhighlight>
  
 
Then checkout master and pull from upstream:
 
Then checkout master and pull from upstream:
  
<pre>
+
<syntaxhighlight lang=bash>
% git checkout master
+
git checkout master
% git pull --ff-only upstream master
+
git pull --ff-only upstream master
</pre>
+
</syntaxhighlight>
  
 
The --ff-only option is to ensure that your master branch is identical to the official D sources' master branch, since otherwise you will end up with a very messy history that will be hard to clean up (and the reviewers will probably reject your pull request due to having unrelated merge commits).
 
The --ff-only option is to ensure that your master branch is identical to the official D sources' master branch, since otherwise you will end up with a very messy history that will be hard to clean up (and the reviewers will probably reject your pull request due to having unrelated merge commits).
Line 89: Line 89:
 
Now go back to your branch and rebase it:
 
Now go back to your branch and rebase it:
  
<pre>
+
<syntaxhighlight lang=bash>
% git checkout mybranch
+
git checkout mybranch
% git rebase master
+
git rebase master
</pre>
+
</syntaxhighlight>
  
 
Now your sources should be up-to-date. Recompile and test everything to make sure it all works.
 
Now your sources should be up-to-date. Recompile and test everything to make sure it all works.
Line 98: Line 98:
 
Note that after rebasing, you will need to force an update to your fork on GitHub with the -f flag, otherwise it will fail because the histories don't match anymore:
 
Note that after rebasing, you will need to force an update to your fork on GitHub with the -f flag, otherwise it will fail because the histories don't match anymore:
  
<pre>
+
<syntaxhighlight lang=bash>
% git push -f origin mybranch
+
git push -f origin mybranch
</pre>
+
</syntaxhighlight>
  
 
You may wish to read up on [http://git-scm.com/book/en/Git-Branching-Rebasing how git rebase works] if you're not familiar with the concept.
 
You may wish to read up on [http://git-scm.com/book/en/Git-Branching-Rebasing how git rebase works] if you're not familiar with the concept.
  
 
If, during the 'git rebase' command, you encounter conflicts, you may want to learn [http://stackoverflow.com/questions/8780257/git-rebase-a-branch-onto-master-failed-how-to-resolve how to resolve a conflict during git rebase].
 
If, during the 'git rebase' command, you encounter conflicts, you may want to learn [http://stackoverflow.com/questions/8780257/git-rebase-a-branch-onto-master-failed-how-to-resolve how to resolve a conflict during git rebase].

Revision as of 23:23, 10 December 2012

The source code of the D compiler (dmd), runtime library (druntime), and standard library (Phobos), are all available at GitHub.

Fork the project

To contribute to the D compiler, runtime library, or standard library, you need to create an account on GitHub, and then navigate to the D programming language page, select the project you wish to contribute to, and create a fork of that project.

For example, if you wish to submit a patch to the D compiler, you should navigate to D-Programming-Language/dmd, then click on the "Fork" button at the top right corner of the page. This will clone the D compiler sources into your list of projects.

Check out the sources

See also: Using Git on Windows

Once you have forked the project you wish to contribute to, use git to checkout a local copy of the project.

Generally, you should checkout a copy of at least dmd, druntime, and phobos in order to have a working compiler toolchain that you can use to test your changes.

After checking out the sources, you will probably want to know how to build git master.

Make your changes in a branch

Generally, it is preferred that any changes you wish to contribute should be made in its own dedicated topic branch. For example, if you have a fix for issue 1234 in the D compiler, you might want to do something like this:

cd /usr/src/d/dmd/src
git checkout -b issue_1234
vim expression.c    # make your changes here
make -f posix.mak
...                 # test your changes here
git commit -a       # commit to the branch named 'issue_1234'
git push -u origin  # push changes to your fork of DMD

Test your changes

Before you submit your changes, it's a good idea to test it thoroughly first. It's also a good idea to run the unittests for druntime and phobos:

cd /usr/src/d/druntime
make -f posix.mak unittest
cd ../phobos
make -f posix.mak unittest

Pull requests that fail unittests will not be accepted by the maintainers.

TBD: add instructions on running dmd's unittests.

Create a pull request

Once you have tested all your changes and pushed them to your fork on GitHub, you are ready to submit a pull request.

  1. Navigate to your fork of the project on GitHub.
  2. Important: Select the branch that you made your changes in, say issue_1234.
  3. Click on the "Pull Request" button.

This will submit your changes for review by the D maintainers. If your changes are approved, they will be merged into the master branch. Otherwise, if the maintainers have some comments or feedback, you can refine your changes by editing and testing in your local workspace, and pushing the new changes to the same git branch. The new changes will be automatically included in your pull request.

Autotester

Pull requests are automatically picked up by the autotester, which compiles the code in the pull request and runs it through the dmd, druntime, and phobos unittests on all supported platforms. Generally, pull requests must pass all tests before they will be merged. The status of the tests can be monitored through the pull request page.

Rebasing

Sometimes, if a particular change you are working on is taking a long time, or if you encounter a problem that is fixed by a new commit upstream, you may need to sync your local branch with master in order to keep the code up-to-date. In this case, it is recommended that you use git rebase to apply your changes on top of the latest git master, so that when you submit a pull request, the change history will be easier for the reviewers to follow. Using git merge is not recommended, as it may produce a lot of merge commits that may not be relevant to your changes.

For example, you may be working on your changes:

cd /usr/src/d/phobos
git checkout mybranch
vim std/algorithm.d   # apply lots of cool changes here

First, before you resync with master, make sure all your changes are checked in (or stashed):

git commit -a

Then checkout master and pull from upstream:

git checkout master
git pull --ff-only upstream master

The --ff-only option is to ensure that your master branch is identical to the official D sources' master branch, since otherwise you will end up with a very messy history that will be hard to clean up (and the reviewers will probably reject your pull request due to having unrelated merge commits).

Now go back to your branch and rebase it:

git checkout mybranch
git rebase master

Now your sources should be up-to-date. Recompile and test everything to make sure it all works.

Note that after rebasing, you will need to force an update to your fork on GitHub with the -f flag, otherwise it will fail because the histories don't match anymore:

git push -f origin mybranch

You may wish to read up on how git rebase works if you're not familiar with the concept.

If, during the 'git rebase' command, you encounter conflicts, you may want to learn how to resolve a conflict during git rebase.