Collect in-dev items under “development version” heading

[gadenbuie]

In between releases, it'd be great if update_news() could collect the draft news items under a specific heading. My personal preference would be to follow tidyverse conventions:

# <package> (development version)

One thing I like about the above heading, as opposed to using a .9000 version suffix, is that it allows the package maintainer some freedom if the package version changes without being officially released, while making it easier to automate maintenance of the NEWS file between official releases.

[krlmlr]

Thanks. I see particular use in tagging intermediate versions. fledge::bump_version() gives you a version number and a tag for free, and also updates the NEWS.md file. It's not an "official" version, rather a mini-milestone.

I also see value in supporting different workflows. We could watch out for a heading of this form, and recreate it if it was present before. Would you like to propose a PR?

[gadenbuie]

fledge::bump_version() gives you a version number and a tag for free, and also updates the NEWS.md file. It's not an "official" version, rather a mini-milestone.

I'm curious about your workflow in these cases. When you release a major milestone, do you re-write the NEWS to collapse these smaller milestones into the official release version?

A little background on the problem I'm wanting to solve: Rather than looking for the heading of this form and recreating it if present, I'm wanting an automated way to update the NEWS file without explicitly bumping, tagging or releasing. Here's how I see this working:

1. While merging the PR, I write the NEWS entry in the commit message (typically using a squash merge, but the merge commit type is flexible, for sure)
2. An action (or human) in the main branch calls update_news() and collects un-released NEWS items into a development version heading.
3. When I'm ready to bump the version, I call fledge::bump_version() and edit and organize the NEWS items.

[krlmlr]

Before sending to CRAN I rewrite NEWS.md, all headers that end with .90xx go away. (At some point fledge will also check for this.)

I think fledge does most of the workflow you are anticipating, it just assigns an explicit version number and a tag with the default which = "dev" . For which = "patch" or stronger, you are supposed to edit the NEWS.md file before finalizing. Would it help if bump_version("patch") checked for .90xx headings already?

[gadenbuie]

I'm realizing now that I'm advocating for an overall different treatment of the dev version. I personally tend to follow the advice on the Organization of NEWS items in the tidyverse style guide.

In particular, I don't think that it's worth distinguishing (in the NEWS, at least) between versions x.y.z.9000 and x.y.z.9001. I'd prefer to collect NEWS items for any dev-level version changes in a single (development version) heading, making it easier to automate keeping the dev version NEWS items up to date.

This approach would also allow fledge to completely re-write the dev version section, collecting everything since the last version tag in the dev heading. This would let users who do want to split their NEWS by dev version to opt into that be bumping and tagging, whereas those who want a unified dev section could skip the tagging part.

Here's a small example that demonstrates how fledge does do most of the anticipated workflow but it's not quite possible currently.

I'll setup a temporary package to work with, following the example in the Using fledge docs.

library(usethis)
library(gert)
#> Linking to libgit2 v1.2.0, ssh support: YES
#> Global config: /Users/garrick/.gitconfig
#> Default user: Garrick Aden-Buie <garrick@adenbuie.com>
library(fs)
library(fledge)

options(usethis.quiet = TRUE)

if (dir_exists("SuperFrob")) {
  dir_delete("SuperFrob")
}

# two helper functions to simplify the reprex below
git_commit_quietly <- function(files, message) {
  git_add(files)
  invisible(git_commit(message))
}

read_news <- function(path = "NEWS.md") {
  cat(brio::read_file(path))
}

pkg <- create_package("SuperFrob", rstudio = FALSE, open = FALSE)
setwd("SuperFrob")
proj_set()
use_news_md()
use_git()
git_commit_quietly(".", "Initial commit")

dir_tree()
#> .
#> ├── DESCRIPTION
#> ├── NAMESPACE
#> ├── NEWS.md
#> └── R

At this point we start off with a NEWS file that looks like this (so far so good).

read_news()
#> # SuperFrob 0.0.0.9000
#> 
#> * Added a `NEWS.md` file to track changes to the package.

Let's create a file and a commit with a fledge-styled message.

use_r("super")
brio::write_file("# frobnicate", "R/super.R")
git_commit_quietly("R/super.R", "- Add support for frobnication")

Now we update our NEWS and check the changes.

update_news()
#> → Scraping 2 commit messages.
#> ✓ Found 1 NEWS-worthy entries.
#> 
#> ── Updating NEWS ──
#> 
#> → Adding new entries to 'NEWS.md'.
git_commit_quietly("NEWS.md", "Commit NEWS changes")

read_news()
#> <!-- NEWS.md is maintained by https://cynkra.github.io/fledge, do not edit -->
#> 
#> - Add support for frobnication
#> 
#> 
#> # SuperFrob 0.0.0.9000
#> 
#> * Added a `NEWS.md` file to track changes to the package.

This looks more or less okay: the new NEWS item was added above the last heading. Let's add another file and commit, followed by a NEWS update.

use_test("super")
git_commit_quietly(".", "- Add tests for frobnication")
update_news()
#> → Scraping 3 commit messages.
#> ✓ Found 2 NEWS-worthy entries.
#> 
#> ── Updating NEWS ──
#> 
#> → Adding new entries to 'NEWS.md'.
git_commit_quietly("NEWS.md", "Commit NEWS changes")

Now update_news() adds everything again to the top of the NEWS file.

read_news()
#> <!-- NEWS.md is maintained by https://cynkra.github.io/fledge, do not edit -->
#> 
#> - Add tests for frobnication
#> - Add support for frobnication
#> 
#> 
#> - Add support for frobnication
#> 
#> 
#> # SuperFrob 0.0.0.9000
#> 
#> * Added a `NEWS.md` file to track changes to the package.

What I would have liked to have happen is for the dev version heading to have been rewritten entirely by fledge. (I'm okay with losing the hand-crafted message from usethis because that version wasn't tagged.)

After our first commit and update_news(), we'd have

<!-- NEWS.md is maintained by https://cynkra.github.io/fledge, do not edit -->

# SuperFrob (development version)

- Add support for frobnication

and again after our second commit, followed by an update_news(), we'd have

<!-- NEWS.md is maintained by https://cynkra.github.io/fledge, do not edit -->

# SuperFrob (development version)

- Add tests for frobnication
- Add support for frobnication

Then, when we're ready for a more public release, we would bump the version

bump_version("patch")
#> → Scraping 5 commit messages.
#> ✓ Found 2 NEWS-worthy entries.
#> 
#> ── Updating NEWS ──
#> 
#> → Adding new entries to 'NEWS.md'.
#> 
#> ── Update Version ──
#> 
#> ✓ Package version bumped to 0.0.1.
#> → Adding header to 'NEWS.md'.
#> → Committing changes.
#> ℹ Preparing package for release (CRAN or otherwise).
#> ! Convert the change log in 'NEWS.md' to release notes.
#> ! After CRAN release, call `fledge::tag_version()` and
#> `fledge::bump_version()` to re-enter development mode

where ideally the NEWS would now look like this

read_news()
#> <!-- NEWS.md is maintained by https://cynkra.github.io/fledge, do not edit -->
#> 
#> # SuperFrob 0.0.1
#> 
#> - Add tests for frobnication
#> - Add support for frobnication

(Currently it would again repeat both news bullets.)

Finally, we'd edit and organize the NEWS items into coherent release notes and then tag the version.

tag_version()
#> 
#> ── Tagging Version ──
#> 
#> → Creating tag v0.0.1 with tag message derived from 'NEWS.md'.

[krlmlr]

Thanks for your input. The 90xx versions make it easy for fledge to determine which commits/merges have been added to NEWS.md . With the workflow you suggest, what happens if I make a typo in a commit message?

I find these intermediate version tags quite useful. Would it help if we had automation to remove the intermediate 90xx headers from NEWS.md ?

[gadenbuie]

I think what I'm asking for is just that update_news() when

• called by itself rather than as part of bump_version()
• and when there hasn't been a version tag/change since the last time it was called

should write the news items to a # <package> (development version) heading that is completely rewritten each time. Currently update_news() doesn't handle this case well, but improving this behavior wouldn't change anything about the rest of the workflow.

Effectively, the change would be that when calling update_news()

1. Throw away the (development version) heading at the top of NEWS.md
2. Write the news items since the last version change.
   • If there's been a version change or a tag — i.e. we're in bump_version() — then write the news items under the # <package> x.y.z heading (as currently)
   • If there hasn't been a version change, then write the news items under # <package> (development version)

With the workflow you suggest, what happens if I make a typo in a commit message?

With this workflow, we'd do the editing at the same time as we do currently. Calling bump_version() rewrites the latest news items under the right heading and then we'd edit and commit at that time.

I find these intermediate version tags quite useful.

Totally, and if you tag those intermediate versions they be frozen in the NEWS.

Would it help if we had automation to remove the intermediate 90xx headers from NEWS.md ?

I think this would certainly be a useful feature! But it's kind of tangential to what I'm hoping for here.

[krlmlr]

This and many many other issues will be much easier with #331.

[maelle]

this is included in #588 (calling update_news() with no argument in any branch will update the changelog if there's a development version header)

[maelle]

regarding the bumping however this is not included yet, this would be a different issue I think so I opened #602.