/astropy-changelog

Utility for managing the astropy changelog (demo)

Primary LanguagePythonBSD 2-Clause "Simplified" LicenseBSD-2-Clause

astropy-changelog: utility for managing the astropy changelog (demo)

This is a proof of concept (POC) for changing the basis of the astropy changelog from the CHANGES.rst file to a new CHANGES.yml file. The driver for this and initial discussions were captured in an astropy-dev email thread in Oct 2016 (subject "Proposal for a new changelog system").

An important point to note is that the current code strives to maintain smooth compatibility with the current CHANGES.rst as a source for users and developers to understand astropy changes.

However, once we have transitioned to a YAML structured representation then there are numerous possibilities for using this far more effectively and providing much better ways to present and discover this information. One simple idea is to break up the output RST file by version, e.g. CHANGES-4.0.rst, CHANGES-3.2.1.rst, and so on. This is not currently practical because change entries commonly apply to multiple versions.

Overview

The key element of this POC is the script convert_changelog.py. It can handle the following:

  • Read a changelog from the legacy CHANGES.rst RST format and convert into a structured data changelog object (list of change entries, where each entry is a dict).
  • Read a changelog from the new CHANGES.yml YAML format directly into a structured changelog object.
  • Write a structured changelog object to YAML.
  • Write a structured changelog object into the legacy RST format. One key difference is that it does not preserve the empty subpackage entries, e.g. when there are no bug fixes for a particular subpackage, that is simply not reported.

The changelog YAML file contains four documents:

  • Instructions for developers to add a changelog entry
  • Template that they use
  • Release dates (needed to generate the RST legacy format)
  • Change entries

Envisioned process for astropy package maintainers

The envisioned process is to convert from CHANGES.rst to CHANGES.yml and then convert back to RST to verify that the YAML representation accurately captures the original changelog:

./convert_changelog.py CHANGES.rst CHANGES.yml
./convert_changelog.py CHANGES.yml CHANGES_new.rst

# Diff the two, preferably using a graphical diff too.  opendiff works well on Mac.
opendiff CHANGES.rst CHANGES_new.rst

At this point CHANGES.yml becomes the official source of changes and CHANGES.rst is a derived product that is generated (by some TBD process) with:

./convert_changelog.py CHANGES.yml CHANGES.rst

Process for astropy core contributors

The goal is that the instructions in the CHANGES.yml file are clear and self-contained, and that merge conflicts will be avoided by placing new change entries at a quasi-random location within the file.

Example files

To allow looking at the files in a manageable form, this repo includes a chopped down version of the astropy changelog as changes_test.rst. From there:

./convert_changelog.py changes_test.rst changes_test.yml
./convert_changelog.py changes_test.yml changes_test_new.rst
./convert_changelog.py --line-width=80 changes_test.yml changes_test_new-80.rst