changelogging/lib.rs
1//! Building changelogs from fragments.
2//!
3//! # Example
4//!
5//! Please see the [readme] for an overview of this project and an example of using it.
6//!
7//! # Inspiration
8//!
9//! [Keep a Changelog](https://keepachangelog.com/) is the inspiration of this project.
10//!
11//! The [changelog] of `changelogging` is built using itself, which gives the "bootstrapping" vibe.
12//!
13//! # Terminology
14//!
15//! ## Changelogs
16//!
17//! *Changelogs* are files which document all notable changes between project versions.
18//! Each version of the project has its own *entry* in the changelog.
19//!
20//! ## Fragments
21//!
22//! *Fragments* are small pieces of information, which, combined together, form changelog *entries*.
23//!
24//! Fragments contain three things:
25//!
26//! - *id*, usually bound to something like *pull requests*;
27//! - *type*, for instance *change* or *feature*;
28//! - *content*, which gets written to the changelog.
29//!
30//! In `changelogging`, fragments are files which have names starting with `{id}.{name}`
31//! and contain fragment contents.
32//!
33//! ## Entries
34//!
35//! *Entries* describe changes between project versions. They are composed of *sections*.
36//!
37//! ## Sections
38//!
39//! *Sections* group and describe specific changes, e.g. *features*, *fixes*, *deprecations*, etc.
40//!
41//! # Configuration
42//!
43//! `changelogging` uses [TOML](https://github.com/toml-lang/toml) for its configuration.
44//!
45//! By default the application will look for the `changelogging.toml` file in the current directory.
46//! It also understands `pyproject.toml` if it contains the `[tool.changelogging]` section.
47//! In case both files are present, the former takes precedence.
48//!
49//! See [`config`] for configuration, [`context`] for contexts and [`workspace`]
50//! that combines configuration and context into one structure.
51//!
52//! # Usage
53//!
54//! This section assumes we have [this] configuration and the following [template].
55//!
56//! ## Globals
57//!
58//! - `--help (-h)` displays help information.
59//! - `--version (-V)` shows this application's version.
60//! - `--directory (-D)` changes the directory before doing anything.
61//! - `--config (-C)` specifies the configuration file to use.
62//!
63//! ## `create`
64//!
65//! The `create` command is used to create changelog fragments.
66//!
67//! The fragment content can be passed through the argument:
68//!
69//! ```console
70//! $ changelogging create --content "Added cool features!" 13.feature.md
71//! ```
72//!
73//! If the content is not provided, the placeholder gets written instead:
74//!
75//! ```console
76//! $ changelogging create 64.change.md
77//! $ cat changes/64.change.md
78//! Add the fragment content here.
79//! ```
80//!
81//! Let us add some content to this fragment:
82//!
83//! ```console
84//! $ echo "Changed some things!" > changes/64.change.md
85//! ```
86//!
87//! Alternatively, the default editor can be used to write the fragment content:
88//!
89//! ```console
90//! $ changelogging create --edit ~bug.fix.md
91//! ```
92//!
93//! And, inside the editor:
94//!
95//! ```md
96//! Fixed annoying bugs!
97//! ```
98//!
99//! Here are the options (except for [globals](#globals)) that `create` supports:
100//!
101//! - `--content (-c)` passes the content of the fragment through the argument.
102//! - `--edit (-e)` opens the default editor to enter the fragment's contents.
103//! - `--add (-a)` adds the fragment file via `git`.
104//!
105//! ## `preview`
106//!
107//! The `preview` command is used to preview changelog entries:
108//!
109//! ```console
110//! $ changelogging preview
111//! ## [0.7.0](https://github.com/nekitdev/changelogging/tree/v0.7.0) (YYYY-MM-DD)
112//!
113//! ### Features
114//!
115//! - Added cool features! ([#13](https://github.com/nekitdev/changelogging/pull/13))
116//!
117//! ### Changes
118//!
119//! - Changed some things! ([#64](https://github.com/nekitdev/changelogging/pull/64))
120//!
121//! ### Fixes
122//!
123//! - Fixed annoying bugs!
124//! ```
125//!
126//! Here are the options (except for [globals](#globals)) that `preview` supports:
127//!
128//! - `--date (-d)` specifies the date to use instead of today.
129//!
130//! ## `build`
131//!
132//! The `build` command is used to build changelog entries from fragments.
133//!
134//! After one ensures that the changelog entry is correct, building the changelog is as simple as:
135//!
136//! ```console
137//! $ changelogging build
138//! ```
139//!
140//! You can also see the [rendered] version.
141//!
142//! Here are the options (except for [globals](#globals)) that `build` supports:
143//!
144//! - `--date (-d)` specifies the date to use instead of today.
145//! - `--stage (-s)` stages the updated changelog via `git`.
146//! - `--remove (-r)` removes all fragment files with `git`.
147//!
148//! [changelog]: https://github.com/nekitdev/changelogging/blob/main/CHANGELOG.md
149//! [readme]: https://github.com/nekitdev/changelogging/blob/main/README.md
150//! [this]: https://github.com/nekitdev/changelogging/blob/main/changelogging.toml
151//! [template]: https://github.com/nekitdev/changelogging/blob/main/examples/TEMPLATE.md
152//! [rendered]: https://github.com/nekitdev/changelogging/blob/main/examples/CHANGELOG.md
153
154#![forbid(unsafe_code)]
155#![deny(missing_docs)]
156
157pub mod app;
158pub mod builder;
159pub mod commands;
160pub mod config;
161pub mod context;
162pub mod date;
163pub mod discover;
164pub mod fragment;
165pub mod git;
166pub mod init;
167pub mod load;
168pub mod workspace;