Wings for Your R Packages
Streamlines the process of versioning R packages and updating NEWS. Numbers are cheap, why not use them?
The goal of fledge is to streamline the process of versioning R packages and updating NEWS. Numbers are cheap, why not use them?
Currently, this "works for me", use at your own risk.
Workflow for development
The fledge package assumes an R package that is version-controlled with Git in a dedicated repository. It will take care of updating
DESCRIPTION when you want to assign a new version to your package.
- In commit messages to
master, mark everything that should go to
NEWS.mdwith a bullet point (
*). This works for single commits, merge commits, or pull requests.
When you want to assign a version number to the current state of your R package, call
NEWS.mdas appropriate. When done, call
This has the following effects:
NEWS.mdis composed from bits in your most recent commit messages, no need to resolve merge conflicts in
- A new version number is assigned automatically (this is modeled after
- A tag matching the version number is assigned automatically, with the most recent NEWS included in the tag's message. When you push the tag:
@-mentioned in the NEWS will be notified
- links will be added to issues or pull requests referenced from NEWS entries
- the tag will be listed on GitHub in the "Releases", it's very easy to convert it to a proper release by copying the message that's already part of the tag
Workflow for releasing to CRAN
NEWS.md, convert the changelog to a higher-level description of features and bug fixes.
Make last-minute adjustments before releasing to CRAN.
When accepted, call
fledge::tag_version(force = TRUE) fledge::bump_version()
to tag the released version and to switch to a development version immediately.
Setting up fledge isn't much different from the regular development workflow:
Bump the package version with
NEWS.mdfile may grow large, especially if you haven't used tags in your repository before.
From here on, switch to the development workflow. Don't forget to use bullet points in your commit or merge messages to indicate NEWS-worthy changes!
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.) In those commits, the messages are parsed. Only lines that start with a star
* or a dash
- are included, and a line that starts with three dashes makes sure that everything past that line isn't included. 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 follwing components: - foo - bar - baz
will be added as:
- 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.
The main entry point is
bump_version(), which does the following:
NEWSentries from top-level commits
update_version(): bump version in
DESCRIPTION, add header to
- Depending on the release type:
NEWS.md, create tag with message
- other releases:
commit_version(): only commit
You can always edit
NEWS.md and call
finalize_version() again. Both the commit and the tag will be updated.
If you rebase after creating a tag, you need to call
finalize_version() to make sure the tag is moved to the mainline branch.
If you pushed after calling
finalize_version() (directly or indirectly), the tag may have been pushed as well. In this case, invoke
git push origin :vx.y.z.9www (where
x.y.z.9www is the new version) to delete the newly created remote tag. Because of this, only
"dev" releases are tagged automatically, other releases always must be tagged manually with
Install from GitHub via
Functions in fledge
|bump_version||Bump package version|
|commit_version||Commits NEWS.md and DESCRIPTION to Git|
|update_news||Update NEWS.md with messages from top-level commits|
|finalize_version||Finalize package version|
|update_version||Update NEWS.md and DESCRIPTION with a new version|
|tag_version||Create a new version tag|
|Roxygen||list(markdown = TRUE)|
Include our badge in your README