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 for other languages are, for example, auto-changelog
for JavaScript and auto-changelog
for Python.
First of all, for demonstration purposes, a small git repository will be created 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")
#> [149b664] 2022-08-27: 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")
#> [72729e7] 2022-08-27: 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()# View the list
an$repo_list
#> $v0.0.1
#> $v0.0.1$commits
#> sha summary
#> 1: 72729e77c3bb83966e6504b01e6317de0411b60c refactor: added second phrase
#> 2: 149b664edc37b692048003e00d5eb3e01ca255c0 feat: new file example.txt
#> message author email when
#> 1: refactor: added second phrase Alice alice@example.org 2022-08-27 21:27:41
#> 2: feat: new file example.txt Alice alice@example.org 2022-08-27 21:27:39
#> sha_seven type clean_summary tag tag_before
#> 1: 72729e7 Refactorings added second phrase v0.0.1 v0.0.1
#> 2: 149b664 New features new file example.txt v0.0.1 <NA>
#>
#> $v0.0.1$latest_date
#> [1] "2022-08-27"
#>
#> $v0.0.1$sha_from
#> [1] "149b664edc37b692048003e00d5eb3e01ca255c0"
#>
#> $v0.0.1$sha_to
#> [1] "72729e77c3bb83966e6504b01e6317de0411b60c"
#>
#> $v0.0.1$tag_from
#> [1] "149b664"
#>
#> $v0.0.1$tag_to
#> [1] "v0.0.1"
#>
#> $v0.0.1$full_changes
#> [1] "Full set of changes: [`149b664...v0.0.1`](https://example.org/git2r/foobar/compare/149b664...v0.0.1)"Executing the $write()-method, the changelog is written
to the path specified with the repo_path-argument (CAUTION:
this method overwrites the changelog without any warning).
an$write()
#> processing file: news-md-template.Rmd
#> output file: news-md-template.knit.md
#> /usr/lib/rstudio-server/bin/quarto/bin/tools/pandoc +RTS -K512m -RTS news-md-template.knit.md --to markdown_strict-yaml_metadata_block --from markdown+autolink_bare_uris+tex_math_single_backslash --output /tmp/RtmpIlbo7c/autonewsmd/NEWS.md
#>
#> Output created: /tmp/RtmpIlbo7c/autonewsmd/NEWS.mdNow, we can verify that the file NEWS.md also appears in
the git folder and check its content.
list.files(path)
#> [1] "NEWS.md" "example.txt"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 example.txt"
#> [8] " ([149b664](https://example.org/git2r/foobar/tree/149b664edc37b692048003e00d5eb3e01ca255c0))"
#> [9] ""
#> [10] "#### Refactorings"
#> [11] ""
#> [12] "- added second phrase"
#> [13] " ([72729e7](https://example.org/git2r/foobar/tree/72729e77c3bb83966e6504b01e6317de0411b60c))"
#> [14] ""
#> [15] "Full set of changes:"
#> [16] "[`149b664...v0.0.1`](https://example.org/git2r/foobar/compare/149b664...v0.0.1)"To see, how the changelog file builds up, the new file can also be added and committed.
Sys.sleep(2)
git2r::add(repo, "NEWS.md")
git2r::commit(repo, "chore: added news.md file")
#> [fcb473e] 2022-08-27: chore: added news.md file
an$generate()
an$write()
#> processing file: news-md-template.Rmd
#> output file: news-md-template.knit.md
#> /usr/lib/rstudio-server/bin/quarto/bin/tools/pandoc +RTS -K512m -RTS news-md-template.knit.md --to markdown_strict-yaml_metadata_block --from markdown+autolink_bare_uris+tex_math_single_backslash --output /tmp/RtmpIlbo7c/autonewsmd/NEWS.md
#>
#> Output created: /tmp/RtmpIlbo7c/autonewsmd/NEWS.mdnewsmd <- readLines(file.path(path, "NEWS.md"))
newsmd
#> [1] "# TestRepo NEWS"
#> [2] ""
#> [3] "## Unreleased (2022-08-27)"
#> [4] ""
#> [5] "#### Other changes"
#> [6] ""
#> [7] "- added news.md file"
#> [8] " ([fcb473e](https://example.org/git2r/foobar/tree/fcb473e25df99cb741a7a759254963e3157b79a1))"
#> [9] ""
#> [10] "## v0.0.1 (2022-08-27)"
#> [11] ""
#> [12] "#### New features"
#> [13] ""
#> [14] "- new file example.txt"
#> [15] " ([149b664](https://example.org/git2r/foobar/tree/149b664edc37b692048003e00d5eb3e01ca255c0))"
#> [16] ""
#> [17] "#### Refactorings"
#> [18] ""
#> [19] "- added second phrase"
#> [20] " ([72729e7](https://example.org/git2r/foobar/tree/72729e77c3bb83966e6504b01e6317de0411b60c))"
#> [21] ""
#> [22] "Full set of changes:"
#> [23] "[`149b664...v0.0.1`](https://example.org/git2r/foobar/compare/149b664...v0.0.1)"Besides repo_name and repo_path, there are
some other (optional) configurations available. The file name can be
modified with the field $file_name. Typically, the file
name is NEWS or CHANGELOG.
an$file_name
#> [1] "NEWS"Furthermore, the ending of the changelog file can be set with
$file_ending. This defaults to .md, but could,
for example, also be .txt or even an empty string.
an$file_ending
#> [1] ".md"A very important configuration is the tag_pattern. This
regular expression is used to identify release tags, which are used to
create the subsections of the changelog file. This field defaults to
"^v(\\d+\\.){2}\\d+(\\.\\d+)?$" to identify patterns of the
from v0.0.1.9001.
an$tag_pattern
#> [1] "^v(\\d+\\.){2}\\d+(\\.\\d+)?$"