WordPress plugin/theme readme file standard. Readme.txt
Always have an “Unreleased” section at the top for keeping track of any changes.
This serves two purposes:
Alright…let’s get into it.
Sadly, no. Calm down. I know you’re furiously rushing to find that link to the GNU change log style guide, or the two-paragraph GNU NEWS file “guideline”. The GNU style guide is a nice start but it is sadly naive. There’s nothing wrong with being naive but when people need guidance it’s rarely very helpful. Especially when there are many situations and edge cases to deal with.
Well, if you can’t tell from the example above, CHANGELOG.md is the best convention so far.
Some projects also use HISTORY.txt, HISTORY.md, History.md, NEWS.txt, NEWS.md, News.txt, RELEASES.txt, RELEASE.md, releases.md, etc.
It’s a mess. All these names only makes it harder for people to find it.
Because log diffs are full of noise — by nature. They could not make a suitable change log even in a hypothetical project run by perfect humans who never make typos, never forget to commit new files, never miss any part of a refactoring. The purpose of a commit is to document one atomic step in the process by which the code evolves from one state to another. The purpose of a change log is to document the noteworthy differences between these states.
As is the difference between good comments and the code itself, so is the difference between a change log and the commit log: one describes the why, the other the how.
It’s difficult, because people follow wildly different formats and file names.
Vandamme is a Ruby gem created by the Gemnasium team and which parses many (but not all) open source project change logs.
“CHANGELOG” is the name of the file itself. It’s a bit shouty but it’s a historical convention followed by many open source projects. Other examples of similar files include README, LICENSE, and CONTRIBUTING.
The uppercase naming (which in old operating systems made these files stick to the top) is used to draw attention to them. Since they’re important metadata about the project, they could be useful to anyone intending to use or contribute to it, much like open source badges project.
When I refer to a “change log”, I’m talking about the function of this file: to log changes.
Yanked releases are versions that had to be pulled because of a serious bug or security issue. Often these versions don’t even appear in change logs. They should. This is how you should display them:
## 0.0.5 - 2014-12-13 [YANKED]
The <[YANKED]> tag is loud for a reason. It’s important for people to notice it. Since it’s surrounded by brackets it’s also easier to parse programmatically. Should you ever rewrite a change log?
Sure. There are always good reasons to improve a change log. I regularly open pull requests to add missing releases to open source projects with unmaintained change logs.
It’s also possible you may discover that you forgot to address a breaking change in the notes for a version. It’s obviously important for you to update your change log in this case.
The simplest thing to do is start your initial development release at 0.1.0.0 = 0.1.0 and then increment the FEATURE version for each subsequent release.
If your software is being used in production, it should probably already be 1.0.0.0. If you have a stable API on which users have come to depend, you should be 1.0.0.0. If you’re worrying a lot about backwards compatibility, you should probably already be 1.0.0.0.
ENHANCED version zero is all about rapid development. If you’re changing the API every day you should either still be in version 0.x.y.z or on a separate development branch working on the next major version.
This is a question of responsible development and foresight. Incompatible changes should not be introduced lightly to software that has a lot of dependent code. The cost that must be incurred to upgrade can be significant. Having to bump major versions to release incompatible changes means you’ll think through the impact of your changes, and evaluate the cost/benefit ratio involved.
It is your responsibility as a professional developer to properly document software that is intended for use by others. Managing software complexity is a hugely important part of keeping a project efficient, and that’s hard to do if nobody knows how to use your software, or what methods are safe to call. In the long run, CMS Versioning (CMSver), and the insistence on a well defined public API can keep everyone and everything running smoothly.
As soon as you realize that you’ve broken the CMS Versioning (CMSver) spec, fix the problem and release a new minor version that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it’s appropriate, document the offending version and inform your users of the problem so that they are aware of the offending version.
That would be considered compatible since it does not affect the public API. Software that explicitly depends on the same dependencies as your package should have their own dependency specifications and the author will notice any conflicts. Determining whether the change is a PATCH version level or FEATURE version level modification depends on whether you updated your dependencies in order to fix a bug or introduce new functionality. I would usually expect additional code for the latter instance, in which case it’s obviously a minor level increment.
Use your best judgment. If you have a huge audience that will be drastically impacted by changing the behavior back to what the public API intended, then it may be best to perform a ENHANCED version release, even though the fix could strictly be considered a patch release. Remember, CMS Versioning (CMSver) is all about conveying meaning by how the version number changes. If these changes are important to your users, use the version number to inform them.
Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new ENHANCED version release there should be at least one FEATURE version release that contains the deprecation so that users can smoothly transition to the new API.
No, but use good judgment. A 255 character version string is probably overkill, for example. Also, specific systems may impose their own limits on the size of the string.