Get started with fledge


Do you want to provide a changelog ( more informative than “bug fixes and performance improvements” ( to the users of your package?

Ways to achieve that are:

Using fledge is a discipline / a few habits that is worth learning!

What you need to do in practice is:

- Add support for bla databases.


- Add support for bla databases.


Also tweak the CI workflow accordingly. :sweat_smile:

For informative commit messages refer to the Tidyverse style guide.

These habits are worth learning!

Installation & setup

Once per machine

Install from cynkra’s R-universe using:

install.packages("fledge", repos = "")

Or install from GitHub using:


If you are used to making workflow packages (e.g. devtools) available for all your interactive work, you might enjoy loading fledge in your .Rprofile.

Once per package


{fledge} consists of the following functions that enable versioning at different stages through the package development lifecycle.

Function Name Description Stage Applicable
bump_version(which) Increments the package version based on argument. (Version format supported Configuration, Development, Release
finalize_version() Finalize the package version Configuration, Development
commit_version() Commits and DESCRIPTION to Git. Release
tag_version() Parses and creates/updates the tag for the most recent version. Release
update_news() Update with messages from top level commits Used by bump_version()
update_version() Update and DESCRIPTION with a new version Used by bump_version()


The following sections show how to combine these functions at different stages with any R package on GitHub. All {fledge} commands should be issued from the package directory of the target R package.

Initial Configuration

{fledge} assumes that the target R package is version-controlled with Git in a dedicated repository. The following steps are required to set up {fledge} for first time use, with your package.

  1. Call bump_version() as given below to set the package version

  2. Edit if required (typo fixes, rephrasing, grouping).

  3. Call finalize_version() as given below to update


You are all set to switch to the development stage now. Ensure that you use bullet points (* or -) in your commit or merge messages to indicate the messages that you want to include in Use finalize_version(push = TRUE) to push to the remote repository (e.g. GitHub) in one swoop.


{fledge} aims to update and DESCRIPTION correctly whenever a new version is assigned. In order to do this, the following steps need to be included throughout the development workflow.

  1. In commit messages to your main branch (typically main or master), mark everything that should go to with a bullet point (- or *). This is applicable to single commits, merge commits, or squash commits from pull requests. Do not edit manually.

  2. When you want to assign a version number to the current state of your R package e.g. at the end of the day or before a break, call


    The default argument for bump_version is “dev”. So the dev part of the version number will be updated. It is good practice to assign a new version number before switching focus to another project.

  3. Edit if required (typo fixes, rephrasing, grouping).

  4. Call finalize_version(): fledge::finalize_version(). This achieves the following:

    • is now composed, based on the most recent commit messages. To understand how is updated by fledge, see the section on implementation.
    • A new version number is assigned automatically (this is modeled after usethis::use_version()).
    • A tag matching the version number is assigned automatically, with the most recent messages included in the tag’s message.

Releasing to CRAN

When you want to release your package to CRAN, follow the steps below:

  1. Call bump_version() with the appropriate argument ("patch", "major", "minor"). e.g.,

  2. Edit, convert the “change log” to “release notes” – a higher-level description of features and bug fixes (typo fixes, rephrasing, grouping).

  3. Call commit_version() as below

  4. Make any necessary adjustments before releasing to CRAN depending on results of preparatory / incoming checks.

  5. Once the release/changes have been accepted by CRAN, use the following calls to tag the released version and to switch to a development version immediately.

  6. Return to development mode!

FAQ & edge cases

At least we think these questions could be asked. Feel free to also ask us questions!

But what if I want to edit manually?

You still can!

What if a contributor wants to contribute a NEWS item?

If someone opens a PR, with fledge the information about the changes should be entered in the message for the merge or squash commit. Now you could still advise contributors to provide a summary of the change as a comment to the PR.

Does this mean “Fix #42” will appear in

If you want to fix an issue with a commit message you can

- Adds support for coolness (#42, @contributor).


Fix #42

Edge cases

git push origin :vx.y.z.9www

(where x.y.z.9www is the new version) to delete the newly created remote tag. This is the reason why {fledge} only tags "dev" releases automatically. Other releases always must be tagged manually with tag_version().