Periodically bump version, perform GitHub release, maintain news/changelog

[brookslogan]

Raised by @dshemetov a while back: we should periodically bump the package version and perform a GitHub release. Maintaining a news/changelog file would also be helpful. Version numbers help with lifecycle deprecation messaging. We should think about how backwards-compatible we want to be, and how much we want to catch with deprecation messages.

[dshemetov]

I suggest a simple and common approach to version numbering (h/t @krivard): A.B.C, where A increments for large backwards-incompatible versions, B increments for large feature additions (backwards compatible), C increments for minor changes/fixes.

[krivard]

Credit: https://semver.org/

[brookslogan]

We're "at" version 1.0.0 for a while already but are still cleaning up some interface issues. With current pull-into-main + semver we will reach ridiculous version numbers quickly. It feels like we are more in < 1.0.0 by semver standards, so I'm thinking of doing something a little semver-incompatible until we stabilize more --- maybe just call the current version 0.x.y.z or 1.x.y.z with x.y.z semver-like (I think this might be sort of like 1.0.0-alpha-x.y.z, but in an R numeric_version-compatible way). When we switch to semver proper we should consider moving to pull-into-dev, at least for breaking changes.

[dshemetov]

What do you think about not making major version numbers be sacred?

TL;DR: Just let the version number get really large. One negative consequence I can think of is that it will give a false impression of package maturity to some people. Doesn't seem like a big issue though (personally, if I see package-42.1.2 out in the wild, the bigger number doesn't give me much more confidence).

[brookslogan]

Regarding the non-sacred major version numbers:

• The authors DO support epochal version labels.
• Skimming, I didn't see any real head-to-head comparison of integrating vs. not integrating the epoch label into the version number. They do mention it increases "visual complexity" (and would require an update to semver spec if it were made part of the spec). But we might also argue that integrating clearly shows what epoch something is in without having to search for a page explaining which major versions belong to which epochs.
• Wacky animal names / national forest names vs. epoch numbers: perhaps wacky names are easier to "market" (but not explanatory at all); only numbers could be integrated into R version tags, and require less creative thinking.

Random points:

• The version was marked as 1.0.0 months ago and we haven't changed it since. Current development is on main.
• Up until now, and for probably the next month, we're developing more like we're at version 0, or within an alpha phase. (But we can't include "alpha" in R version tags that I know of (and hyphens are converted into dots).)
• I don't want to retroactively apply semver with versions >=1 to our still-experimental 1.0.0 phase, but at least a couple retroactive version numbers could be useful.
• For the next month, I don't want to apply semver with versions >=1. Potentially, we could introduce a dev branch and then just do a v2 [or v3] release at the end of the month.

Potential routes forward:

• 1.x.y.z
• 0.x.y.z
• [0.w.r]
• [x.y.z] Decide on which of the many 1.0.0 commits should be the 1.0.0 release, maybe also a 2.0.0 release, switch development to a dev branch, switch epipredict to be checking against the dev branch of epiprocess during this experimental phase and then switch it back to checking against the main and manually bump the dependency. Maybe think a bit more about what to point external people to when soliciting feedback (really, sort of a beta phase, but again, R version numbers don't accommodate this). [I guess some of these steps aren't actually mandatory; maybe we could still be doing development on main and having main point to (at different points in time) different things with the same version number, and considering releases to be the act of attaching a separate git branch/tag / whatever GitHub releases do, rather than committing on main with the contents indicating a particular version number, which we've already messed up. And some of the steps would also apply to the other things above.]

[The differences between the above have shrunk and continue to shrink the more we've stayed in experimental 1.0.0 without doing version bumps. But we do have some PRs now where we want to be able to refer back to an old version in case it breaks epipredict things, although we could just do this by pointing to a particular commit.]

[dshemetov]

I'm really just in favor of simple solutions. The reason I prefer sticking with the original SemVer is because adding epochal version numbers is

• treading new ground in terms of the convention
• makes us non-compliant with their spec
• makes it more likely that we have further issues that haven't been explored in this "SemVer+"
• sets us up for having to make rules for what decides an epoch

I feel like you haven't really addressed my suggestion of just bumping the version numbers up and letting them get large. The benefits are:

• we stay in SemVer and avoid the issues above
• you can start doing it now, without issue, on the PRs you have now

But if you really don't want to have large version numbers, we could also delete the 1.0.0 release, since that was just a test and I don't think any one is using it. And revert back to 0.z.w to get us back to alpha. Maybe that's what you're suggesting in your route 3. I think that would also be fine.

[dshemetov]

Also, it seems to me that the test release of epipredict is actually 0.0.1, so I'm confused what the 1.0.0 discussion is about?

[dshemetov]

Rereading your comments about eventually getting back to SemVer, I think that's a good eventual goal.

So maybe if you want to have something like: 0.x.y.z as a way to mark alpha for now and then when you have a first stable public release do 1.x.y, that sounds fine to me.

But again, I think this is all a workaround us really wanting to have 1.0.0 mean something. With 0.x.y.z, you'll still need to increment x every time an interface changes, so you're not removing that work. And, of course, it's fine if we want 1.0.0 to mean something for marketing, I just want us to recognize that that's why we're doing this.

[dshemetov]

Ok, final thought: a time-saving approach would be to just stay in 0.x.y for now, not update 0 when the interface changes (because likely the interface changes in every update this early in the package). Just update x regularly to have distinct versions you can refer to and then when we finally decide we're at 1.0.0, release that, have it be marketing-meaningful, and THEN start tracking interface changes.

[brookslogan]

Clarifications/notes:

• 1.0.0 discussion is about epiprocess.
• Current "meaning" of 1.0.0, was, as I understood it, that core functionality more or less worked, not that it was stable.
• Moving to semver >=1 mentality also influences development being on main vs. on a dev branch.
• epipredict discussion is about what to do in epipredict when certain pending breaking changes are made in epiprocess or if epiprocess changes to development on a dev branch.

Why not just have huge version numbers?

• It undermines any impression of commitment to trying to maintain backwards compatibility that we try to make in the future, because the user already sees we made 20 versions and may not be aware of any shift in mentality.
• We have been developing like we are at version 0.*.*, or 1.0.0-alpha, not 1.0.0. In a month we'll be somewhere like 1.0.0-beta.

Why consider epochs at this point?

• We still plan to go through a beta-like phase; maybe multiple / a beta-like and an rc-like phase. An epoch might be one R-version-number-compatible way to indicate in the version tag itself when the/each beta phase is over; if we present back at some group, we can say this is something like version 4.. rather than 26.. (maybe harder to remember) or "Daring Dragon" (can't include in version tag) or 1.0.0-rc (can't do with R version numbers) or 1.0.0-26 (R can sort of do this, but may render it as (1.0.0.26, which is not, as far as I can tell, strictly semver-compatible, although maybe it's closer than epochs unless semver spec changes to add epochs).

If we decide to move to use epochs, it should be done fairly early on, so we don't start with a epoch number that's too high to look like an epoch number. If we decide to move away from epochs, this can probably be done at any time without too much strangeness.

Ok, final thought: a time-saving approach would be to just stay in 0.x.y for now, not update 0 when the interface changes (because likely the interface changes in every update this early in the package). Just update x regularly to have distinct versions you can refer to and then when we finally decide we're at 1.0.0, release that, have it be marketing-meaningful, and THEN start tracking interface changes.

Sounds solid; previously, I was reluctant to do this since we already had 1.0.0 in the DESCRIPTION on main. But let's just call labeling in the DESCRIPTION file not a release. I'm not sure whether or not this will cause issues for people developing on epipredict who need to update epiprocess for testing; perhaps that can be saved by developing off of a 1.0.0 dev branch or some manual reinstall. (I suppose if we want more flexibility, then, instead of epochs, we could do use dev branch development or pre-releases instead (and live with any hyphen-to-dot conversion, and hope that a new semver doesn't introduce epochs and distinguish between epoch vs. numeric pre-release by looking at dots vs. hyphens) [R version ordering is not numeric pre-release compatible; it considers pre-releases as "after" regular releases].)

[dshemetov]

Thanks for the clarifications Logan. And point taken on large version numbers sending a bad message about backwards compatibility.

Agree that DESCRIPTION file labeling isn't enough to constitute a release (it's not attached to hosting, for one). Personally vote for 0.x.y for now, just to stay compatible with SemVer, and adopting their initial development spec.

Also vote in favor of developing on a dev branch. That way main can always point to the latest stable release and dev can have the latest unstable work.

[dshemetov]

Made releases for the past few versions. Next steps:

• rename current main to dev (so PRs automatically follow the right branch)
• make a new main (we will merge here when we're ready to make a release)
• recommend installations pin their epiprocess versions to a GitHub release
• update generic installation instructions to pak::pkg_install("cmu-delphi/epiprocess@main")

[dshemetov]

closed by #398 and related changes