---
title: "Fledge internals"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Fledge internals}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

```{r setup}
library(fledge)
```

## Implementation

The following sections explain how things actually work inside fledge.

### Updating `NEWS.md`

New entries are added to `NEWS.md` from commit messages to commits in `master`.

* Only top-level commits are considered (roughly equivalent to `git log --first-parent`.)
    The messages from these commits are parsed.
    Only lines that start with a star `*` or a dash `-` are included.
* If a line starts with three dashes, then everything past that line is excluded.
    Example: the following commit message

    ```
    Merge f-fancy-feature to master, closes #5678

    - Added fancy feature (#5678).

    - Fixed bug as a side effect (#9012).

    ---

    The fancy feature consists of the components:

    - foo
    - bar
    - baz
    ```

    will be added as below to `NEWS.md`:

    ```
    - Added fancy feature (#5678).
    - Fixed bug as a side effect (#9012).
    ```

When retrieving the current NEWS for defining the tag message, the entries between the first two first-level headers (starting with `#`) are returned.
You can use second and third level headers and add as many empty lines as you want.

### Collecting NEWS

The first function to call at any stage is always `bump_version()`. This does the following

1. Calls `update_news()` to collect NEWS entries from top-level commits.

2. Calls `update_version()` to increment the version in `DESCRIPTION` and add a header to `NEWS.md`.

### Tagging for "dev" vs. other releases

`bump_version()` continues depending on the release type:

*  `"dev"` releases: Calls `finalize_version()` to commit `DESCRIPTION` and `NEWS.md`.
    Also creates a tag with a message.
    You can always edit `NEWS.md` and call `finalize_version()` again. Both the commit and the tag will be updated.
*  Other releases: Calls `commit_version()` to commit `DESCRIPTION` and `NEWS.md` without tagging.
    In this stage, you can edit `NEWS.md` and commit as much as you like.
    The tag is created only after you use `tag_version()` manually.