Crate changelog

Expand description

A generator for categorized change logs.

This crate generates change logs (a.k.a release notes) that are typically distributed at project release milestones. Unlike other tools that do the same, this one does not require you to follow any particular git workflow conventions. All it assumes is that you’ll pick a few keywords (or use the built-in ones) to annotate lines in your commit messages.

When you wish to record a user visible change (e.g. new feature, bug fix, breaking change, etc.) you write a normal commit message and annotate some lines in it with your chosen keywords. The annotated lines are used at report generation time to organize changes into categories and scopes. The organized changes are then rendered as a pretty and accurate change log. Commit messages without tags are quietly ignored and you are free to tag as little or as much as you want.

See README for details.

§Usage

Install the executable wrapper as follows:

$ cargo install git-changelog

Once on PATH, the tool works like a normal git sub-command (e.g. git log) and takes a revision range as input. It looks at all commits in the range and uses the keywords it finds in their messages to generate the report. Simple. 🙂

$ git changelog v0.1.1..v0.2.0

If you don’t provide a revision range, <last-tag>..HEAD is used. If no tags are defined, just the last commit is picked.

$ git changelog -d
INFO: Reading file '/Users/aldrin/Code/git-changelog/.changelog.yml'
INFO: Using revision range 'v0.2.0..HEAD (15 commits)'
...

Note that using -d can you give you some insight into the tool operations. For more complex range selections you can use git log arguments as shown below:

$ git changelog -- --author aldrin --reverse --since "1 month ago"

Note the -- before you start the git log arguments.

§Library Usage

The crate functionality is also usable as a library as shown below:

[dependencies]
git-changelog = "0.3"

extern crate changelog;
println!("{}", changelog::ChangeLog::new());

The configuration used in simple example shown above is picked from the repository configuration file (if one is found) or from built-in defaults. Advanced usage can programmatically manage these as follows:

use changelog::{Configuration, Keyword, ChangeLog};

// Create a custom configuration
let mut config = Configuration::new();

// Pick the category or scope keywords that match your project conventions
config.conventions.categories.push(Keyword::new("feature", "New Features"));
config.conventions.categories.push(Keyword::new("break", "Breaking Changes"));

// Pick the range of commits
let range = "v0.1.1..v0.2.0";

// Generate a changelog for the range with the configuration
let changelog = ChangeLog::from_range(range, &config);

// Pick output preferences
config.output.json = true;

// Render
assert!(changelog::render(&changelog, &config.output).is_ok());

Structs§

Category: Changes grouped by categories (e.g. “Fixes”, “Breaking Changes”, etc.).
ChangeLog: A categorized changelog
Commit: A single commit
CommitList: A list of commit revisions
CommitMessage: The commit message
Configuration: The tool configuration.
Conventions: The change categorization conventions used by a repository/project.
Keyword: A keyword used to categorize commit message lines.
OutputPreferences: The output preferences
PostProcessor: A post-processor definition.
Scope: Changes grouped by scope (e.g. “API”, “Documentation”, etc.).

Constants§

CONFIG_FILE: The YAML configuration file name (.changelog.yml).
TEMPLATE_FILE: The Handlebars template file name (.changelog.hbs).

Functions§

in_git_repository: Check if we’re in an git repository?
render: Render the changelog with the given output preferences

Type Aliases§

Result