Writing Down Your Improvement Proposal On The Wiki

1. When to make an improvements proposal

We write down "Plan" wiki page to track discussion, progress and evolution of largish enhancement proposal to Mercurial. Not all proposal go through a "Plan" wiki page some just get directly sent as patches, get solved in a simple email thread or discussed on the bug tracker. Here is a small list of reason why one might want to create a wiki page for a project:

• it involves some complicated design (like a binary format) that will receive multiple revision,
• it requires multiples independent steps that will get done gradually over a long period of time,
• it creates large amount of debate that justify to keep track of various dimension of the problem space and there solutions,
• it is a long term project that is not going to be implemented shortly but which surface often enough that we want to keep track of various idea,

• <insert your other good reason here>.

2. How to make improvements proposal

1. The title of the page should end with Plan

2. The page should have the CategoryNewFeatures and CategoryDeveloper (see DirstateFormatImprovementPlan for an example)

3. Example Source

    #pragma section-numbers 2

    <<Include(A:dev)>>

    = Feature Title =

    '''Status: Project'''

    '''Main proponents: YourNameHere'''

    /!\ This is a speculative project and does not represent any firm decisions on future behavior. 

    Add a short summary of the idea here.

    == Goal ==

    Explain what kind of problem are triggering this idea, why it is worth solving and the big picture of how you'll solve it.


    == Detailed description ==

    All kind of stuff can go here, solution description / alternative solution etc

    == Roadmap ==

     * (./) various
     * (./) step
     * {x} That
     * {x} need
     * {x} to
     * {x} be
     * {x} performed

    == Roadmap ==

     * Gather history rewriting function into a core module and get commands to use it,
     * expose an API to build and submit a `plan`,
     * use this `plan` as the on disk representation for in progress operation,
     * have a UI for the user to edit a `plan` (this will eventually replace histedit),
     * expose UI to execute a `plan` step by step / have an option for commands to just schedule the `plan`,
     * add some "preview" capability to the plan.

    == See Also ==

     * pointer
     * to
     * related
     * page