# releasenotes

Contents

- Description
- Commands
  - Change navigation

generate release notes from commit messages (EXPERIMENTAL)

# Description

It is common to maintain files detailing changes in a project between releases. Maintaining these files can be difficult and time consuming. The `hg releasenotes` command provided by this extension makes the process simpler by automating it.

# Commands

## Change navigation

### releasenotes

parse release notes from commit messages into an output file:

    hg releasenotes [-r REV] [-c] FILE

Given an output file and set of revisions, this command will parse commit messages for release notes then add them to the output file.

Release notes are defined in commit messages as ReStructuredText directives. These have the form:

    .. directive:: title

       content

Each `directive` maps to an output section in a generated release notes file, which itself is ReStructuredText. For example, the `.. feature::` directive would map to a `New Features` section.

Release note directives can be either short-form or long-form. In short- form, `title` is omitted and the release note is rendered as a bullet list. In long form, a sub-section with the title `title` is added to the section.

The `FILE` argument controls the output file to write gathered release notes to. The format of the file is:

    Section 1
    =========

    ...

    Section 2
    =========

    ...

Only sections with defined release notes are emitted.

If a section only has short-form notes, it will consist of bullet list:

    Section
    =======

    * Release note 1
    * Release note 2

If a section has long-form notes, sub-sections will be emitted:

    Section
    =======

    Note 1 Title
    ------------

    Description of the first long-form note.

    Note 2 Title
    ------------

    Description of the second long-form note.

If the `FILE` argument points to an existing file, that file will be parsed for release notes having the format that would be generated by this command. The notes from the processed commit messages will be merged into this parsed set.

During release notes merging:

- Duplicate items are automatically ignored
- Items that are different are automatically ignored if the similarity is greater than a threshold.

This means that the release notes file can be updated independently from this command and changes should not be lost when running this command on that file. A particular use case for this is to tweak the wording of a release note after it has been added to the release notes file.

The -c/--check option checks the commit message for invalid admonitions.

The -l/--list option, presents the user with a list of existing available admonitions along with their title. This also includes the custom admonitions (if any).

Options:

`-r, --rev <REV>`
| revisions to process for release notes
`-c, --check` | checks for validity of admonitions (if any)
`-l, --list` | list the available admonitions with their title