-
Notifications
You must be signed in to change notification settings - Fork 91
AddingPackages HowTo
So you want to propose a package to be included in the Haskell Platform.
You should first read the policy on adding packages. This "how to" guide gives extra practical advice.
You're expected to become an advocate for the package. You'll have to spend a little time writing the proposal (though hopefully not too long) and time responding to questions on the mailing list.
In the simplest case there is just one package maintainer and they also write the proposal, but it doesn't have to be that way. You can have a whole team of people, for example you might have a team of maintainers and enthusiastic users who write the proposal together and advocate the package when it gets discussed on the mailing list.
The only strict requirement is that the proposal must have the support of the maintainers of the package. We'd all look pretty silly if we accepted a package but then there was nobody prepared to maintain it!
You're free to use whatever structure suits the package you're proposing. Keep in mind the key point about the proposal:
> The proposal forms the nub of the argument for why the package should be included in the Haskell Platform. It should contain or link to enough information so that reviewers can make an informed decision on whether the package should be accepted.
If you like, you can use this outline to get started:
- Credits
- Abstract
- Rationale
- Introduction to the API
- Important design decisions
- Open issues
There's an example proposal for the 'tar' package to give you some ideas.
Header matter
Start by adding a title at the top of the document.
We suggest adding a bit of boilerplate to tell reviewers what is expected of them.
Obviously, you should stick in the real discussion deadline that the [Members#ReleaseTeam|release]] have announced.
Credits
List the author (that's you!) and the maintainers (perhaps that's also you!).
If the proposal is accepted then this section will be updated with the list of people who helped with the review.
Abstract
Next write a 2-3 sentence abstract explaining what the package does. You can usually just copy the description section of your package's Cabal file.
Add a link to the Hackage page for your package. If your package has a dedicated home page then add a link for that too. If you expect that reviewers will need to use the development version of your package, rather than a release tarball, then add a link to the source repo.
If your proposal depends on another existing proposal getting accepted then you should note that somewhere.
Rationale example
The rationale is the core of your argument as to why this package should be added to the platform. Your task here is to convince people. What makes the package useful? What are the use cases? Being able to point to existing uses is always good. Similarly, existing comments or reviews from users can be helpful. Old release announcements can be a good source of inspiration here.
If your package is a replacement for an existing package (or part of one) then you'll want to convince people why the new one is an improvement.
Introduction to the API example
Next, for library packages, you want to give the reviewers a feel for how the thing is supposed to be used. You have quite a bit of flexibility in how you do this. The obvious choice is to make use of existing examples and introductory documentation. For example your package's website (if it's got one) or haddock API docs might have some introduction, an explanation of key concepts or examples. Other good sources might be stuff from release announcements, mailing list posts, blog posts, wiki pages or demo programs. Depending on the existing sources, you might decide they fit the task fine in which case you can link to them directly, otherwise copy the stuff into the proposal and edit it to make it coherent.
In the example 'tar' proposal, the "Introduction to the API" section is mostly copied from the package's API docs with just a bit of re-editing.
Of course, if you end up making something new for the proposal then it'd be great to keep it somewhere so that new users can benefit from it too. The obvious place is in the Haddock docs, or a project website.
Important design decisions example
Next try to list the major design decisions. There's no definite list of which decisions should go in this section. Rather, the goal is to help the reviewers do a good job. Try explaing decision that you think will help people when reviewing your package. It is difficult for people to review a code base they're unfamiliar with, so knowing the broad strokes of the design will help them a lot.
You can also try to preempt questions regarding the design that are likely to come up by explaining the design up front. If you have already documented the design in a separate document or paper then feel free to link to it or to copy pieces from there into the proposal.
Open issues example
Finally, add a section for open issues. This section may be empty initially or contain questions you want the reviewers to consider.
Once you are happy with what you've written for the proposal, the next step is to get it onto the wiki. For this you will need an account. Currently the haskell-platform wiki is open for anyone to register. Once you have registered and logged in then you can create and edit wiki pages.
There is a standard place to put package proposals: in the wiki on a page named Proposals-$pkgname
For example, the `tar` package proposal would live here: Proposals-tar
Paste in the content of the proposal you have written. You can use wiki markup for things like section headers, links and code examples.
You should also be sure to add a link to your package proposal from the list of proposals.
The Haskell libraries mailing list is where package proposals are discussed. You have to be subscribed to be able to post to the mailing list, so make sure that you and anyone helping you with the proposal is subscribed.
The email should be the same content as what you pasted in the wiki page, though you may need to format things slightly differently to look sensible in an email. The only difference is that the email should have a link to the wiki page, so that people can always find the latest version of your proposal, rather than having to trawl through a long mailing list thread.
The email for the example proposal would start like this:
There is a window in each release cycle for discussing new packages. The release team will announce the deadlines. There's a deadline for you to send in your proposal and then a later deadline for the end of the discussion period.
There is no earliest time you can send in your proposal however, so go, send your proposal!
As an advocate for the package you're expected to help the reviewers by answering questions they ask on the mailing list. You also remain in charge of the proposal and have the job of updating the proposal in response to things raised in the discussion.
Often it will make sense to incorporate answers to reviewers' questions into the proposal itself. If there isn't an obvious place in the proposal to put the answer then you might like to just stick them into a Q&A section.
Issues and complaints raised by reviewers should be tracked, for example in an "open issues" section. A simple way to do this is to give a one-sentence summary and link to the mailing list post where the issue was raised. A member of the steering committee might help you out with this, especially if the decision seems like it's going to be controversial. You're not expected to fix everything reviewers ask for, or to fix things straight away, but it would be helpful to indicate which issues you think can and should be addressed.
Ultimately, the criteria to get your package accepted is that the reviewers come to a consensus and agree to accept it. Sometimes reviewers will disagree with each other or with you. See the suggestions on how to achieve consensus. Keep in mind that it is OK to get a consensus for conditional acceptance, where you or the maintainers promise to make certain changes before the package gets included into a release.
If your package is accepted then you need to make a couple final updates to the proposal:
* You need to note that it was accepted and to link to the mailing list discussion where it was accepted. * You need to credit the reviewers who made significant contributions to the review process.
Just as you deserve prominent credit in the proposal, for the effort of writing it and guiding it through the discussion process, the reviewers deserve credit for putting effort into reviewing the package. Giving proper credit to both the proposal authors and the reviewers is part of the incentives for these people to volunteer their time for the benefit of the community.
Isn't this proposal business a lot of work?
You can get someone to help you! It is fine to have several authors of a proposal and they do not all need to be maintainers of the package. Get some of your more enthusiastic users to help you.
The reason for the proposal is to make life easier for the people reviewing your package. Remember, the reviewers are volunteers too and we'd like them to be able to come to an informed decision. Also, detailed review is a great way of improving your package. So there's something in it for you too, be positive! :-)
How long should the proposal be, how much detail should there be?
Keep in mind that reviewers will ask questions and that the answers to sensible questions should be incorporated into the proposal (the format is up to you but you might like to use a Q&A section). So you can speed the review process by addressing the obvious points that you think reviewers will bring up. If you're not sure, take a look at existing proposals and ask someone to read your proposal over before sending it in.
It says my package has to work on platform X but I don't have any access to platform X!
Don't worry, neither do I! You're not expected to have personal access to every operating system that the Haskell Platform targets. You can get help from other hackers who do have access. If this is the only thing holding you up then submit the proposal anyway and ask the reviewers nicely if someone could please check that it works on this particular platform. This is easier of course if your package has tests or a demo program they can check.