This page is primarily intended for Mercurial's developers.
Skeleton Extension Plan
Status: In progress
Main proponents: KatsunoriFujiwara
This page mainly focuses on "skeleton extension" proposed by Matt as issue4677.
"skeleton extension" prototyping repository is available at https://firstname.lastname@example.org/foozy/hgext-skeleton.
Tasks that we should do.
- make (or confirm) tools available to out of Mercurial source tree
hghave (insensibility is also needed)
- create files of "skeleton extension"
- write explanation about the skeleton extension itself in wiki
- start "snippets for extension" repository
2. What the skeleton should (not) include
The skeleton extension should include:
COPYING of GPL (v2+?) as a sample
README.rst about "myfirstextension" as a sample
Makefile that knows how to use run-tests out of the core repo
setup.py for "single file" extension as a sample
__init__.py copied from Mercurial source
myfirstextension.py file as a sample
- example setting of testedwith and buglink
- a GPL copyright header with a pointer to the LicenseFAQ
- a note about API guarantees and a pointer to MercuringAPI
README.rst to explain how to run tests
hghaveaddon.py as a sample to add custom hghave feature
- test scripts that use worthy tools of the core repo
test-check-code.t using contrib/check-code.py
test-check-commit.t using contrib/check-commit
test-check-py3-compat.t using contrib/contrib/check-py3-compat.py
test-check-pyflake.t using tests/filterpyflakes.py
test-module-imports.t using contrib/import-checker.py
Every "README" files are written in RST (reStructuredTex) syntax and have ".rst" suffix, because (1) help document in Mercurial core is written in RST syntax and (2) explicit ".rst" suffix of them might cause well formatted page on repository hosting site (for example, Bitbucket does so)
On the other hand, it shouldn't included:
README about the skeleton extension itself => wiki
explanation about how to write extension => wiki
explanation about how to write test => wiki
setup.py and sample for "multiple files" extension => developer, who implements such extension, should know what to do for it
3. Steps to start writing extension
"skeleton extension" assumes steps below to start writing extension with it.
- get and extract recent archive of "skeleton extension"
- rename "myfirstextension.py" in extracted archive as you like
- write actual logic of your own extension
- get recent source tree of Mercurial ("hg clone" or "archive + exract")
- write specific tests (optional)
- execute (bundled and/or specific) tests with run-tests.py of (4) above
Developer shouldn't clone from "skeleton extension" repository, because cloned repository (= custom extension) has same root with the source of cloning (= "skeleton extension"). This causes serious problem at distinction between repositories.
By default, "hg" command found in PATH is used to run tests via make.
Mercurial source tree is needed to use recent tools for tests bundled with the skeleton extension. Therefore, developer shouldn't get it, if they don't want to write/run any test, even though extension without any test isn't recommended
4. Snippets for extension
There are many many tips for writing extension. For example:
- add new command
- receive argument
- receive option
- flag option
- value option
- multi-value option
- wrap existing command
- wrap command define in Mercurial core (excluding bundled extension)
- wrap command define in another extension
- add options to existing command
- writing help document
- special command types
- add new command
- wrap function defined in Mercurial core (excluding bundled extension)
- warp function defined in another extension
- basic tips
- refer history
- refer configuration
- refer status in the working directory
- read/write meta data files
- read/write files in the working directory
- extend object
- extend 'repo' object
- extend 'ui' object
- lock (wlock/slock)
- "unfinished" state
- check arguments of function
- check existence of property
It is impossible to explain (almost) all of them in single extension or single wiki page.
Therefore, we need to create another repository to collect worthy snippets. For example, a repository consisting of pairs of simple "extension" for a tip and "test script" of that extension.
(need more discussion about this)
5. Future plans
- integrate into Mercurial source tree (maybe, under contrib ?)
- the source tree of the skeleton extension
- the source tree of snippets for extension
- run tests for snippets as a part of Mercurial test set. (this can examine validity of snippets immediately)
- accept patches for snippets via Mercurial devel-ml
- put "how to start with skeleton extension" document into help/internal
- put "how to write extension" document into help/internal (?)
- put "how to write test" document into help/internal (?)