StructuredChangelog

• With A Single Contributor
• With Multiple Contributors
• Viewing Release Notes
• Other Rake Tasks
• Installation
• Contributing
  • Development
  • Testing
  • Pull Requests
  • Releases
• License

You have a changelog in your gem’s repo, right? Great! Then you’ll never need to manually update your VERSION constant again!

Install the gem and add this line to your Rakefile:

require 'structured_changelog/tasks'

With A Single Contributor

If you have a single-contributor project, you can simply add release lines to CHANGELOG.md:

* FEATURE: we added a new thing
* FIX: we fixed a broken thing

then when you want to cut a release, add a "## RELEASE X.Y.Z" section, making the above look like:

## RELEASE X.Y.Z

* FEATURE: we added a new thing
* FIX: we fixed a broken thing

and run

$ rake changelog:release

This will:

1. validate your CHANGELOG.md

2. set your gem’s VERSION constant to the latest release version specified by your CHANGELOG.md

3. commit that version bump

4. package your gem and push it to the specified gem server (rubygems.org by default)

With Multiple Contributors

If you have multiple contributors, and you follow the single-contributor workflow, you’ll end up with git merge conflicts every time different contributes add lines to the changelog in different Pull Requests. Fortunately, there’s a separate workflow for projects with multiple contributors.

ℹ️	Even though it was expliticitly designed for projects with multiple contributors, this workflow works just as well for projects with a single author—​in fact I use it for structured_changelog.

When you want to add release notes, instead of adding them directly to the changelog, add them to any git commit:

Describe what I did this commit

More description goes here

* FIX: we fixed a thing that was broken

Any line in a commit message that starts with any of the following will be included in the release notes for the next version:

• * BREAKING: or BREAKING:

• * FEATURE: or FEATURE:

• * ENHANCEMENT: or ENHANCEMENT:

• * FIX: or FIX:

• * DEPRECATION: or DEPRECATION:

(We accept either with or without the asterisks so that forgetting one isn’t actually a problem).

Then, when you’re ready to cut a release, run:

$ rake changelog:compile

This will pull all the release lines you’ve written in git commit messages since the last release from the commit log, and create a new release section in your changelog. It will have the minimum version possible given the change types (BREAKING is a major bump, FEATURE is a minor bump, and FIX, ENHANCEMENT, and DEPRECATION are all patch bumps).

Once the rake task has written the new section to the changelog, it’s often beneficial to give it a look and make sure it’s free of typos and any other mistakes. Then, run

$ rake changelog:release

as usual to actually release your gem.

Viewing Release Notes

To view the release notes of the current release:

$ rake changelog:notes

$ rake changelog:notes[current]

To view the release notes of every release:

$ rake changelog:notes[all]

for a specific release:

$ rake changelog:notes[1.0.4]

for all releases inclusively after a given release:

$ rake changelog:notes[1.0.4 <]

for all releases inclusively before a given release:

$ rake changelog:notes[< 2.0.4]

for all releases inclusively between two releases:

$ rake changelog:notes[1.0.4 < 2.0.4]

To view the last 3 releases:

$ rake changelog:recent

To view the last N releases:

$ rake changelog:recent[N]

Other Rake Tasks

To determine the version of the latest release according to the Changelog:

$ rake changelog:version

To validate your changelog:

$ rake changelog:validate

To update your gem’s VERSION constant to the latest release in your Changelog:

$ rake changelog:sync

To commit your version bump—​and only your version bump:

$ rake changelog:commit

To do everything but release your code (so that it can go through a PR for CI, for instance):

$ rake changelog:prep

Installation

Add this line to your application’s Gemfile:

gem 'structured_changelog'

And then execute

$ bundle install

Or, install it yourself with

$ gem install structured_changelog

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/yarmiganosca/structured_changelog.

❗	Code of Conduct This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Testing

To run all the tests, run

$ bundle exec rspec

Pull Requests

Pull requests should be well-scoped and include tests appropriate to the changes.

When submitting a pull request that changes user-facing behavior, add release note lines to the commit message body like this. You can preview your release lines by running

$ bundle exec rake changelog:preview

Releases

Releasing a new version is a 2-step process.

First, run

$ bundle exec rake changelog:compile

This will add a new release section before the other release sections. It will contain all the release notes in the commit messages since the last release, and will be prepopulated with the minimum possible version given those changes. Proof-read it and reorder the notes if you think doing so would be necessary or clearer. Feel free to increase the version if necessary (to force a major release, for example).

Once you’re satisfied, run

$ bundle exec rake changelog:release

This will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

License

The gem is available as open source under the terms of the MIT License.