[IPython-dev] documenting what's new in the repo

Paul Ivanov pi at berkeley.edu
Mon Aug 19 19:52:24 EDT 2013

Hey gang,

We've been getting better about documenting the What's New
changeset as we go along lately (instead of doing it from memory
around release time), but in doing so, have discovered that it's
actually hard to do this without getting merge conflicts any time
you have multiple PR which start off with the same ancestor, with
both editing the what's new file in the same place.

Thomas Kluyver and I tried a few things: adding identical marker
lines around a commit, adding only to the top of a file with a
bunch of blank line context, but none of those worked. We then
asked Matthew Brett for ideas, and he suggested we just have a
whatsnew.d/ directory to hold files with descriptions of the
changesets. We just talked this over during lunch with Fernando,
it seems fairly clean and will work, we'll just have to write a
little script when we get a bunch of such files in the whatsnew.d
directory, which will collapse them all together, add them to the
what's new *file*, and delete the contents of whatsnew.d

Given that we already have a whatsnew directory, which is where
development.rst current lives, I decided to name the new
directory pr, so docs/source/whatsnew/pr is the place where new
PRs should add a file which documents new features, as well as
backwards incompatible ones. For backwards incompatible changes,
use the incompat- prefix for a filename.

In a self-referential strange loop, I've opened a PR which
documents this proposed scheme while using it. See here:

                  / \
                A*   \^   -
             ,./   _.`\\ / \
            / ,--.S    \/   \
           /  `"~,_     \    \
     __o           ?
   _ \<,_         /:\
--(_)/-(_)----.../ | \
Paul Ivanov

More information about the IPython-dev mailing list