The purpose of the autonewsmd R package is to bring the power of
conventional commit messages to the R community. There is no need
anymore to tediously maintain a changelog file manually. If you are
using conventional commit messages, autonewsmd will do that for you
and automatically generate a human readable changelog file directly from
the repository’s git history.
Conventional commit messages
(https://www.conventionalcommits.org/en/v1.0.0/) come with some easy
rules to create human readable commit messages for a git history. One
advantage is that following these conventions, these messages are also
machine readable and automated tools can run on top of them in order to,
e.g., generate beautiful changelogs out of them. Similar tools written
in other programming languages are, for example,
auto-changelog for
JavaScript and
auto-changelog for Python.
You can install autonewsmd with:
install.packages("autonewsmd")You can install the development version of autonewsmd with:
install.packages("remotes")
remotes::install_github("kapsner/autonewsmd")The default changelog template organizes commits according to their
association with specific tags. The tags form the headings of the
changelog file and are sorted in decreasing order according to their
release dates. The following table lists the commit types that are
currently supported by autonewsmd. To be correctly recognized by
autonewsmd, it is important that the formatting of the commit messages
follow the conventions described
here.
| Type | Changelog Subheading |
|---|---|
| feat: | New features |
| fix: | Bug fixes |
| refactor: | Refactorings |
| perf: | Performance |
| build: | Build |
| test: | Tests |
| ci: | CI |
| docs: | Docs |
| style: | Style |
| chore: | Other changes |
If any commit type includes BREAKING CHANGE in its commit message’s
body or footer, the subheading Breaking changes is included as
first subheading within the respective sections. Furthermore, the
detection of breaking changes using the exclamation mark (!) between
the type description and the colon (as described
here)
is supported as well.
First of all, create a small repository with some commit messages.
library(autonewsmd)
# (Example is based on the public examples from the `git2r` R package)
## Initialize a repository
path <- file.path(tempdir(), "autonewsmd")
dir.create(path)
repo <- git2r::init(path)
## Config user
git2r::config(repo, user.name = "Alice", user.email = "alice@example.org")
git2r::remote_set_url(repo, "foobar", "https://example.org/git2r/foobar")
## Write to a file and commit
lines <- "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do"
writeLines(lines, file.path(path, "example.txt"))
git2r::add(repo, "example.txt")
git2r::commit(repo, "feat: new file example.txt")
## Write again to a file and commit
Sys.sleep(2) # wait two seconds, otherwise, commit messages have same time stamp
lines2 <- paste0(
"eiusmod tempor incididunt ut labore et dolore magna aliqua. ",
"Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris ",
"nisi ut aliquip ex ea commodo consequat."
)
write(lines2, file.path(path, "example.txt"), append = TRUE)
git2r::add(repo, "example.txt")
git2r::commit(repo, "refactor: added second phrase")
## Also add a tag here
git2r::tag(repo, "v0.0.1")Then, instantiate an autonewsmd object. Here, you must provide the
repo_name (this argument is used to compose the title of the changelog
file). The repo_path-argument can be provided optionally and defaults
to the current working directory ("."). The repo_path should be the
root of a git repository. The $generate()-method creates a list with
all commit messages that is used for rendering the changelog file.
an <- autonewsmd$new(repo_name = "TestRepo", repo_path = path)
an$generate()Executing the $write()-method, the changelog is written to the path
specified with the repo_path-argument. If force = FALSE (the
default), a dialog is prompted to ask the user if the file should be
(over-) written.
an$write(force = TRUE)Now, we can verify that the file NEWS.md also appears in the git
folder and check its content.
list.files(path)
#> [1] "example.txt" "NEWS.md"newsmd <- readLines(file.path(path, "NEWS.md"))
newsmd
#> [1] "# TestRepo NEWS"
#> [2] ""
#> [3] "## v0.0.1 (2022-08-27)"
#> [4] ""
#> [5] "#### New features"
#> [6] ""
#> [7] "- new file"
#> [8] " ([22b8453](https://example.org/git2r/foobar/tree/22b845346a0f3686d79eb86445af6be71dc86da6))"
#> [9] ""
#> [10] "#### Refactorings"
#> [11] ""
#> [12] "- added second phrase"
#> [13] " ([ec510eb](https://example.org/git2r/foobar/tree/ec510ebb465d25ab7ad27e8b637cf4113b55cbdf))"
#> [14] ""
#> [15] "Full set of changes:"
#> [16] "[`22b8453...v0.0.1`](https://example.org/git2r/foobar/compare/22b8453...v0.0.1)"autonewsmd, sjtable2df, rBiasCorrection, BiasCorrector, DIZtools, DIZutils, DQAstats, DQAgui, miRacumDQA, kdry, mlexperiments, mllrnrs, mlsurvlrnrs authors-block
(If you are using autonewsmd and you like to have your repository
listed here, please add the link pointing to the changelog file to this
README.md and create a pull request.)
newsmd: manually add updates (version or bullet points) to the NEWS.md filefledge: to streamline the process of updating changelogs (NEWS.md) and versioning R packages developed in git repositories (also supporting conventional commits)
- add options to format the changelog
- add more changelog style templates
- add support for Commit message with scope