Last update November 15, 2012

Pull Request

This page describes the process of creating a "pull request" for a D component.

Table of contents of this page

Instructions

Coding Conventions

Tips

Testing and reviewing other pulls

Instructions

Set up git and a GitHub account. (GitHub tutorial)
Find the D repository you wish to contribute to (on https://github.com/D-Programming-Language), and fork it. (GitHub help)
Clone your fork (run git clone git@github.com:YourUserName/D-Component-Name.git).
While this is technically not required, you should create a new branch for your changes. This will prevent accidents in case you'll want to have several unrelated pull requests for the same project. To create a new branch, type: git checkout -b your-branch-name-here
Edit the files in the working copy.
Commit your changes: git commit -am "Commit message here"
(if you added new files, you will need to explicitly add them with git add)
If fixing a bugzilla entry make sure to add Fixes Issue #### somewhere in the commit message (replace # with the bugzilla entry number)
Push your changes: git push origin your-branch-name-here
Go back to the GitHub page for your fork (https://github.com/YourUserName/D-Component-Name)
Select the new branch from the Current branch drop-down, then click the Pull Request button. (GitHub help)
Describe the pull request in the form. You can review your commit and changes on the appropriate tabs.
If fixing a bugzilla entry add the link to to the bugzilla entry in the pull request description, and update the bugzilla issue `Keywords` entry with the 'pull' keyword
When done, submit the form by clicking Send pull request.
If requested to rebase or fix some parts of your pull request, make sure to add a comment once you've pushed back the new changes. This makes sure the reviewers get notified about the change.

When fixing a bug (as listed on Bugzilla), please be sure to:

add a link to your pull request as a Bugzilla comment, and add the keyword "pull" to the issue;
include the string "fix issue nnnn" somewhere in the commit message.

Coding Conventions

Use Type *ptr style when writing pointers in the DMD codebase for C++ files, not Type* ptr (the latter is preferred in D and for druntime/phobos pull requests)
Put else if statements on the same line

Tips

When writing diagnostics checks and if the error message involves array indexes make sure to add the -m32 flag in the required args section at the top. For example:

// REQUIRED_ARGS: -m32
/*
TEST_OUTPUT:
---
fail_compilation/diag8887.d(1): Error: param 'x' of type (int[4u]) cannot be passed by value in extern(C) function
---
*/

Without -m32 and when building on x64 the error message will be (notice it prints 4LU instead of 4u):

fail_compilation/diag8887.d(1): Error: param 'x' of type (int[4LU]) cannot be passed by value in extern(C) function

See one of the diag**.d files in test\fail_compilation for examples.

When writing runnable tests and using assertions make sure to add this line at the top (it can be empty after the colon):

// PERMUTE_ARGS:

This will ensure the module is compiled without -release mode which would ordinarily make the asserts disappear.

When writing/editing ddoc files wrap any D keywords with the $(D ...) macro, e.g.:

$(P This is an $(D opEquals) function.)

Testing and reviewing other pulls

If you want to check out the changesets in a pull request to a local branch, you do one of the following:

Checkout a specific pull (e.g. pull 995 from remote upstream) via:

$ git fetch upstream pull/995/head:pull995
$ git checkout pull995

Or you can make git checkout all the pulls automatically when you call git fetch. Do this by editing the .git/config file. In this sample the last line was added for the remote upstream:

[remote "upstream"]
    url = https://github.com/D-Programming-Language/dmd
    fetch = +refs/heads/*:refs/remotes/upstream/*
    fetch = +refs/pull/*/head:refs/remotes/upstream/pr/*

You can change pr to any other name. Then, to checkout a pull request locally all you have to do is:

$ git fetch
* [new ref]         refs/pull/995/head -> upstream/pr/995
$ git checkout pr/995

You can also apply the trick globally for all of your repositories by running:

git config --global --add remote.upstream.fetch "+refs/pull/*/head:refs/remotes/upstream/pr/*"

This assumes the pull requests are made in the upstream remote. You can change this according to your own needs.