Skip to content

Keep a CHANGELOG #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 18, 2016
Merged

Keep a CHANGELOG #3

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 44 additions & 0 deletions text/0000-use-changelog.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
- Start Date: 2016-07-13
- RFC PR: (leave this empty)
- Nix Issue: (leave this empty)

# Summary
[summary]: #summary

We use a change log file to document API changes of released versions relative
to their predecessors.

# Motivation
[motivation]: #motivation

Change logs are a common and convenient way to document API changes in a single
location. Being able to easily find notes on breaking changes is particularly
useful.

# Detailed design
[design]: #detailed-design

We follow the conventions laid out in [Keep A CHANGELOG](https://github.com/olivierlacan/keep-a-changelog/tree/18adb5f5be7a898d046f6a4acb93e39dcf40c4ad).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be useful to include the following:

  • Guidlines for contributors related to updating the changelog (probably encourage it but make it a soft requirement)
  • Note responsibility for maintainer to update CHANGELOG before release including creating a new unreleased section.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Guidlines for contributors related to updating the changelog (probably encourage it but make it a soft requirement)

👍 to that. We don't want it to block people from contributing, so maintainers can always fix it up later.

We add a section to CONTRIBUTIONS.md, encouraging contributors to add
appropriate entries to the change log as part of their pull requests.

We add a section to RELEASE_PROCESS.md (which does not exist yet), that tasks
the persons creating a new release with updating CHANGELOG.md appropriately.

We add an initial CHANGELOG.md file.

# Drawbacks
[drawbacks]: #drawbacks

It adds a bit of work to the development process.

# Alternatives
[alternatives]: #alternatives

We could decide not to keep a change log.

# Unresolved questions
[unresolved]: #unresolved-questions

None.