changelog/
lib.rs

1// Copyright 2017-2018 by Aldrin J D'Souza.
2// Licensed under the MIT License <https://opensource.org/licenses/MIT>
3//! A generator for categorized change logs.
4//!
5//! This crate generates change logs (a.k.a release notes) that are typically distributed at project
6//! release milestones. Unlike other tools that do the same, this one does not require you to follow
7//! any particular git workflow conventions. All it assumes is that you'll pick a few *keywords* (or
8//! use the built-in ones) to annotate lines in your commit messages.
9//!
10//! When you wish to record a user visible change (e.g. new feature, bug fix, breaking change, etc.)
11//! you write a normal commit message and annotate some lines in it with your chosen keywords. The
12//! annotated lines are used at report generation time to organize changes into *categories* and
13//! *scopes*. The organized changes are then rendered as a pretty and accurate change log. Commit
14//! messages without tags are quietly ignored and you are free to tag as little or as much as you
15//! want.
16//!
17//! See [README] for details.
18//!
19//! # Usage
20//!
21//! Install the executable wrapper as follows:
22//!
23//! ```bash
24//! $ cargo install git-changelog
25//! ```
26//!
27//! Once on `PATH`, the tool works like a normal git sub-command (e.g. `git log`) and takes a
28//! [revision range] as input. It looks at all commits in the range and uses the keywords it finds
29//! in their messages to generate the report. Simple. 🙂
30//!
31//! ```bash
32//! $ git changelog v0.1.1..v0.2.0
33//! ```
34//!
35//! If you don't provide a revision range, `<last-tag>..HEAD` is used. If no tags are defined, just
36//! the last commit is picked.
37//!
38//! ```bash
39//! $ git changelog -d
40//! INFO: Reading file '/Users/aldrin/Code/git-changelog/.changelog.yml'
41//! INFO: Using revision range 'v0.2.0..HEAD (15 commits)'
42//! ...
43//! ```
44//!
45//! Note that using `-d` can you give you some insight into the tool operations. For more complex range
46//! selections you can use `git log` arguments as shown below:
47//!
48//! ```bash
49//! $ git changelog -- --author aldrin --reverse --since "1 month ago"
50//! ```
51//!
52//! Note the `--` before you start the `git log` arguments.
53//!
54//! # Library Usage
55//!
56//! The crate functionality is also usable as a library as shown below:
57//!
58//! ```toml
59//! [dependencies]
60//! git-changelog = "0.3"
61//! ```
62//!
63//! ```rust
64//! extern crate changelog;
65//! println!("{}", changelog::ChangeLog::new());
66//! ```
67//!
68//! The configuration used in simple example shown above is picked from the repository configuration
69//! file (if one is found) or from built-in defaults. Advanced usage can programmatically manage
70//! these as follows:
71//!
72//! ```rust
73//! use changelog::{Configuration, Keyword, ChangeLog};
74//!
75//! // Create a custom configuration
76//! let mut config = Configuration::new();
77//!
78//! // Pick the category or scope keywords that match your project conventions
79//! config.conventions.categories.push(Keyword::new("feature", "New Features"));
80//! config.conventions.categories.push(Keyword::new("break", "Breaking Changes"));
81//!
82//! // Pick the range of commits
83//! let range = "v0.1.1..v0.2.0";
84//!
85//! // Generate a changelog for the range with the configuration
86//! let changelog = ChangeLog::from_range(range, &config);
87//!
88//! // Pick output preferences
89//! config.output.json = true;
90//!
91//! // Render
92//! assert!(changelog::render(&changelog, &config.output).is_ok());
93//! ```
94//! [revision range]: https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#double_dot
95//! [README]: https://github.com/aldrin/git-changelog/blob/master/README.md
96
97extern crate chrono;
98#[macro_use]
99extern crate failure;
100extern crate handlebars;
101#[macro_use]
102extern crate log;
103#[macro_use]
104extern crate nom;
105extern crate regex;
106#[macro_use]
107extern crate serde_derive;
108extern crate serde_json;
109extern crate serde_yaml;
110
111mod git;
112mod input;
113mod commit;
114mod output;
115mod changelog;
116
117pub use git::in_git_repository;
118pub use input::Configuration;
119pub use input::Conventions;
120pub use input::OutputPreferences;
121pub use input::Keyword;
122pub use input::PostProcessor;
123pub use input::TEMPLATE_FILE;
124pub use input::CONFIG_FILE;
125pub use commit::Commit;
126pub use commit::CommitList;
127pub use commit::CommitMessage;
128pub use changelog::ChangeLog;
129pub use changelog::Category;
130pub use changelog::Scope;
131pub use output::render;
132
133pub type Result<T> = std::result::Result<T, failure::Error>;
changelog/lib.rs

changelog/
lib.rs
