Towards better Changes (1)

In order to produce a more helpful Changes file for my modules and applications (primarily for me first, and then for others), aside from the usual advice found on the web like:

  • Geared towards humans (users)
  • NOT a commit log
  • Tell user whether or not she should upgrade (and when)
  • List potential backward incompatibility (removed features, renamed stuffs)
  • List new/improved features
  • Reference each entry with associated issue tracker ID, if any (e.g. GH#123 for Github, RT#12345 for rt.cpan.org, and so on)
  • Categorize by the nature of the changes (new/enhancements, bug fixes, internal, documentation, and so on)

I’m trying to keep in mind about these two things.

Reason, reason, reason (a.k.a. why, Why? WHY???)

When something is added (and more importantly, when something is removed or renamed), there is usually a reason. Unfortunately, I forget easily. And more unfortunately, I often change my mind. A reason that might be sound at one time, might not be in a later time (and then might again be in a future time). If I didn’t write down the reason I did something, and then forget, I might revert a potentially good decision that I made in the past, only to find out later after some repeated incidents, which will make me revert back the decision. And thus, wasted efforts. This has happened to me more than a couple of times.

Instead of:

- Rename foo to bar.
- Remove baz.

it’s much more helpful (for the future me, for other users) to write:

- Rename foo to bar because foo is not a very clear name.
- Remove baz because Module::XYZ already has something similar (qux), 
  added a mention in See Also section.

The “why, Why, WHY???” rule is also very much applicable to code comments and commit messages.

Updating old entries

In a long history of a module, or a specification document, a feature that got introduced in an earlier release might get renamed or removed in a later release. When one reads the Changes file, it will be useful in the old entry that introduced a feature gets updated with a reference to the new release which removes/deprecates/renames the feature.

You might also notice something like this in IETF RFCs listing. For example, when you are viewing RFC 821 (an old description of the SMTP protocol), you’ll see a notice that this RFC has been obsoleted by RFC 2821.

So something like this might be useful:

1.03    2015-03-06 (PERLANCAR)

        - Add quz.
        - Remove foo because it proves to be more trouble than it's worth.
        - Rename bar to baz because bar might be mistaken as a night-only
          thingie.

...

0.46    2011-03-02 (SOMEONE2)

        - Introduce foo. UPDATE: Removed in 1.03.

...

0.13    2011-03-02 (SOMEONE2)

        - Add bar. UPDATE: Renamed to baz in 1.03.

Some other things I do

Add releaser information. Even if currently all of my dists are released only by me (but I’ve switched PAUSE accounts before). This is additional information that might be useful. Reader can be informed that a certain release is not released by its original maintainer/author. And, different releaser might use different build tools/environment and this might creep in as bugs. Knowing who did the release can be useful to track down the problem.

Add a blank line for each entry in a release. For example: this or this. Admittedly, this started purely because of issue with text editor (I can align each entry more easily in Emacs if I separate each entry with a blank line), but with time, this format encourages me to write more sentences in a single entry as a paragraph, instead trying to be as brief as possible by keeping each entry to fit in a single line. And, if each entry becomes a paragraph, a blank line separator helps readability.

Some things I tend to avoid

Crediting each entry

Example:

1.2.3    2015-03-06 (PERLANCAR)

         - Add foo GH#19 (Peter)

         - Make it so that bar does not crash the browser (Peter)

         - Fix bug GH#32 (Ron)

         - Rename bar to baz (Peter)

         - Mention some related modules (Ron) 

Sure, it’s okay to mention an occasional contributor and if there are only a few entries. But if there are a lot of entries, the names become more of a noise and distracting. If you need to credit a significant contribution for a certain release, perhaps it’s better to add an entry at the above, for example:

1.2.3    2015-03-06 (PERLANCAR)

         - This release is mostly due to Peter's tireless work. So, thanks Peter.

         - Add foo GH#19
         - Make it so that bar does not crash the browser
         - Fix bug GH#32
         - Rename bar to baz
         - Mention some related modules

I believe it’s more convenient for the reader. If a curious reader wants to know who does each change, she can go browse the commit logs.

Categorizing changes by contributor. Ugh, just no. This is not helpful for readers.

Other recommended readings

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s