Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
follow header conventions #3
I maintain the Emacsmirror a mirror of Emacs packages here at github.
Eventually I want to provide a package manager which uses this mirror. This package manager is far from ready but it can already display a list of available packages and details about a package; similar to
Since I mirror more than 3000 packages I can not maintain the package metadata manually like the maintainers of
Unfortunately many maintainers do not follow these conventions at all or not close enough for these extraction tools to work properly.
I mirror about 800 packages from github among which 120 do not follow the most important convention: how the summary line has to be formatted.
For these 120 packages I am currently creating patches and submitting pull requests like this one.
In some cases I also corrected some other problems concerning the library header and/or deleted trailing whitespace. If I did not fix anything but the summary line please don't assume that the rest of the header is 100% correct; you might still want to improve it.
Also note that if you maintain additional packages I might not have created such a pull request for them even when they fail to follow the header conventions closely enough. I do so only (at this point) if the summary line can not be parsed. So please fix the headers of other libraries yourself.
Please read the official Header Conventions. Note that while creating this patch I tried to preserve your personal header style while following these conventions as closely as required by the extraction tools. You might want to further improve the header.
Here are some additional notes.
(To save some time I created this generic pull request message which mentions some common problems which might not all apply to this package. So please forgive me if some of this is not relevant to you.)
This has to be on the first line, there are three semicolons and three dashes. The library name has to match the filename (therefor it ends with
If you also define local variables using
There is not reason for
If the summary is rather long do not split it into two lines, the extraction tools fail to parse that. Instead make them shorter, which is also useful when the summary is displayed when listing packages or elsewhere.
Don't worry if the summary line is longer than 74 or 80 characters; what matters is the length of the summary sans the leading filename. It's probably a good idea for the summary to be no longer than ~30-40 characters (or even less) - but again if you can't make it this short without losing essential information don't worry to much.
can probably be abbreviated as:
Move the longer description to the Commentary section.
Also please make the summary useful to people who don't have the necessary domain knowledge. E.g. they should be able to tell from the summary that the package implements a major mode for some obscure programming language they have never heard of before and therefor is not of interest to them.
This begins with three dashes and ends with a colon.
The first sentence or paragraph should repeat the information from the summary line. Try to be brief but use whole sentences - this isn't the summary line, we have enough room.
If you feel the need to provide installation instructions preferably do so toward the end of the commentary section.
You might even want to create a separate section for the installation instructions. This breaks with the header conventions (or at least isn't mentioned there) but has the advantage that tools that extract the commentary won't include the installation instructions. And that is useful because these tools are commonly used to extract information for the benefit of a package manager, so the generic instructions would actually be incorrect because installation happens with something like
In any case do not only provide the installation instructions. At the very least duplicate the summary line at the beginning of the commentary section.
Also if your installation instructions are as generic as in the example above consider dropping them completely. This is common knowledge and for a complete beginner who never installed a package before yours (how likely is that?) this isn't enough information anyway (what is that
Maintainer and Author Header Lines
The convention requests both to be specified. In my opinion you can omit
Multiple authors can be specified but only one maintainer. Note that you can't use
Please consider not obfuscation the email address and wrap it with
Don't forget to provide the appropriate feature. The
This comment has been minimized.
This comment has been minimized.Show comment Hide comment
Yes, please accept this pull request -- it will allow the inclusion of an automatically-built maxframe package in the Melpa package repository (http://melpa.milkbox.net). It looks like someone has already hacked a version of maxframe for upload to Marmalade, but it would be very much better if that were not necessary.