Differences between revisions 1 and 3 (spanning 2 versions)
Revision 1 as of 2011-04-04 13:19:07
Size: 1904
Editor: GregWard
Comment: new page
Revision 3 as of 2012-07-19 16:47:05
Size: 2006
Editor: GregWard
Comment:
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:

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.
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.
Line 12: Line 7:
 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`.
Line 13: Line 10:
  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.)
 1. 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, code.google.com. Make it clear who maintains the code and where issues should be reported. A public bug tracker is a good idea.
Line 19: Line 12:
  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`.

  1. 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,
  code.google.com.

  1. Add a page `FooExtension` to the Mercurial wiki. Use the
  ExtensionTemplate to guide you. Be sure to link to your public
  repository as follows:
  {{{
 1. Add a page `FooExtension` to the Mercurial wiki. Use the ExtensionTemplate to guide you. Be sure to link to your public repository as follows:
 {{{
Line 33: Line 16:
  And make sure that your page ends with
  {{{
 And make sure that your page ends with
 {{{
Line 38: Line 21:
  so that it is visible in that category page.  so that it is visible in that category page.

 1. Edit UsingExtensions and link to your page.
Line 41: Line 26:

 
* 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?
 * 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?

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, code.google.com. 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 ExtensionTemplate 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?

PublishingExtensions (last edited 2016-01-20 16:37:15 by MartijnPieters)