Clarify version number in wiki

[geneorama]

The major.minor.patch concept is clear, but what does the part after the dash indicate?

I believe it's one of these:

• major.minor.patch-commit
• major.minor.patch-buildnumber

It's to me what convention @tomschenkjr was using. I see some big numbers which would seem like commits, but I know that the CRAN submission process can be challenging and it could be actual builds.

Either way, I'd like to make a decision and clarify it in the wiki.

[geneorama]

I believe that it should be "build number", which would indicate the submission to CRAN.

For example, if when we submit version x.y.z, the full name is x.y.z-1 the first time. If that submission is rejected the next build should be x.y.z-2, no matter how many commits went into it.

[tomschenkjr]

Commits so you'd have a way (without relying on git log) you determine if two people are looking at the same code.

…

On Wed, Jun 26, 2019, 11:56 AM Gene Leynes ***@***.***> wrote: The major.minor.patch concept is clear, but what does the part after the dash indicate? I believe it's one of these: - major.minor.patch-commit - major.minor.patch-buildnumber It's to me what convention @tomschenkjr <https://github.com/tomschenkjr> was using. I see some big numbers which would seem like commits, but I know that the CRAN submission process can be challenging and it could be actual builds. Either way, I'd like to make a decision and clarify it in the wiki. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#180?email_source=notifications&email_token=AAMQFUK5LDPPV54BU4JV2HTP4ONS3A5CNFSM4H3UHU5KYY3PNVWWK3TUL52HS4DFUVEXG43VMWVGG33NNVSW45C7NFSM4G33RKLA>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AAMQFUL3MYJN72YLYA2TXPTP4ONS3ANCNFSM4H3UHU5A> .

[nicklucius]

@geneorama - Documentation for the build iteration process is here

[geneorama]

I didn't see any benefit to this, but one thing that @nicklucius mentioned makes sense: it would be very useful for determining which version is installed if you're looking at installed.packages()

A couple of things that I think would make the documentation better are clarifying the following:

1. What this component of the version is called. I would suggest something along the lines of commit number rather than build or buildNumber. Yes, each commit is rebuilt in Appveyor, but this number is designed to reflect the commit, not the fact that it was built.
2. Doesn't this affect how maintainers perform pull requests? I think this versioning would require a rebase merge, since a commit merge would create a new commit and throw off the version number.
3. How do we would handle the counting upon a merge? I'm assuming that if you merged two branches for one issue, then you would add up the commits from the base and target.
4. I'm assuming that the number resets after a successful submission to CRAN, or does it reset when there is a update to x/y/z parts of the version number, or when someone branches?

Also, in theory shouldn't every commit have a change to the DESCRIPTION file? It would be great to

A good example is the last submission to CRAN. We made several changes to the tests and examples and submitted it to CRAN. Then they rejected it because we had a bad URL in the README. When we fixed this should the patch number increment? What about the commitNumber, does that reset?

I really like the contributing document in principal, but I'm having a hard time resolving some of these issues, and it's always a problem when it's the last minute with a looming CRAN deadline.

Maybe we should be using git hooks to manage all of this.

[tomschenkjr]

I didn't see any benefit to this, but one thing that @nicklucius mentioned makes sense: it would be very useful for determining which version is installed if you're looking at installed.packages()

Yeah, that's a more succinct and better way of putting it. In RStudio, I've been able to catch that I had a prior build by just looking at the build number.

What this component of the version is called. I would suggest something along the lines of commit number rather than build or buildNumber.

That's fair. The original documentation on semantic versioning is called build, but I think you're right that it's really tied to the commit.

You enumerated a few questions on merge/pull requests and branching. I think it's been tough for contributors to remember to do that, even though we specify it in the CONTRIBUTING documentation. It's a small, easy thing to ignore. In the past, I've simply made the change for them or have occasionally asked them to do it.

A good example is the last submission to CRAN. We made several changes to the tests and examples and submitted it to CRAN. Then they rejected it because we had a bad URL in the README. When we fixed this should the patch number increment?

I think so. Behind this is the concept that it takes several commits to get to the final version of x.y.z. So, we just need to separate them to know which iteration of x.y.z we're looking at (e.g., x.y.z-1 or x.y.z-2).

Maybe we should be using git hooks to manage all of this.

I've thought about automating this a few ways, but always seemed to have some issues. I've researched and seen other packages that use a shell script that updates the DESCRIPTION file (but that requires remembering to run the shell script). Ultimately, my thinking was this didn't need to be a perfect exercise and missing it every so often is probably OK. Likewise, I appreciate the deliberation to look at the DESCRIPTION file and think about what version your change should be (e.g., did you make a minor change or just a bug fix?)

Nevertheless, always can have improvement in the future.

[geneorama]

@tomschenkjr in the current system, what is your thinking about when the number resets? Is that when there is a successful CRAN submission?

Appveyor apparently uses a build number concept, RSocrata is currently at 355 https://ci.appveyor.com/project/cityofchicago/rsocrata

I looked into the git hook idea a bit yesterday. Although you can make some things automatic, I wasn't sure how to add it to a project. The hooks are in .git/hooks/. Git comes with example hooks in that folder, but they're disabled.

No matter what, I agree that automation would not solve the "major minor patch" decision.

I see two inherent conflicts that are very fundamental.

First, the version is something that is ultimately decided after the the commit. Sometimes you might know which version you're working on, but you don't really know until it's merged. Putting the version number in the code is necessary for R packages, so this is just something to manage.

Second, there are two sources for what constitutes a version. First, there are the actual things that the code is doing. Second, there is a publication on CRAN.

I liked the way we did release candidates in the lead API where we were not on a new version until the new version was accepted. However, I don't think this works well with CRAN where you don't know when something will be accepted.

[tomschenkjr]

what is your thinking about when the number resets? Is that when there is a successful CRAN submission

After submission to CRAN. CRAN is just publishing one of the commits that we determine was the final version. GitHub contains each one of them. Once we release a version on CRAN, the next version should modify either major.minor.bug version and the commit resets at 1.

First, the version is something that is ultimately decided after the the commit. Sometimes you might know which version you're working on, but you don't really know until it's merged.

Remember that when we'd start new sprints that we'd often say "so this work will be version x.y.z". That was determined based on the work we'd expect to be done in the upcoming sprint. It was also our awareness to understand how dramatic changes would be. So, we would often decide the version number at the beginning of work.

Even semantic versioning recognizes that sometimes you have to make changes in their FAQ:

What do I do if I accidentally release a backwards incompatible change as a minor version?

As soon as you realize that you’ve broken the Semantic Versioning spec, fix the problem and release a new minor version that corrects the problem and restores backwards compatibility. Even under this circumstance, it is unacceptable to modify versioned releases. If it’s appropriate, document the offending version and inform your users of the problem so that they are aware of the offending version.

But, perhaps it's valuable to draft changes to the "Making Changes" section of CONTRIBUTING

Second, there are two sources for what constitutes a version. First, there are the actual things that the code is doing. Second, there is a publication on CRAN.

CRAN is just publishing one commit that we decide is the final version of a new version. Sometimes it's easy so we are done after x.y.z-1, usually it takes several commits so we're not done until x.y.z-20.

[geneorama]

Going though the submission process changed my perspective slightly on this.

I would like to suggest that the -n part advances with each submission to CRAN rather with each commit. There can be cases where the same "version" is submitted to CRAN with slight changes to the submission (like if someone builds locally rather than using Travis CI). I think the version number makes sense to track here, but I still don't see how to properly track the -n part with the dev/master/build steps otherwise.

[tomschenkjr]

I would like to suggest that the -n part advances with each submission to CRAN rather with each commit.

This makes a lot of sense.