Smoother change tracking and versioning for R packages.
Do you want to provide a changelog (NEWS.md) more informative than “bug fixes and performance improvements” (https://twitter.com/EmilyKager/status/1413628436984188933
) to the users of your package?
Ways to achieve that are:
Update NEWS.md right before release by reading through commit messages. Not necessarily fun!
Update the changelog in every commit e.g. in every PR. Now, if there are several feature PRs around that update the changelog, you’ll have a few clicks to make to tackle conflicts. Easy enough, but potentially annoying.
-
Use fledge to
- fill the
NEWS.md
for you based on informative commit messages, - (optionally) increase the version number in
DESCRIPTION
(e.g. useful in bug reports with session information!), - (optionally) create git tags (more coarse-grained history compared to top-level merges see fledge tag list on GitHub).
- fill the
Using fledge is a discipline, a few habits, that are worth learning!
What you need to do in practice is, no matter your fledge commitment level:
-
For important commit messages you want recorded in the changelog, you can
Use the conventional commits syntax. For instance
feat: Enhanced support for time series
. Only using conventional commits syntax will provide automatic grouping of changelog items into groups (Documentation, Bug Fixes, etc.).Add a hyphen
-
or*
at the beginning of the commit message. Exclude housekeeping parts of the message by typing them after a line---
.
- Add support for bla databases.
or
- Add support for bla databases. --- Also tweak the CI workflow accordingly. :sweat_smile:
Use informative merge commit messages as those will also be included by default in the changelog. On GitHub you can control the default commit message when merging a pull request.
(GitHub repositories only) For merge commits with the default not self-contained message (“Merge pull request…”), rely on fledge’s querying GitHub API to get the PR title and include it in the changelog.
For informative commit messages refer to the Tidyverse style guide.
Then, for full fledge use = fledge-assisted management of NEWS.md, DESCRIPTION version numbers, and git tags:
Run
fledge::bump_version()
regularly e.g. before every coffee break or at the end of the day or of the week. If you forgot to merge one PR runfledge::unbump_version()
, merge the PR with an informative squash commit message, then runfledge::bump_version()
and go drink that coffee!Run
fledge::finalize_version()
if you need to editNEWS.md
manually e.g. if you made a typo or are not happy with a phrasing in retrospect. Even if you edit a lot, what’s been written in by fledge is still a good place-holder.Follow the recommended steps at release (see
vignette("fledge")
usage section).
OR, for light fledge use = filling of NEWS.md between releases:
- Have a development version header as produced by
usethis::use_development_version()
.
# mypackage (development version)
- Regularly run
fledge::update_news()
, preferentially on the main branch to avoid merge conflicts.
These habits are worth learning!
Installation & setup
Once per machine
Install from CRAN using:
install.packages("fledge")
Install from cynkra’s R-universe (development version) using:
install.packages("fledge", repos = c("https://cynkra.r-universe.dev", "https://cloud.r-project.org"))
Or install from GitHub (development version as well) using:
remotes::install_github("cynkra/fledge")
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
Your package needs to have a remote that indicates the default branch (e.g. GitHub remote) or to be using the same default branch name as your global/project
init.defaultbranch
.Add a mention of fledge usage in your contributing guide, as contributors might not know about it. A comment is added to the top of
NEWS.md
, but it tends to be ignored occasionally.
For full use
-
If your package…
- is brand-new, remember to run
fledge::bump_version()
regularly. - has already undergone some development, it is not too late to jump on the train! Run
fledge::bump_version()
and thenfledge::finalize_version()
.
- is brand-new, remember to run
How to get started?
Check out the general vignette vignette("fledge")
, and for the whole game, the demo vignette vignette("demo")
. Feel free to ask us questions!
Related tools
-
newsmd: manually add updates (version or bullet points) to the
NEWS.md
file. - autonewsmd: Auto-Generate Changelog using Conventional Commits.