wiki:WorkingConventions/FixingBugs

How to contribute a patch to GHC

Here's how to submit a bug fix to GHC. For adding features, there are a few extra steps to follow.

  1. Make sure the bug is in Trac. Usually it is (that's why you are working on it), but if it's a bug you have found yourself, add it to Trac before you start work. It's important to have a ticket, because it makes sure that the bug report, discussion about the fix, the regression test that checks it, and the eventual conclusion, are all recorded together. Comments in the code can refer to the ticket (e.g. See Trac #2382 for an example). And so on. If there's no ticket, there is every chance that it'll get lost.

  2. Take ownership of the bug in Trac, by using the "Action" chunk at the bottom of the Trac bug display (you need to be logged in to see it), and putting your name in the "reassign to" box. This makes sure that two people don't work on the same bug. You can skip this step if you've submitted your patch to Phabricator already (see below). If you later decide you can't do it after all, remove your name.

  3. Add a test case in the testsuite that shows up the bug.

    • Name the test after the bug number - this is helpful for finding the bug again in the future.

    • Put the directory and name of the test in the "Test Case" field of the Trac report.

  4. Fix the bug!

    • If your proposed fix has non-local consequences, please consult us before investing too much of your time.

    • Please follow our coding conventions.

    • Comment your fix in the source code, and include a reference to the bug ticket number, e.g. "#1466" (this helps when grepping for the fix later).

  5. Make one or several commits that embody your fix.

    • Separate changes that affect functionality from those that just affect code layout, indentation, whitespace, filenames etc. This means that when looking at patches later, we don't have to wade through loads of non-functional changes to get to the important parts of the patch.

    • Please try to follow the general convention for the Git commit message structure as many Git tools rely on this. Moreover, take into account that the commit message text is interpreted as WikiFormatting in Trac.

    • include the ticket number in the form "#NNNN" in the commit message, e.g.
      withMVar family have a bug (fixes #767)
      
      Git will then add a link to the commit from the ticket (as soon as the commit becomes reachable from the master HEAD), so that people watching the ticket can see that a fix has been committed, and in the future we can easily find the patch that addressed the ticket. When navigating the Git history on Trac, you will also be able to jump directly to the ticket from the commit.

    • Please make sure you have setup git to use the correct name and email for your commits. Use the same name and email on all machines you may commit from, or add an entry to the .mailmap file in the ghc root directory.
      $ git config --global user.name "Firstname Lastname"
      $ git config --global user.email "[email protected]"
      

    • Files in GHC repos should use Unix conventions for line endings. If you are on Windows, ensure that git handles line-endings sanely by running:
      git config --global core.autocrlf false
      

  6. Test your commits using the validation script or Travis. Alternatively, you can let Harbormaster build and validate your commits, see next step. (If you have write permission to the repository, then you must validate before pushing.)

  7. Submit one or several code reviews to Phabricator. Wait for Phabricator/Harbormaster to build and validate your commits (~35 minutes each, September 2014).

  8. Update the Trac ticket. Fill out the field called "Differential Revisions". Syntax: Phab:D123.

  9. Wait for the reviewers to look at your patches. If this takes more than a week, complain!

  10. Wait for the release manager to land your patches. If this takes more than a week, complain!

Then have a beer on us. We are truly grateful.

Last modified 3 weeks ago Last modified on Jun 7, 2015 12:54:10 AM