-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.qmd
172 lines (132 loc) · 9.23 KB
/
README.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
---
format: gfm
default-image-extension: ""
editor_options:
chunk_output_type: console
---
# autonewsmd
<!-- badges: start -->
```{r}
#| echo: false
#| message: false
#| results: asis
pkg <- desc::desc_get_field("Package")
cat_var <- paste(
badger::badge_lifecycle(),
badger::badge_cran_release(pkg = pkg),
gsub("summary", "worst", badger::badge_cran_checks(pkg = pkg)),
badger::badge_cran_download(pkg = pkg, type = "grand-total", color = "blue"),
badger::badge_cran_download(pkg = pkg, type = "last-month", color = "blue"),
gsub("netlify\\.com", "netlify.app", badger::badge_dependencies(pkg = pkg)),
badger::badge_github_actions(action = utils::URLencode("R CMD Check via {tic}")),
badger::badge_github_actions(action = "lint"),
badger::badge_github_actions(action = "test-coverage"),
badger::badge_codecov(ref = desc::desc_get_urls()),
sep = "\n"
)
cat_var |> cat()
```
<!-- badges: end -->
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/](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`](https://github.com/cookpete/auto-changelog) for JavaScript and [`auto-changelog`](https://github.com/KeNaCo/auto-changelog) for Python.
## Installation
You can install `autonewsmd` with:
```{r eval=FALSE}
install.packages("autonewsmd")
```
You can install the development version of `autonewsmd` with:
```{r eval=FALSE}
install.packages("remotes")
remotes::install_github("kapsner/autonewsmd")
```
## Supported Commit Types
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](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with--to-draw-attention-to-breaking-change).
<center>
| 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 |
</center>
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](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with--to-draw-attention-to-breaking-change)) is supported as well.
## Example
First of all, create a small repository with some commit messages.
```{r eval=FALSE}
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 = "[email protected]")
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.
```{r eval=FALSE}
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.
```{r eval=FALSE}
an$write(force = TRUE)
```
Now, we can verify that the file `NEWS.md` also appears in the git folder and check its content.
```{r eval=FALSE}
list.files(path)
#> [1] "example.txt" "NEWS.md"
```
```{r eval=FALSE}
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)"
```
## Used By
[autonewsmd](https://github.com/kapsner/autonewsmd/blob/main/NEWS.md), [sjtable2df](https://github.com/kapsner/sjtable2df/blob/main/NEWS.md), [rBiasCorrection](https://github.com/kapsner/rBiasCorrection/blob/master/NEWS.md), [BiasCorrector](https://github.com/kapsner/BiasCorrector/blob/master/NEWS.md), [DIZtools](https://github.com/miracum/misc-diztools/blob/main/NEWS.md), [DIZutils](https://github.com/miracum/misc-dizutils/blob/master/NEWS.md), [DQAstats](https://github.com/miracum/dqa-dqastats/blob/master/NEWS.md), [DQAgui](https://github.com/miracum/dqa-dqagui/blob/master/NEWS.md), [miRacumDQA](https://github.com/miracum/dqa-miracumdqa/blob/master/NEWS.md), [kdry](https://github.com/kapsner/kdry/blob/main/NEWS.md), [mlexperiments](https://github.com/kapsner/mlexperiments/blob/main/NEWS.md), [mllrnrs](https://github.com/kapsner/mllrnrs/blob/main/NEWS.md), [mlsurvlrnrs](https://github.com/kapsner/mlsurvlrnrs/blob/main/NEWS.md) [authors-block](https://github.com/kapsner/authors-block/blob/main/NEWS.md)
**(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`](./README.md) and create a pull request.)**
## Related R Packages
- [`newsmd`](https://github.com/Dschaykib/newsmd): manually add updates (version or bullet points) to the NEWS.md file
- [`fledge`](https://github.com/cynkra/fledge): to streamline the process of updating changelogs (NEWS.md) and versioning R packages developed in git repositories (also supporting conventional commits)
## TODOs:
- add options to format the changelog
- add more changelog style templates
- add support for [Commit message with scope](https://www.conventionalcommits.org/en/v1.0.0/#commit-message-with-scope)