Document changelog process

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.

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
 ===========
 

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
 

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
 

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

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(