From 374243d697de92dadbe60da77a1519b79aa15836 Mon Sep 17 00:00:00 2001 From: lethosor Date: Mon, 2 Apr 2018 22:22:20 -0400 Subject: [PATCH] Document changelog process --- Contributing.rst | 3 ++- docs/Compile.rst | 14 ++++++++++++++ docs/NEWS-dev.rst | 5 +++++ docs/NEWS.rst | 5 +++++ docs/changelog.txt | 30 ++++++++++++++++++++++++++++++ docs/gen_changelog.py | 15 +++++++++++++-- 6 files changed, 69 insertions(+), 3 deletions(-) diff --git a/Contributing.rst b/Contributing.rst index 2c1e7bb45..59ff8285f 100644 --- a/Contributing.rst +++ b/Contributing.rst @@ -32,7 +32,8 @@ How to get new code into DFHack (i.e. not the master or develop branch of your fork). * If possible, compile on multiple platforms when changing anything that compiles * It must pass CI - run ``python travis/all.py`` to check this. -* Update ``NEWS.rst`` and ``docs/Authors.rst`` when applicable. +* Update ``changelog.txt`` and ``docs/Authors.rst`` when applicable. See + `build-changelog` for more information on the changelog format. * Create a GitHub pull request once finished * Submit ideas and bug reports as :issue:`issues on GitHub <>`. Posts in the forum thread can easily get missed or forgotten. diff --git a/docs/Compile.rst b/docs/Compile.rst index 74ffb4078..54d9c21c8 100644 --- a/docs/Compile.rst +++ b/docs/Compile.rst @@ -666,6 +666,20 @@ Then close that Admin ``cmd.exe``, re-open another Admin ``cmd.exe``, and run:: pip install sphinx +.. _build-changelog: + +Building the changelogs +----------------------- +If you have Python installed, but do not want to build all of the documentation, +you can build the changelogs with the ``docs/gen_changelog.py`` script. + +All changes should be listed in ``changelog.txt``. A description of this file's +format follows: + +.. include:: /docs/changelog.txt + :start-after: ===help + :end-before: ===end + Misc. Notes =========== diff --git a/docs/NEWS-dev.rst b/docs/NEWS-dev.rst index 68c16d272..7a9da7cb7 100644 --- a/docs/NEWS-dev.rst +++ b/docs/NEWS-dev.rst @@ -8,6 +8,11 @@ Development Changelog ##################### +This file contains changes grouped by the release (stable or development) in +which they first appeared. See `build-changelog` for more information. + +See `changelog` for a list of changes grouped by stable releases. + .. contents:: :depth: 2 diff --git a/docs/NEWS.rst b/docs/NEWS.rst index 506999280..22f9881b9 100644 --- a/docs/NEWS.rst +++ b/docs/NEWS.rst @@ -8,6 +8,11 @@ Changelog ######### +This file contains changes grouped by the stable release in which they first +appeared. See `build-changelog` for more information. + +See `dev-changelog` for a list of changes grouped by development releases. + .. contents:: :depth: 2 diff --git a/docs/changelog.txt b/docs/changelog.txt index b413237ed..d59930998 100644 --- a/docs/changelog.txt +++ b/docs/changelog.txt @@ -1,3 +1,33 @@ +===[[[ +===help + +Entries in docs/NEWS.rst and docs/NEWS-dev.rst are generated from +docs/changelog.txt. NEWS.rst groups entries by stable releases, and NEWS-dev.rst +groups them by all releases (stable and development). For example, an entry +listed under "0.44.05-alpha1" in changelog.txt will be listed under that in +NEWS-dev.rst as well, but under "0.44.05-r1" in NEWS.rst (assuming that is the +closest stable release after 0.44.05-alpha1). An entry listed under a stable +release in changelog.txt will be listed under that release in both NEWS.rst and +NEWS-dev.rst. + +changelog.txt uses a syntax similar to RST, with a few special sequences: + +- ``===`` indicates the start of a comment +- ``#`` indicates the start of a release name (do not include "DFHack") +- ``##`` indicates the start of a section name (this must be listed in ``gen_changelog.py``) +- ``-`` indicates the start of a changelog entry. **Note:** an entry currently must be only one line. +- ``:`` (colon followed by space) separates the name of a feature from a description of a change to that feature. + Changes made to the same feature are grouped if they end up in the same section. +- ``:\`` (colon, backslash, space) avoids the above behavior +- ``- @`` (the space is optional) indicates the start of an entry that should only be displayed in NEWS-dev.rst. + Use this sparingly, e.g. for immediate fixes to one development build in another development build that + are not of interest to users of stable builds only. +- Three ``[`` characters indicate the start of a block (possibly a comment) that + spans multiple lines. Three ``]`` characters indicate the end of such a block. + +===end +]]] + ================================================================================ # Future === Leave this section blank diff --git a/docs/gen_changelog.py b/docs/gen_changelog.py index 189591c1f..fcc6cb1f2 100644 --- a/docs/gen_changelog.py +++ b/docs/gen_changelog.py @@ -53,8 +53,21 @@ def parse_changelog(): entries = [] with open('docs/changelog.txt') as f: + multiline = '' for line_id, line in enumerate(f.readlines()): line_id += 1 + + if multiline: + multiline += line + elif '[[[' in line: + multiline = line + + if ']]]' in multiline: + line = multiline.replace(']]]', '') + multiline = '' + elif multiline: + continue + if not line.strip() or line.startswith('==='): continue @@ -72,8 +85,6 @@ def parse_changelog(): last_entry = ChangelogEntry(line.strip(), cur_section, cur_stable, cur_dev) entries.append(last_entry) - # entries.setdefault(cur_stable, []).append(last_entry) - # entries.setdefault(cur_dev, []).append(last_entry) elif line.lstrip().startswith('-'): if not cur_stable or not cur_dev: raise ValueError(