Document changelog process

develop
lethosor 2018-04-02 22:22:20 -04:00
parent 26fb047aef
commit 374243d697
6 changed files with 69 additions and 3 deletions

@ -32,7 +32,8 @@ How to get new code into DFHack
(i.e. not the master or develop branch of your fork). (i.e. not the master or develop branch of your fork).
* If possible, compile on multiple platforms when changing anything that compiles * If possible, compile on multiple platforms when changing anything that compiles
* It must pass CI - run ``python travis/all.py`` to check this. * 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 * Create a GitHub pull request once finished
* Submit ideas and bug reports as :issue:`issues on GitHub <>`. * Submit ideas and bug reports as :issue:`issues on GitHub <>`.
Posts in the forum thread can easily get missed or forgotten. Posts in the forum thread can easily get missed or forgotten.

@ -666,6 +666,20 @@ Then close that Admin ``cmd.exe``, re-open another Admin ``cmd.exe``, and run::
pip install sphinx 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 Misc. Notes
=========== ===========

@ -8,6 +8,11 @@
Development Changelog 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:: .. contents::
:depth: 2 :depth: 2

@ -8,6 +8,11 @@
Changelog 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:: .. contents::
:depth: 2 :depth: 2

@ -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 # Future
=== Leave this section blank === Leave this section blank

@ -53,8 +53,21 @@ def parse_changelog():
entries = [] entries = []
with open('docs/changelog.txt') as f: with open('docs/changelog.txt') as f:
multiline = ''
for line_id, line in enumerate(f.readlines()): for line_id, line in enumerate(f.readlines()):
line_id += 1 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('==='): if not line.strip() or line.startswith('==='):
continue continue
@ -72,8 +85,6 @@ def parse_changelog():
last_entry = ChangelogEntry(line.strip(), cur_section, last_entry = ChangelogEntry(line.strip(), cur_section,
cur_stable, cur_dev) cur_stable, cur_dev)
entries.append(last_entry) entries.append(last_entry)
# entries.setdefault(cur_stable, []).append(last_entry)
# entries.setdefault(cur_dev, []).append(last_entry)
elif line.lstrip().startswith('-'): elif line.lstrip().startswith('-'):
if not cur_stable or not cur_dev: if not cur_stable or not cur_dev:
raise ValueError( raise ValueError(