In the software industry a changelog, as the name suggests, is a file that logs all the changes made to a specific software program. The reason for creating and keeping a changelog is simple; when a contributor or end-user wants to see if any changes have been made to a software program, they can do that easily and precisely by reading the changelog. All they need to do is go to the changelog and it will show what, and when, any changes were made between the different versions or releases of the particular software.
For every type of software project, there will be the initial release (version) and, subsequently, newer and better releases that work smoother because they have been de-bugged. Changelogs keep track of these changes. They also help to control errors because they document if, and when, those errors were corrected.
The reasoning behind this is simple; when multiple people are working on a software project, the chance that they are aware of any changes becomes slimmer. With a well-written changelog in place, however, anyone who's working on the software can see what changes have been made (or not) so they can move forward from there.
Also, the different ideas team members bring about design, standards and compliance can also be addressed through the changelog documentation. In short, a changelog helps teams work together more fluidly and keeps them on the right track, so to speak.
As mentioned, changelogs help teams develop software better. They can also help end-users who want to know what's in the software they're using and if any previous bugs or errors have been deleted. So both developers and end-users can and do benefit from a well-kept changelog.
While the following principles can change slightly from user to user, they hold true in almost all cases and will help you to create a changelog that's easy to follow and helpful to all developers and end-users.
In order to make all changelogs easier to use and read the following changes should be noted in the same manner and grouped together. This will hopefully create a standard that all can use and benefit from in the future. They are, in alphabetical order;
As of right now, there isn't a standard. That being said, the GNU Changelog Style Guide is what many are using.
There's no real standard here either. On this point however the consensus is that it should be easy for devs and end-users to find any notable changes. CHANGELOG.md works just fine in this regard although some project heads use HISTORY, NEWS and/or RELEASE to note theirs. HISTORY.txt, RELEASES.txt, NEWS.md, NEWS.txt and others can be used also.
The problem here is that, without a standard, it can get confusing. That's why many developers stick with CHANGELOG.md and more are using this name every day.
Yes, when necessary. If, for example, a change, fix, deprecation or addition was missed then, by all means, rewrite the changelog to show these changes. The whole purpose of a changelog is to note all of the most important software changes. A missing change would thus make the changelog less valuable.
Yes, definitely. Since yanked releases are versions of the software with significant bug and error issues they should always be noted. Although again not standardized this is a good example of how to display a yanked version. ## 0.0.5 - 2014-12-13 [YANKED]
Many experts will answer yes to this question as they believe that changelogs are often overutilized, excessive and poorly kept. Also, oftentimes developers will dump their git logs into a changelog, stuffing it full of useless information that can make it harder to use.