/!\ 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://foozy@bitbucket.org/foozy/hgext-skeleton.

1. Tasks

Tasks that we should do.

2. What the skeleton should (not) include

The skeleton extension should include:

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:

3. Steps to start writing extension

"skeleton extension" assumes steps below to start writing extension with it.

  1. get and extract recent archive of "skeleton extension"
  2. rename "myfirstextension.py" in extracted archive as you like
  3. write actual logic of your own extension
  4. get recent source tree of Mercurial ("hg clone" or "archive + exract")
  5. write specific tests (optional)
  6. 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:

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

CategoryDeveloper CategoryNewFeatures

SkeletonExtensionPlan (last edited 2016-03-31 08:30:02 by KatsunoriFujiwara)