scality / changelog-binder Goto Github PK

We want this repository to use Sphinx for its own documentation, as it will help for demonstrating the capabilities of the Sphinx plugin we will later develop.

The documentation should be structured as follows:

• Introduction
• Installation
• Usage
• Development
  • Reference
  • Design
  • Changelog

Given the idea behind changelog-binder, we should be able for every change to know in which version(s) it is included, hence also 'since' which version(s) it's included (e.g. by major.minor). It could be valuable to display this in a resulted rendering.

For users of the tool, it could be useful to have a generate subcommand which creates an (outline of) changelog fragment file, e.g., based on the last commit in the current working tree, or something along those lines.

Define the command-line tool skeleton (using Python and Click) and include unit testing (using pytest) and linting (using pylint and mypy). Also include packaging and minimal installation guide.

The command-line tool defined in #3 should first have sufficient capabilities to extract the list of changelog fragments from Git history.
For this purpose, we want to add a list subcommand, with the following behaviour:

• list --in X.Y.Z would return all fragments included before the X.Y.Z tag but after the most recent tag that comes before it (in terms of Git history)
• list --from A.B.C --to D.E.F would return fragments added after A.B.C and before D.E.F
• list --from X.Y.Z would return fragments added after X.Y.Z up to the current HEAD
• list would return fragments added after the most recent tag

This subcommand would output filenames at first, additional output formats could be added in the future (e.g. showing in which version such file was added, the date of first addition, of last modification, ...)

Building on the list subcommand introduced in #4, we want to add the ability to generate a changelog / release notes from a list of fragments.

To select which fragments to include in the generated document, the same options as the list subcommand will be used.
To control the output contents and format, the following options will be added:

• --release-notes will filter fragments to only include ones tagged with :release-notes:
• --kind $KIND will filter fragments tagged with :kind: $KIND, where $KIND can be one of Feature, Bugfix, or Improvement (more kinds may be added in the future); this option can be used more than once - not specifying it implies all kinds are included
• --epic $EPIC works similarly to the kind filter described above, but not specifying it allows to also include fragments without any :epic: specified; a --no-epic flag will be provided to only select such fragments
• --output $FMT will allow to control the format of the generated document, akin to many existing command-line tools (e.g. kubectl); the only supported format in this initial implementation will be reStructuredText

In this issue, we will not consider automatic retrieval of pull request information.

Define the rationale, constraints, rejected approaches, proposed solution, implementation strategy and test plan for the changelog-binder command-line tool and Sphinx plugin.