PR Log

Turn GitHub pull requests into changelog entries.

Assumptions

Changelogs should be written for humans by humans

PrLog does not try to auto generate a complete changelog. Instead, it pulls GitHub data to prefill your changelog as a baseline for manual editing. Add prose, order items by priority, insert headers.

Merged pull requests fully describe project history

PrLog ignores GitHub issues. If a pull request fixes an important issue it can reference it in its title or description.

Pull requests are tagged with version milestones

PrLog expects pull requests to be assigned to version milestones like v1.1. This ensures consistency with the issue tracker and helps limit GitHub API requests to relevant data.

Changelogs are written in Markdown

Markdown is the de facto standard for formatting files to be displayed on GitHub.

Installation

Install the command line tool:

$ gem install pr_log

Generate a personal access token and place it in a .pr_log.yml file in your home directory:

# ~/.pr_log.yml
access_token: "xxx"

Usage

To insert items for new pull requests with milestone v.1.2 into your CHANGELOG.md file run:

$ prlog fetch --github-repository some/repository --milestone v1.2

By default, this creates entries of the form:

- Title of the pull request
  ([#100](https://github.com/some/repository/pull/100)))

If a pull request URL is already mentioned in the changelog, no entry will be created.

Convention over Configuration

The fetch command can also be invoked without command line options:

$ prlog fetch

PrLog tries to derive defaults from gemspec information:

• If the homepage attribute mentions the URL of the github repository, it is used to determine the github repository name.
• PrLog constructs a milestone name of the form v%{major}.%{minor} from the current gem version.

Configuration

To override PrLog's default configuration you can either pass command line options or place a .pr_log.yml file inside your project's root or your home directory:

# .pr_log.yml
changelog_file: "HISTORY.md"

The following configuration options are available:

• access_token: Personal access token to use for GitHub API requests.

• changelog_file: Relative path to the changelog file.

• entry_template: Template string used for new changelog entries. All fields from the issue search response can be used as interpolations. Default value: - %{title} ([#%{number}](%{html_url})). Use . for nested fields (e.g. %{user.login}).

• github_repository: Name of the GitHub repository of the form user/repository.

• insert_after: Regular expression or string matching the line inside the changelog after which new items shall be inserted.

• label_prefixes: A hash mapping GitHub label names to title prefixes for changelog entries. See below for details.

• milestone: Name of the milestone filter fetched pull requests by.

• milestone_format: Template string used to derive a milestone name from the current gem version. The strings %{major}, %{minor} and %{patch} are replaces with the corresponding numeric component of the current version. Default value: v%{major}.%{minor}.

Label Prefixes

Items for pull requests with certain labels can be prefixed with a string automatically. To add a "Bug fix:" prefix to all pull requests with the label bug, add the following lines to your configuration file:

# pr_log.yml
label_prefixes:
  bug: "Bug fix:"

Development

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

Running the Test Suite

Ensure the environment variable PR_LOG_FIXTURE_OAUTH_TOKEN is set to a valid GitHub access token. Then run bin/rspec. The test suite uses VCR to record and replay requests to the GitHub API. Fixture data used by the test suite comes from the tf/pr_log_test_fixture repository.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/tf/pr_log. 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.

License

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