|
|
# How to contribute a new feature to GHC
|
|
|
|
|
|
|
|
|
We welcome your involvement in making GHC able to do more. Here's how to do it
|
|
|
We welcome your involvement in making GHC able to do more. Here's how to do it.
|
|
|
|
|
|
1. **Add a Trac feature request** for your proposed new feature (unless it's there already). Use "feature request" in the "Type" field.
|
|
|
1. **Take ownership of the ticket 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 feature. If you later decide you can't do it after all, remove your name.
|
|
|
1. **Write down the specification of the feature** and either add it directly to Trac, or put it on a web page somewhere else and link to it. Specifying before implementing is obviously a good idea; and it makes it possible for others to comment on your design before you invest heavily in building the feature.
|
|
|
1. **Write down the specification of the feature** and create a Wiki page for it, or put it on a web page somewhere else and link to it. Specifying before implementing is obviously a good idea; and it makes it possible for others to comment on your design before you invest heavily in building the feature.
|
|
|
1. **Get feedback** by emailing a suitable list (`ghc-devs` for nitty-gritty GHC internals, `glasgow-haskell-users` for user-visible features). Often you'll get useful ideas.
|
|
|
1. **Implement the feature**!
|
|
|
|
|
|
- Please follow our [coding conventions](working-conventions#)
|
|
|
- Please follow our [coding conventions](working-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). It is often helpful to give a small example code fragment that demonstrates the need for your fix. This isn't always relevant; sometimes you are fixing a plain error, but often it's more subtle than that.
|
|
|
1. **Test the feature** by creating a reasonable collection of tests that exercise the new capabilities, and incorporating the new tests in the main testsuite. The building guide contains a [description of how to add tests](building/running-tests).
|
|
|
1. **Record a patch** that embodies your feature.
|
|
|
1. **Make a commit** that embodies your feature.
|
|
|
|
|
|
- Please follow our convention for **naming** patches: [WorkingConventions/Darcs](working-conventions/darcs#).
|
|
|
- Please give the patch a **description** that (a) explains what the patch does, and (b) sketches how it works.
|
|
|
- Include updates to the **user manual** that documents your feature. The user manual is in the same repository as the main compiler source code, so the user-manual patch can form part of the main source-code patch.
|
|
|
- Make a **(separate) patch to the testsuite repository** that embodies your new tests. This has to be a separate patch, because the testsuite is a separate repository.
|
|
|
1. **Test your patch** using the [validation script](testing-patches), before you submit it.
|
|
|
1. **Submit your patch**. If you don't have write permission for the repository,
|
|
|
- Please follow our convention for **naming** commits: [WorkingConventions/Git](working-conventions/git#commit-messages).
|
|
|
- Please give the commit a **description** that (a) explains what the commit does, and (b) sketches how it works.
|
|
|
- Include updates to the **user manual** that documents your feature. The user manual is in the same repository as the main compiler source code, so the user-manual commit can form part of the main source-code commit.
|
|
|
1. **Test your commit** using the [validation script](testing-patches). Alternatively, you can let [Harbormaster](phabricator/harbormaster) build and validate your commit, see next step. (If you have write permission to the repository, then you **must** validate before pushing.)
|
|
|
1. **Submit a code review** to [Phabricator](phabricator). Wait for [Phabricator/Harbormaster](phabricator/harbormaster) to build and validate your commit (\~35 minutes, September 2014).
|
|
|
1. **Update the Trac ticket.**
|
|
|
|
|
|
- Use 'darcs send' to create a patch bundle
|
|
|
- Attach the patch bundle to the Trac report
|
|
|
- Add a comment to the Trac report to say what you've done
|
|
|
- Set the ticket status to 'patch', and if you are listed as owner then 'unassign' the ticket.
|
|
|
This shifts responsibility to the GHC team to review and commit your patch.
|
|
|
|
|
|
> >
|
|
|
> > If you do have write permission, then commit, update the Trac report, and close the ticket. **You must validate before pushing the patch**.
|
|
|
|
|
|
|
|
|
Then have a beer on us. We are truly grateful.
|
|
|
- Add a comment to say what you've done.
|
|
|
- Fill out the field called "[Differential Revisions](phabricator#linking-reviews-to-trac-tickets-and-vice-versa)". Syntax: `Phab:D123`.
|
|
|
- In the 'Action' part of the Trac ticket, select "Please review". This shifts responsibility to [the GHC team](team-ghc) to review and push your commit if it is accepted.
|
|
|
- Optional: if you did not manage to submit a code review to Phabricator for whatever reason, attach a patch bundle (run `git format-patch -n`, where *`n`* is the number of commits).
|
|
|
|
|
|
## Things to bear in mind
|
|
|
|
... | ... | @@ -39,14 +32,14 @@ Then have a beer on us. We are truly grateful. |
|
|
While we love new features, we think twice before incorporating them into GHC's main code base. Here are some things to bear in mind:
|
|
|
|
|
|
|
|
|
- Your patch does not need to be incorporated in the main GHC repository to be useful. The joy of Darcs is that you can send it to anyone, and they can use it quite independently.
|
|
|
- Your proposal does not need to be incorporated in the main GHC repository to be useful. The joy of Git is that you can send it to anyone, and they can use it quite independently.
|
|
|
|
|
|
- It may seem that running 'darcs apply' is practically free for us; you have done all the hard work. But it isn't:
|
|
|
- It may seem that running 'git push' is practically free for us; you have done all the hard work. But it isn't:
|
|
|
|
|
|
- It effectively commits us to maintaining it indefinitely, and worrying about its interactions with existing features
|
|
|
- We try hard to keep GHC's language design somewhat coherent. GHC deliberately tries to host a variety of ideas, not all of which may be good, but we try to keep it under control.
|
|
|
- We have to do quality-control on your patch; we don't want to commit un-maintainable code... or even well-written code that we can't understand.
|
|
|
- If your patch breaks something else, we'll get blamed regardless.
|
|
|
- We have to do quality-control on your proposal; we don't want to push un-maintainable code... or even well-written code that we can't understand.
|
|
|
- If your proposal breaks something else, we'll get blamed regardless.
|
|
|
- Subsequent new features have to take account of interactions with your feature.
|
|
|
|
|
|
- New features should be switchable with their own flag, by default off. We used to have just one flag `-fglasgow-exts` but nowadays we try to be much more selective.
|
... | ... | @@ -61,7 +54,7 @@ While we love new features, we think twice before incorporating them into GHC's |
|
|
system that is hard to learn, and complaints of the form "why doesn't it work like X?
|
|
|
I'm familiar with X!".
|
|
|
|
|
|
- Remember that GHC HQ is not heavily staffed! It may take us a while to give your patch the attention it deserves. However, if you hear nothing for a couple of weeks then please feel free to ping us, in case your patch has slipped through the cracks.
|
|
|
- Remember that GHC HQ is not heavily staffed! It may take us a while to give your proposal the attention it deserves. However, if you hear nothing for a couple of weeks then please feel free to ping us, in case your proposal has slipped through the cracks.
|
|
|
|
|
|
|
|
|
If you are working on a feature that you think you think is a candidate for including in GHC's main repository, you may want to talk to us while you are developing it. We may well, for example, have advice about how to structure the change in a way that we're happy to incorporate in our code base. |