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” 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
NEWS.mdfor you based on informative commit messages,
DESCRIPTION(e.g. useful in bug reports with session information!),
Using fledge is a discipline / a few habits that is worth learning!
What you need to do in practice is:
*at the beginning of important commit messages e.g. the merge or squash commits that merge a Pull Request. These are the commit messages that’ll be recorded in the changelog eventually! Exclude housekeeping parts of the message by typing them after a line
- 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.
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 run
fledge::unbump_version(), merge the PR with an informative squash commit message, then run
fledge::bump_version() and go drink that coffee!
fledge::finalize_version() if you add to edit
NEWS.md manually e.g. if you made a typo or are not happy with a phrasing after thinking about it. 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).
These habits are worth learning!
Install from cynkra’s R-universe using:
install.packages("fledge", repos = "https://cynkra.r-universe.dev")
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.
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
If your package…
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.
Check out the general vignette
vignette("fledge"), and for the whole game, the demo vignette
vignette("demo"). Feel free to ask us questions!