olivierlacan/keep-a-changelog

If you build software, keep a changelog.

Don’t let your friends dump git logs into changelogs™

This repository generates https://keepachangelog.com/.

Development

Dependencies

• Ruby (see version, rbenv recommended)
• Bundler (gem install bundler)

Installation

• git clone https://github.com/olivierlacan/keep-a-changelog.git
• cd keep-a-changelog
• bundle install
• bin/rake serve starts a local development server at http://localhost:4567 which will reload with any local file changes
• bin/rake build runs middleman build with --verbose flag so build errors are logged for easier debugging

Deployment

• bin/rake clean can clean a corrupted build/ directory in case publish failed
• bin/rake deploy cleans, builds and pushes to the gh-pages branch on GitHub so the site is deployed to keepachangelog.com

Translations

Create a new directory in source/ named after the ISO 639-1 code for the language you wish to translate Keep a Changelog to. For example, assuming you want to translate to French Canadian:

• create the source/fr-CA directory.
• duplicate the source/en/1.0.0/index.html.haml file in source/fr-CA.
• edit source/fr-CA/1.0.0/index.html.haml until your translation is ready.
• commit your changes to your own fork
• submit a Pull Request with your changes

It may take some time to review your submitted Pull Request. Try to involve a few native speakers of the language you're translating to in the Pull Request comments. They'll help review your translation for simple mistakes and give us a better idea of whether your translation is accurate.

Contribute

Please do contribute! Issues and pull requests are welcome.

Thank you for your help improving software one changelog at a time!

keep-a-changelog's Issues

Keeping it DRY by writing it at the point in a structured format

Starting with a TODO comment block

Quite often I'll write a todo comment not just as a bookmark for what's to do later, but for the work I'm about to do right then. This is the point at which I'm most aware of what I'm adding, removing, deprecating or fixing, so a structured comment block might be quite easy to add near the code I'm working on.

The structure of this could use tags, i.e. 'CHANGELOG; NEWS; Commit Message' so that when the work is committed, a pre-commit process extracts the specially formatted comment blocks and appends the categorised and itemised content to the places it's been tagged for.

Strikes me that this could help focus the mind on the work that's about to be done, avoid forgetting important bits when it comes to the commit messages and keep the commit message useful, and produce a standardized changelog.

The downsides being the parsers that'd be needed to extract the comment blocks from all the languages worked with, and the discipline of writing structured comment blocks at the point.

Anyway, just another idea to put in the pot.

P.S. was inspired to write after starting to listen to the changelog podcast episode.

Use underlines rather than "##" for entries

If you're proposing that each changelog entry contains nested sections like ### Added, then I suggest using underlined headings for each entry to better visually separate changelog entries from sections.

This reads better IMO than what is currently proposed and is still valid markdown:

# Changelog
All notable changes to this project will be documented in this file.

0.0.3 - 2014-08-09
------------------

### Added
- "Why should I care?" section mentioning The Changelog podcast.

### Deprecated
- Nothing.

### Removed
- Nothing.

### Fixed
- Nothing.

0.0.2 - 2014-07-10
------------------

### Added
- Explanation of the recommended reverse chronological release ordering.

### Deprecated
- Nothing.

### Removed
- Nothing.

### Fixed
- Nothing.

This format would also allow parsers (like chag) to work with reStructuredText and markdown interchangeably.

how to get links to versions in CHANGELOG.md file

Hi guys, I'm using same style as here https://github.com/olivierlacan/keep-a-changelog/blob/gh-pages/CHANGELOG.md for my change log file https://github.com/darlingjs/darlingjs/blob/master/CHANGELOG.md. But why in original change log versions. like that one

[Unreleased][unreleased]

or

[0.0.8]

converts to link, but in my case it still looks in raw format. What is the purpose? And how to get links as well?

Date pronunciation by Brits

while Brits use a robotic-looking "2 June 2012", yet pronounce it "June 2nd, 2012".

Very few people pronounce dates that way in this country! In fact, most people I know twitch when American film trailers recite dates in "September 19" format.

Apart from that - I like the document!

The "Change" section.

Currently only Added, Deprecated, Removed and Fixed are noted as section of the changelog. In my opinion a Change or Altered section should be added so people have a place to list things like:

• Updated dependencies (version change).
• Altered implementations.
• Renamed methods.
• And so on.

I suggested the "Altered" label to be a little more specific about what goes in there, preventing it from being a dumping ground for all changes.

The tool

There were already some suggestions about a "tool".

I think they should be concentrated in one issue concerning the tool specifically.

What should it do?

• Check your changelog for syntax errors
• Be able to convert your changelog files from distros, etc .. into this format (plugin-able)
• This tool should use some "template" - a standard that would define the changelog syntax for the checking and conversion
• Should maybe contain some dictionary with key-words, like breaks, yanked to suggest instead adding [BREAKS], [YANKED] tag or similar
• Export public version of this document without [internal] tagged lines.

I can cook something up in Python, but as this is not my own project, I don't want to impose my preferences on anyone :)

However this tool should be part of this project, something like Syncthing - they also have reference implementation for their protocol, and it seems like a good idea.

Who is this project for?

One of the things I am left wondering when reading the spec and some of the issues in this project is the question of what audience this project is intending to target; in fact, what two audiences.

The first is what types of projects. There are a few different major types of software projects. One is libraries, that are intended to be used by other developers, or possibly hosted APIs. Another is server software being delivered to sysadmins, or maybe anything highly technical; the end users are expected to be technically proficient and know a bit about how the software works, but are not necessarily API consumers. The last is end-user facing software; hosted software intended intended for non-technical end users, or desktop or mobile software intended for them.

The other question is who the audience for the changelog is, which is a slightly different question than above. While the audience could be the primary users of the software, it could also be downstream distributors such as package maintainers for software that gets packaged in Linux or BSD distros, or it could be other developers, QA, and tech support within the project itself.

The answers to these questions would influence some of the other open discussions I see on this repo. For instance, issue #2 about which changes should be included. If it's intended for team members who are heavily involved in the project itself, it should probably include all changes like a GNU style ChangeLog, though I think that with modern Git commit message conventions that's redundant, the Git log is where people involved in the project itself should be looking.

Issue #30 is also related to this. It mentions marking internal vs. external changes. Perhaps the idea here is that the changelog is for the internal team, but a user-facing release notes should be extractable from it?

The other audience that isn't frequently thought of, besides internal people and external users, is external packagers. Things like reorganizations of data files or splitting up of single binaries into libraries and multiple binaries, licensing audits, and the like may be important to them.

What type of software this is targeting is also important. For developer-facing APIs, pretty much every change that affects the external API should be documented, as well as any major internal changes that may affect its behavior. For sysadmin oriented software, any data migrations that might be necessary should be mentioned. For end user oriented software, probably only user visible changes and added removed functionality should be mentioned.

However, sometimes a single project is more than one of these things. You may have a hosted service, that has both a programmatic API and an end-user facing interface.

Defining which of these types of projects, and which of these types of users, is in scope for this document would be good. If they are all intended to be in-scope, then there may need to be a decision on how to support all of them if they have conflicting requirements, for instance some changes that are internal only, or some that affect the API while some that affect the UI.

Is the goal to support those through multiple different changelogs, or some master changelog from which each could be extracted?

Broken link to CHANGELOG.md on website.

On http://keepachangelog.com/ phrase "contains what I hope will become a better CHANGELOG file convention." links to 404 Page Not Found.

Sections for Migrations / Tests would also be useful

Changed semantics

Hi there,

we have the following groups:

• Group changes to describe their impact on the project, as follows:
  • Added for new features. (+MINOR)
  • Changed for changes in existing functionality. (+MINOR or +MAJOR)
  • Deprecated for once-stable features removed in upcoming releases. (+MINOR)
  • Removed for deprecated features removed in this release. (+MAJOR)
  • Fixed for any bug fixes. (+PATCH)
  • Security to invite users to upgrade in case of vulnerabilities. (+PATCH)

I've added here which version number each group affects. For Changed it is possible to have altered existing functionality in such a way that you must increment MAJOR, but you can also have changes which only have to increment MINOR.

For example:

• MINOR: You've altered a existing functionality in such a way, that it is faster or it is slightly reconfigured or refactored. The interface hasn't changed, so it would be an overkill to increment MAJOR?!
• MAJOR: You've altered the functionality in an API incompatible way.

It may be useful to distinguish Changed changes for MINOR or MAJOR, so that the reader sees this immediately?
Maybe it is useful to add to the spec something like Changed minor or Adjustment or Improvement to point out its an API compatible change in existing functionality?

merge=union

I read this blog post which talked about how keeping a CHANGELOG can prevent automatically accepting pull-requests, unless you put something like CHANGELOG.md merge=union in your .gitattributes file. Since this website is all about CHANGELOGs, I think it's worth mentioning somewhere in the site that specifying CHANGELOG.md merge=union is pretty important 😄

Question: what about entries that are focused on performance?

Hypothetically, what if you had an entries like:

• method() now uses 50% of the memory
• on a 2012 MacBook, method() completes in 30% of the previous elapsed time

Are these fixes? Or additions? Should there be a new performance section?

List of change groups not properly nested

Should be an easy fix.

keepachangelog tools

This is not strictly an issue, but FYI a few folks have been making tools based around the conventions established so far by this project. Here are a few I have participated in or found:

• https://github.com/bcomnes/changelog-init
• https://github.com/ngoldman/changelog-parser
• https://github.com/ngoldman/gh-release
• https://github.com/bigwhoop/trellog
• https://github.com/contentful-labs/keepachangelog

Might be helpful/beneficial to link to these in the README. 😄

CLI?

Any special CLI? Or some tool that can be customized to apply that spec?

Or I'll try to do it and report back :)

Changelog for each minor release

With large teams and lots of changes, these file can be pretty big, and one changelog would be massive.

On large projects, I personally tend to create a changelog for each minor version, like CHANGELOG-2.4.md, CHANGELOG-2.5.md.

I then split each changelog into sections, like "changes introduced in x.y.3", "changes in x.y.1".

I think large projects like symfony also do similarl; see https://github.com/symfony/symfony/blob/master/CHANGELOG-2.2.md

Change log does not mention whether the project follows Semantic Versioning

The guide states:

What makes a good change log?
Explicitly mention whether the project follows Semantic Versioning.

https://github.com/olivierlacan/keep-a-changelog/blob/v0.0.6/README.md#what-makes-a-good-change-log

But the change log does not mention whether the project follows Semantic Versioning:
https://github.com/olivierlacan/keep-a-changelog/blob/v0.0.6/CHANGELOG.md

I think the change log should "lead by example" and should implement all its recommended best practices.

Reflections about automation and having a good changelog

Here are my 2 cents,

First, I'm the author of gitchangelog which will "dump git logs into your changelog". But I feel somewhat that we are chasing the same rabbit.

Can you tell me what's wrong with this changelog: https://pypi.python.org/pypi/gitchangelog#changelog

TBH, I have difficulties to see what can't be automated if you accurately move to the commit time the editing/filtering job of making a changelog. This requires some conventions (and thus discipline) although. But has huge advantages also.

With little effort on your git committing conventions, I think I could generate your actual CHANGELOG.md from git log thanks to a gitchangelog with a customized gitchangelog.rc.

I would be happy to contribute to your project in my way, by providing a template in gitchangelog that would generate what you came up as what should be the standard format for a changelog.

I feel like you imply that there are no way to generate automatically a valid changelog from a git history, and this seems like a religious statement as I can't see any clear points in your README.md linking the automation process to are failure of following what you list as "what makes a good changelog".

Many thanks to read me, I care about making good changelog also.
I would be happy to have any feedback about my thoughts and hope that mine is helping in some ways.

Chronological Order?

First off, I love this repo and the discussion that it's generating. Thanks for putting this together.

The example CHANGELOG only has a single version entry in it. When I bump to version 0.0.2, do I append the version 0.0.2 section to the bottom of the CHANGELOG (chronological order), or insert it above the entry for version 0.0.1 (reverse chronological order)?

My vote is for reverse chronological order so information about the most recent version is kept near the top.

The First-Look CHANGELOG doesn't include an Unreleased section

The first-ever example of the CHANGELOG format (on the website) fails to include the "Unreleased" section, yet the website text states --Always have an "Unreleased" section at the top for keeping notes on any changes.--

This is not so good. If we expect N% of people will look at the website, then maybe P% will see the "hero image" - the example log.

Consider making it as impactful and complete as possible. PR?

Handling of Public vs Internal changes

This is somewhat related to issue #2

We have a SAAS app. We make many changes. We want these to be in the Changelog. We need to communicate what's changed to the client, but they don't need to know about refactorings or other things that we find notable but have no customer facing effect.

Proposal

In each release support the current format as well as the concept of "Public" and "Internal" sections. Automated tools could be set to simply ignore anything under an "Internal" heading when generating documentation for public consumption.

An example (noting that most of the time only some of these would be present / filled out):

## 0.0.4 - 2014-08-09
### Public
#### Added
- blah blah

#### Changed
- blah blah

#### Removed
- blah blah

### Internal
#### Added
- blah blah

#### Changed
- blah blah

#### Removed
- blah blah

Should you ever rewrite things you put in your CHANGELOG before?

Basically, should CHANGELOG files be diffable to quickly see what updates have been added since the last time? I just ran into a diff that made little sense (i.e. it had not just prepended new information to the top): CHANGELOG.txt, Zegnat/AdBlock-WebKit@2842332.

Denote API breaking changes

We have a Changed section but some changes may be breaking and others not. This information can be encoded in the release version if the maintainer follows Semantic Versioning but unless this adherence is explicitly stated in the change log (I think it should, which we should address) we can't assume that readers of the change log know that a major version bump often comes with the introduction of API breaking changes.

So far I've seen and used this syntax:

## 1.0.0 - 2014-12-13
### Changed
- [breaking] removed method x

While it does the job of calling attention to the breaking change, it's inconsistent with the idea I submitted for yanked releases in #35. I think a breaking change should warrant as much if not more attention than a yanked release. So perhaps:

## 1.0.0 - 2014-12-13
### Changed
- [BREAKING] removed method x

Sure it's ugly, but it does the job. With several independent breaking changes though it gets real ugly:

A way to fix that would be to use Markdown's emphasis:

## 1.0.0 - 2014-12-13
### Changed
- **BREAKING**: removed method x

This one looks a bit more civilized:

It might be worth extending this syntax to yanked as well since square brackets have no emphasis meaning in Markdown and conflict with link tags a bit.

Generate changelog from an actual data format?

Rather than trying to parse the Changelog, wouldn't it make more sense to store it in some real data format, and then just generate it?

e.g.

require 'json'

# LOAD THE DATA STRUCTURE
changelog = JSON.load <<CHANGELOG_JSON, nil, symbolize_names: true
{ "description": "All notable changes to this project will be documented in this file.",
  "entries": [
    { "version"  : "0.0.4",
      "released" : "2014-08-09",
      "added"    : ["Better explanation of the difference between the file (\\"CHANGELOG\\") and its function \\"the change log\\"."],
      "changed"  : ["Refer to a \\"change log\\" instead of a \\"CHANGELOG\\" throughout the site to differentiate between the file and the purpose of the file — the logging of changes."],
      "removed"  : ["Remove empty sections from CHANGELOG, they occupy too much space and create too much noise in the file. People will have to assume that the missing sections were intentionally left out because they contained no notable changes."]
    },
    { "version"  : "0.0.3",
      "released" : "2014-08-09",
      "added"    : ["\\"Why should I care?\\" section mentioning The Changelog podcast."]
    },
    { "version"  : "0.0.2",
      "released" : "2014-07-10",
      "added"    : ["Explanation of the recommended reverse chronological release ordering."]
    },
    { "version"  : "0.0.1",
      "released" : "2014-05-31",
      "added"    : [
        "This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.",
        "CNAME file to enable GitHub Pages custom domain",
        "README now contains answers to common questions about CHANGELOGs",
        "Good examples and basic guidelines, including proper date formatting.",
        "Counter-examples: \\"What makes unicorns cry?\\""
      ]
    }
  ]
}
CHANGELOG_JSON

# NORMALIZE THE DATA STRUCTURE
changelog[:entries] ||= []
changelog[:entries].each do |entry|
  entry[:changed] ||= []
  entry[:added]   ||= []
  entry[:removed] ||= []
end

# LOAD THE TEMPLATE
template = <<ERB_TEMPLATE
# Change Log
<%= changelog[:description] %>

<% changelog[:entries].each do |entry| -%>
## <%= entry[:version] %> - <%= entry[:released] %>
<% if entry[:added].any? -%>
### Added
<% entry[:added].each do |added| -%>
- <%= added %>
<% end -%>

<% end -%>
<% if entry[:changed].any? -%>
### Changed
<% Array(entry[:changed]).each do |changed| -%>
- <%= changed %>
<% end -%>

<% end -%>
<% if entry[:removed].any? -%>
### Removed
<% Array(entry[:removed]).each do |removed| -%>
- <%= removed %>
<% end -%>

<% end -%>
<% end -%>
ERB_TEMPLATE

# RENDER THE TEMPLATE
require 'erb'
puts ERB.new(template, 0, '-').result(binding)


# >> # Change Log
# >> All notable changes to this project will be documented in this file.
# >> 
# >> ## 0.0.4 - 2014-08-09
# >> ### Added
# >> - Better explanation of the difference between the file ("CHANGELOG") and its function "the change log".
# >> 
# >> ### Changed
# >> - Refer to a "change log" instead of a "CHANGELOG" throughout the site to differentiate between the file and the purpose of the file — the logging of changes.
# >> 
# >> ### Removed
# >> - Remove empty sections from CHANGELOG, they occupy too much space and create too much noise in the file. People will have to assume that the missing sections were intentionally left out because they contained no notable changes.
# >> 
# >> ## 0.0.3 - 2014-08-09
# >> ### Added
# >> - "Why should I care?" section mentioning The Changelog podcast.
# >> 
# >> ## 0.0.2 - 2014-07-10
# >> ### Added
# >> - Explanation of the recommended reverse chronological release ordering.
# >> 
# >> ## 0.0.1 - 2014-05-31
# >> ### Added
# >> - This CHANGELOG file to hopefully serve as an evolving example of a standardized open source project CHANGELOG.
# >> - CNAME file to enable GitHub Pages custom domain
# >> - README now contains answers to common questions about CHANGELOGs
# >> - Good examples and basic guidelines, including proper date formatting.
# >> - Counter-examples: "What makes unicorns cry?"
# >> 

Update "Can change logs be automatically parsed?"

Hi!
I created Github-Changelog-Generator.

It seems, that it exactly, what should be mentioned in Paragraph Can change logs be automatically parsed?.

My project generate changelog file very close to your changelog conventions.

bdw: found your article, when try to google standart date format for changelog files - many thanks for explanation! I will implement it in my project in next release

What about upgrading notes

Something more useful than a change log is a note about "how to upgrade to the next version".

Let's take for instance the symfony/symfony repo. There are some CHANGELOG files (which are just a log of git commits, so yes, quite useless), but it also provides UPGRADE files to better explain to the end user the impacts on his project. It's not listing all the important changes between versions but focuses on the actions the user must do (updating his code if the project is a lib or, for instance, upgrading a database if the project is a full application).

My question is: should we include those "upgrading notes" into the change log or keep them apart?
IMO as it could be quite long it's better to have a separate file, but for quick actions it could make sense to have a dedicated sub section. What do you think?

Add database versions

Hi,

How do I add information database versions in the changelog ?

Sections should be only recommended

Inspired by #20, I would now say the possible sections for each release (like Added, Deprecated, Removed etc.) should be only recommended by the formal specification.

Each project works differently. For example someone would never use Security sections. while someone always use Performace section. Instead of trying to list all possible section, I would suggest only list few mainly used sections, mention these are only examples, and let anyone chose those sections that fits the specific project.

What changelog formats are out there?

Hi,

great initiative! I've been pondering about this issue a while, too, and started a small tool to parse changelogs in ruby land a while back: https://github.com/lhm/changelog_parser

What I found at that time was that even within language communities there is a great variation in the way people structure their changelogs. The reasons may be personal preference, ease-of-update, or sometimes historical precedence.

My gut feeling currently is that it will be difficult to find a one-size-fits-all format that satisfies a sufficiently sized critical mass. Instead, I'd look to find some way to communicate the semantics of the projects' changelog, possibly involving magic comments, akin to vim/emacs hints in source files.

In any case, more data would be useful. I think it would be interesting to start collecting changelogs from different projects (organized by programming languages maybe?), in order to see what the current state of affairs is. Maybe this project could be a place to start such a collection?

A general note to the version

I read about this project on WP Tavern and I was surprised that the only thing I have to change in my changelog is the format of version title :)

I thought it would be good to include a general Note to the version. Not always it is needed, but sometimes it would be useful. Or you would just include it as a simple paragraph below the version title?

Also I use indicators that group the changes made, like Accessibility, Translation, etc..

It could be like:

[2.0.0] - 2014-11-02

Note

• This changelog reflects theme development going from Tiny Forge v1.6.0 to Tiny Framework v2.0.0

Added

• Enhancement: new mobile menu look and functionality: sticky menu + integrated search.
• Enhancement: new navigation menu for social networking link management.
• Accessibility: added outline that affects all links on the site.
• Translation: significant changes compared to Tiny Forge, translation will have to be redone.

Why not use GitHub release notes?

@searls offers this example: https://github.com/linemanjs/lineman/releases

My retort:

@searls Sure, but that’s not portable. It’s already hard to convince OSS maintainers to keep a changelog, this is even harder.

Portability

I think the portability problem is a huge showstopper. Something that can't live with the repo will disappear if the project moves from GitHub, or just simply isn't accessible offline with the codebase in hand.

I think that's a problem for GitHub to address if they want to see people adopt their release notes platform.

Tags

This however is a neat idea although I find tags much more obscure than some people seem to realize. The git interface is pretty poor I think, and the visibility from various clients, although better than before, is still not great. That's the one part of GitHub's implementation of Releases notes that I do like, however, since they are portable.

I don't know if it's possible using git, but it would be nice if the GitHub release description was stored in the tag description itself.

Evangelism on GitHub

This is all well and good, but…

I love this project’s goal, but even some of the best ideas didn’t succeed on merit alone. People who believed in those ideas talked to people they know, and got others on board.

(That’s how Isaac Schlueter got npm to become the de facto package manager for Node.js! The link is to a podcast episode—ironically, from “The Changelog” podcast. The part I am citing starts at 8:15, and goes on for the next minute or two.)

I Propose…

…That everyone who believes in the Keep A Changelog mission should start opening Issues or Pull Requests, asking repo owners and contributors to convert to the changelog format described by this project.

Recommendations

• Spread the word. Always mention the http://keepachangelog.com URL in your Issues or Pull Requests.
• Make it easy for others to convert. I’ve often found change logs that are pretty close to official format, but organized just a little bit differently. I recommend editing these yourself and sending a Pull Request; that will make it much easier for them to accept.
• Quantity matters. If it’s not so easy for you to do the previous item, try and make up for the difference in volume; open as many as you can, and aim for sheer numbers. The more people are following these guidelines, the more likely it is that others who are more resistant might just reconsider.

Opening homepage in FF 40 causes prompt for file download

Loading the site root in firefox version 40 causes a prompt for CHANGELOG.md to be downloaded. It doesn't do this in chrome, so I don't know if it is a firefox bug or a problem with the code here. in firefox it doesn't display the changelog for the site, where as in chrome it does.

Dealing with yanked versions

It's common for libraries to be yanked when they create serious issues when released. They're then replaced with a subsequent version but it's not often obvious to people who had upgraded to the yanked version what happened.

Too many change logs simply ommit yanked versions as if they had never existed.

We should try to define a standard for how to display yanked version in a change log:

## 0.5.0 (YANKED) - 2012-12-12
## ~~0.5.0~~ - 2012-12-12
## [YANKED] 0.5.0 - 2012-12-12
## [YANKED] 0.5.0 - 2012-12-12
## 0.5.0 - 2012-12-12 [YANKED] 

From a parsing perspective, here are my goals:

1. yanked versions need to STAND OUT
2. yanked versions need to not screw up automated change log parsers by abnormally changing the order of the version header, this is why my favorite is the last example
3. yanked versions need to be self-evident, it should be obvious to anyone that these versions were pulled, so perhaps a less colloquial word than yanked should be used: pulled, removed, etc.

The Markdown strikethrough ~~word~~ is nice but it's a noisy syntax that doesn't (alone) make it obvious that a version had to be killed. In combination with a descriptor take [YANKED] I think it could work but again, it risks messing up automated parsing, which is not ideal.

Separate changelogs for different branches

Hi @olivierlacan,

This is a nice movement you're doing here. 👍

My question is that, is it a right convention to use different changelogs for different repository branches?
I think that it's not wrong to have separate changelogs because each branches serves different purpose.

Can you please share your thought on this particular situation?

Date wrapping convetion

Hi. I'm developing related project Github-Changelog-Generator.
And has a question - what will be guideline for date wrapping format.
For example: in that project format like tag - date

I try to research, how people usually print date and here is a some stats:

• 90% of repo (try too look most starred repo in github) prints if format tag (date)
• 5% prints in the same format, like yours tag - date
• 5% don't print date at all

Examples:

• https://github.com/h5bp/html5-boilerplate/blob/master/CHANGELOG.md
• https://github.com/angular/angular.js/blob/master/CHANGELOG.md
• https://github.com/docker/docker/blob/master/CHANGELOG.md
• https://github.com/square/picasso/blob/master/CHANGELOG.md
• https://github.com/GoogleCloudPlatform/kubernetes/blob/master/CHANGELOG.md

So, I would like to discuss, what should be guideline for changelog format and why?

Link to the "standard" Perl format somewhere?

There's already a standard that is at least somewhat widely used in the Perl community. See https://metacpan.org/pod/CPAN::Changes::Spec for details. It's a bit looser than what you propose, but the ideas are very similar. There's also a testing module people can use to verify that their Changes file follows the spec.

Parseable variations (Markdown, RST, Wiki, text/plain)

Agreeing on a common format is difficult.

For freshcode.club (a freshmeat replacement), I've decided to allow a few variations, but still enforce a common scheme (which k-a-c captures pretty well).
Here primarily to keep it parsable without too many false positives:
http://fossil.include-once.org/freshcode/wiki/AutoupdateChangelog

I'd have presumed Markdown was more common, but in particular Python projects (well, if they have a changelog anyway) seem to lean towards ReStructuredText rather (PEP287 and hence PyPI support).

Plain text structures are not that far off from MarkDown either, and I'd need to support it since CPAN::Canages::Spec is the only widespread format.

What I personally find more relevant to differentiate release note changelogs from commit logs is leaving out e.g. attributions (written by <[email protected]) or ticket numbers (Closes #257) which are largely irrelevant to actual feature changes. Maybe the summarization intent of changelogs could be more stressed?

No suggestions for handling changes in dependencies

Let's say you have an app that's dependent upon some external service or library. That external software has been updated and you have leveraged the latest version of it in your app, thus giving your app new features or limitations.

When producing a change log for your app it seems that the most responsible, and sensible, thing to do would be to point out the changes in the external software that are applicable to yours...

Maybe a "Changes from External sources" section or a suggestion for a convention for linking to external repos / web sites for changes.

The best would be a way to link to the markdown changelog from an external project such that if it was using the keep-a-changelog format we'd be able to programmatically ingest the changes from the linked version eg

## Additions
  - blah
  - blah
  - Added changes from [version 0.0.2-0.0.4 of keep-a-changelog](https://raw.githubusercontent.com/olivierlacan/keep-a-changelog/gh-pages/CHANGELOG.md)

That would (potentially) enable a script to see that the link is to a CHANGELOG.md file and parse it to extract the changes in versions between 0.0.2 and 0.04 for insertion into the rendered version of your change log.

How to make version as links

On the https://github.com/olivierlacan/keep-a-changelog/blob/master/CHANGELOG.md you have versions are links to tag compare. I've created my change log at https://github.com/qa-tools/qa-tools/blob/develop/CHANGELOG.md and this doesn't happen. Also the user mentions doesn't work.

Any idea why?

Awesome guide! + Suggestions/Ideas

This is a great guide. I was just looking for some rules since every time I
attempted to keep a change log for my own use it ended up being totally useless

In respect to the earlier releases it might be a good idea to order the sections
within a change log to first display those more crucial to those "less" crucial.

So something like:

• Security
• Fixed
• Removed
• Deprecated
• Changed
• Added

Also it might be a good idea to make the README more detailed for those (like
me) who are beginners but want to use this and make a habit out of it. Thought I
guess consistency is more important whatever the order is.

So a little bit more detail about "what" should go under these sections using
some real project examples. For example, does a removed method go into the
Removed section or Changed section? What does Add section contain, so if I add
an new method does it go here or to Changed. What is considered a feature, how
to determine what should I put in the change log etc.

Adding a good git tag guide would also help ( like the one here ) and using
git push origin [tagname] rather than creating tags via the Github, as well as using
git tag -a etc.

A bonus would be explaining the workflow you have with the change log, though I
guess this guide might not be for beginners. For example, do you actually edit
the change log on every commit you deem worthy for mentioning or a the time of
the release you just review the commits you have done and pick the most
important?

And for the extremely ocd/nitpicking question of the day:
Within a change log section (example Added) do you keep the additions
chronological (first-to-last) or in reverse (like the commit history, git log)?

Thanks again for the guide and your effort put into it.

Brazilian Portuguese translation

Hi,

I'm just passing by (again) to tell you that I've translated the content to Brazilian Portuguese 🍍

ambiguity in "guidelines for contributing"

Please don't submit pull requests that directly modify the index.html file. It's generated by the generate.thor script which I would appreciate you run before submitting your pull request if you included any changes to README.

I think you mean a polite version of "Don't edit the index.html manually. Instead regenerate it via thor and then add it to your PR for changes to the README."

BUT what it actually instructs people to do is not modify index.html it, but run thor.... and then... throw out the changes thor generated to index.html. I guess. I say this because the commit and the resulting PR will most definitely modify the index.html file directly even when the changes are from thor. And it instructs me not to directly modify it.

Yeah, I know. I'm being pedantic. But I seriously had to stop and ponder if you wanted the index.html changes in the PR or not. Maybe you have some after-merge hook that automatically runs thor and updates the repo, and reloads the site. Dunno.

Use same tense in changelog messages

I opened this issue because I do not quite know what to do. I have rather often read to use the "imperative present tense" in commit messages. What about changelogs? The proposed special words like "added" and "removed" are all in past tense. The main example mixes them.

Present tense:

### Fixed
- Fix typos in recent README changes.
- Update outdated unreleased diff link.

Past tense:

### Added
- Unreleased section to gather unreleased changes and encourage note
keeping prior to releases.
### Changed
- Clarified the section on "Is there a standard change log format?".

I suggest to be consistent about the style - but I do not know which one to prefer (to be fair: I have a preference, but I want to hear other opinios before submitting a pull request). Any thoughts?

Why the emphasis on open source?

The website text tightly relates the proposed change log format with open source projects:

of notable changes for each version of an _open source project_
(...)
If you don’t care, why are you contributing to _open source?_
(...)
about why _open source maintainers and contributors_ should care
(...)
what I hope will become a better CHANGELOG file convention for all _open source projects. Can the_ _open source community_ learn from its mistake

I came to know keepachangelog.com by searching for a standard to apply in the (private) company I work at, and so far it seems a pretty good format to use. I assure you that this problem (bad change logs or the complete lack of it) affects many projects out there, both closed and open source.

Don't you guys think that adherence to the format by the closed source world would benefit the industry as a whole?

I actually don't mind (not at all) the open source references along the manifesto (can I call it a manifesto?), I'm just passing by giving food for thought.

Minor corrections

Great article, just discovered this from a WordPress link... and indeed it's definitely something I'll help support, since I agree on virtually all points. :-) Couldn't help spotting a negligible typo here, though:

"CHANGELOG" is the name of the file itself. It's a bit shouty but it's a historical convention followed by many open source project.

Obviously the last word should be pluralised. Also, on a slightly less objective note:

"Americans put the month first ("06-02-2012" for June 2nd, 2012, which makes no sense), while Brits use a robotic-looking "2 June 2012", yet pronounce it differently."

Yeah, sorry, but Australians do the latter... as does every English-speaking country that isn't the United States. ;p I get that the remark is meant to be tongue-in-cheek, however, it does provoke a bit of an eye-roll. That sentence is probably better served as "The US puts the month first ... ... while the rest of the world uses a robotic-looking ... ", blah-blah.

Note I also mentioned the US, not "Americans". Latin America takes the sensible approach with ordering dates. ;-)

Anyway, up with ISO.

Referencing issue numbers

Have you considered any particular format for referencing issue numbers from within the change log?

Translation into Russian

Olivier, thanks for a great manual! I'd like to translate it into Russian, what do you think?

Isn't a CHANGELOG about all changes not just important changes?

Several interesting comments on Twitter from Caleb Thompson and Aaron Patterson.

Caleb Thompson: @olivierlacan That’s exactly a changelog. NEWS is a record of changes between releases, which is what you want. http://t.co/bneYwnliy3

Caleb Thompson: @olivierlacan NEWS is for important changes, not every change as a log of changes would be.

Caleb Thompson: @olivierlacan Here, have some more. https://t.co/BCggwhnJnr https://www.gnu.org/prep/standards/html_node/NEWS-File.html#NEWS-File https://www.gnu.org/prep/standards/html_node/Change-Logs.html

Aaron Patterson @mperham end user focused changes should be in NEWS.

I think the GNU standards are definitely something this project will have to take into account. I do have an initial dislike for the NEWS file idea because of its atrocious semantics. NEWS tells me much less about the purpose of this file than CHANGELOG does. And its focus is not obvious at all, which I believe should explain why there's so much confusion around the naming of end-user focused change logs.

It also wouldn't be the first time people from the GNU community commit semantic crimes. Another proof that — yes — naming does matter, a lot.

No "changed" group mentioned.

There is no "changed" group mentioned on http://keepachangelog.com/ in "Each version should:", but is presented in example CHANGELOG.