|
⇤ ← Revision 1 as of 2011-04-04 13:19:07
Size: 1904
Comment: new page
|
Size: 2005
Comment: Add advices for bug tracker and UsingExtensions
|
| 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 maintain 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
- 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.
- 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 maintain the code and where issues should be reported. A public bug tracker is a good idea.
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.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?