Best Practices for Publishing Mercurial Extensions

So you've just written a high-quality, general-purpose Mercurial extension that you want to share with the world. Follow the guidelines on this page to make life easier for you, easier for people who want to use your extension, and easier for other developers who might want to contribute changes.

For concreteness, I'll pretend your extension is called foo.

Guidelines

1. Keep the source code for your extension in a Mercurial repository: one extension per repository, one repository per extension. (Even if you are the author of 17 brilliant extensions, I might only be interested in one of them. Of course, if you have extensions that depend on each other, you might want to ignore this advice.)

   Name the repository after the extension. One common convention is to prepend hg-, e.g. hg-foo. That will clearly distinguish your repository from other projects that happen to be called foo.

2. Create a public cloneable repository of your extension's source code. If you don't have a personal or company web server for hosting public Mercurial repositories, there are many hosting services available, e.g. bitbucket.org, sourceforge.net. Make it clear who maintains the code and where issues should be reported. A public bug tracker is a good idea.

3. Add a page FooExtension to the Mercurial wiki. Use the Extension Template to guide you. Be sure to link to your public repository as follows:

   Repository: http://hg.example.com/hg-foo

   And make sure that your page ends with

   ----
   CategoryExtensionsByOthers

   so that it is visible in that category page.

4. Edit UsingExtensions and link to your page.

What not to do

• Please don't add your source code as a wiki attachment. That sort of misses the whole point of using a version-control system like Mercurial: how do I tell you what version I'm using if I find a bug? How do you create new versions?