fix: readded vignette

kapsner · Oct 15, 2024 · 6174204 · 6174204
1 parent c9b7046
commit 6174204
Showing 1 changed file with 231 additions and 0 deletions.
diff --git a/vignettes/autonews.qmd b/vignettes/autonews.qmd
@@ -0,0 +1,231 @@
+---
+title: "autonewsmd"
+vignette: >
+  %\VignetteIndexEntry{autonewsmd}
+  %\VignetteEncoding{UTF-8}
+  %\VignetteEngine{quarto::html}
+editor_options:
+  chunk_output_type: console
+execute:
+  eval: false
+  collapse: true
+  comment: "#>"
+---
+
+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 for other 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.
+
+## 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/).
+
+<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.
+
+Please also refer to the [`README`](https://github.com/kapsner/autonewsmd#autonewsmd) for further information.
+
+## Example
+
+First of all, for demonstration purposes, a small git repository will be created with some commit messages.
+
+```{r creategit}
+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 instantiatenmd}
+an <- autonewsmd$new(repo_name = "TestRepo", repo_path = path)
+an$generate()
+```
+
+```{r viewrepolist}
+# View the list
+an$repo_list
+#> $v0.0.1
+#> $v0.0.1$commits
+#>                                         sha                       summary                       message author
+#> 1: c75e13af49dd99ab70f621717c4bf585001b82d0 refactor: added second phrase refactor: added second phrase  Alice
+#> 2: f66d96d2362df21a0685b3636b43438f51814455    feat: new file example.txt    feat: new file example.txt  Alice
+#>                email                when sha_seven         type        clean_summary    tag tag_before
+#> 1: [email protected] 2022-09-02 06:31:20   c75e13a Refactorings  added second phrase v0.0.1     v0.0.1
+#> 2: [email protected] 2022-09-02 06:31:18   f66d96d New features new file example.txt v0.0.1       <NA>
+#>
+#> $v0.0.1$latest_date
+#> [1] "2022-09-02"
+#>
+#> $v0.0.1$sha_from
+#> [1] "f66d96d2362df21a0685b3636b43438f51814455"
+#>
+#> $v0.0.1$sha_to
+#> [1] "c75e13af49dd99ab70f621717c4bf585001b82d0"
+#>
+#> $v0.0.1$tag_from
+#> [1] "f66d96d"
+#>
+#> $v0.0.1$tag_to
+#> [1] "v0.0.1"
+#>
+#> $v0.0.1$full_changes
+#> [1] "Full set of changes: [`f66d96d...v0.0.1`](https://example.org/git2r/foobar/compare/f66d96d...v0.0.1)"
+```
+
+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 writenmd}
+an$write(force = TRUE)
+#> processing file: autonewsmd-5272f03178-news-md-template.qmd
+#> output file: autonewsmd-5272f03178-news-md-template.knit.md
+#> /usr/lib/rstudio-server/bin/quarto/bin/tools/pandoc +RTS -K512m -RTS autonewsmd-5272f03178-news-md-template.knit.md --to markdown_strict-yaml_metadata_block --from markdown+autolink_bare_uris+tex_math_single_backslash --output /tmp/RtmpY9K0uU/autonewsmd/NEWS.md
+#>
+#> Output created: /tmp/RtmpY9K0uU/autonewsmd/NEWS.md
+```
+
+Now, we can verify that the file `NEWS.md` also appears in the git folder and check its content.
+
+```{r listfiles}
+list.files(path)
+#> [1] "example.txt" "NEWS.md"
+```
+
+```{r readnmd}
+newsmd <- readLines(file.path(path, "NEWS.md"))
+newsmd
+#>  [1] "# TestRepo NEWS"
+#>  [2] ""
+#>  [3] "## v0.0.1 (2022-09-02)"
+#>  [4] ""
+#>  [5] "#### New features"
+#>  [6] ""
+#>  [7] "-   new file example.txt"
+#>  [8] "    ([f66d96d](https://example.org/git2r/foobar/tree/f66d96d2362df21a0685b3636b43438f51814455))"
+#>  [9] ""
+#> [10] "#### Refactorings"
+#> [11] ""
+#> [12] "-   added second phrase"
+#> [13] "    ([c75e13a](https://example.org/git2r/foobar/tree/c75e13af49dd99ab70f621717c4bf585001b82d0))"
+#> [14] ""
+#> [15] "Full set of changes:"
+#> [16] "[`f66d96d...v0.0.1`](https://example.org/git2r/foobar/compare/f66d96d...v0.0.1)"
+```
+
+To see, how the changelog file builds up, the new file can also be added and committed.
+
+```{r addnmd}
+Sys.sleep(2)
+git2r::add(repo, "NEWS.md")
+git2r::commit(repo, "chore: added news.md file")
+#> [07b6c39] 2022-09-02: chore: added news.md file
+an$generate()
+an$write(force = TRUE)
+#> processing file: autonewsmd-52215e4b2b-news-md-template.qmd
+#> output file: autonewsmd-52215e4b2b-news-md-template.knit.md
+#> /usr/lib/rstudio-server/bin/quarto/bin/tools/pandoc +RTS -K512m -RTS autonewsmd-52215e4b2b-news-md-template.knit.md --to markdown_strict-yaml_metadata_block --from markdown+autolink_bare_uris+tex_math_single_backslash --output /tmp/RtmpY9K0uU/autonewsmd/NEWS.md
+#>
+#> Output created: /tmp/RtmpY9K0uU/autonewsmd/NEWS.md
+```
+
+```{r readnmd2}
+newsmd <- readLines(file.path(path, "NEWS.md"))
+newsmd
+#>  [1] "# TestRepo NEWS"
+#>  [2] ""
+#>  [3] "## Unreleased (2022-09-02)"
+#>  [4] ""
+#>  [5] "#### Other changes"
+#>  [6] ""
+#>  [7] "-   added news.md file"
+#>  [8] "    ([07b6c39](https://example.org/git2r/foobar/tree/07b6c390bf728cf6e19a991dabe7cb8f1cad1ad6))"
+#>  [9] ""
+#> [10] "## v0.0.1 (2022-09-02)"
+#> [11] ""
+#> [12] "#### New features"
+#> [13] ""
+#> [14] "-   new file example.txt"
+#> [15] "    ([f66d96d](https://example.org/git2r/foobar/tree/f66d96d2362df21a0685b3636b43438f51814455))"
+#> [16] ""
+#> [17] "#### Refactorings"
+#> [18] ""
+#> [19] "-   added second phrase"
+#> [20] "    ([c75e13a](https://example.org/git2r/foobar/tree/c75e13af49dd99ab70f621717c4bf585001b82d0))"
+#> [21] ""
+#> [22] "Full set of changes:"
+#> [23] "[`f66d96d...v0.0.1`](https://example.org/git2r/foobar/compare/f66d96d...v0.0.1)"
+```
+
+## Further configurations
+
+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`.
+
+```{r fn}
+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.
+
+```{r fe}
+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`.
+
+```{r tp}
+an$tag_pattern
+#> [1] "^v(\\d+\\.){2}\\d+(\\.\\d+)?$"
+```
+
+```{r nolintend, include=FALSE}
+# nolint end
+```