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.

• make (or confirm) tools available to out of Mercurial source tree

  • run-tests.py

  • hghave (insensibility is also needed)

  • contrib/check-code.py

  • contrib/check-commit

  • contrib/contrib/check-py3-compat.py

  • contrib/import-checker.py

  • tests/filterpyflakes.py

• create files of "skeleton extension"

  • .hgignore

  • COPYING

  • README.rst

  • Makefile

  • setup.py

  • hgext3rd

    • __init__.py

    • myfirstextension.py

  • tests

    • README.rst

    • hghaveaddon.py

    • test-check-code.t

    • test-check-commit.t

    • test-check-py3-compat.t

    • test-check-pyflake.t

    • test-module-imports.t

• 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:

• .hgignore

• 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

• hgext3rd

  • __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

• tests

  • 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.

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:

• command
  • 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
    • no-repo
    • optional-repo
• function
  • 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
• consistency
  • lock (wlock/slock)
  • transaction
  • dirstateguard
  • "unfinished" state
• hooks
• portability
  • 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 (?)

CategoryDeveloper CategoryNewFeatures