Topics

On release labels


Bob Jacobsen
 

As we work toward a new release system, there seems to be some confusion about version naming.

Version naming appears in several cases:

1) From the Version class (i.e. ./runtest.csh jmri.Version or on the front window of PanelPro) i.e 4.18+R37ad3d0
2) On file names for distribution: So far, these have been made by prepending 'JMRI.' to the Version output, i.e. JMRI.4.18+R37ad3d0.dmg

And there are several different kinds of things named.

a) A local build on my machine, currently 4.22.3ish+jake+20200704T1718Z+R2e94d367f5 - the “4.22.3ish” refers to the _next_ release expected from the master branch, i.e. “ish” means “almost, but not yet"

b) That same local build as a Jenkins dev build: 4.22.3ish+jenkins+20200704T1616Z+R2e94d367f5- i.e. filename JMRI.4.22.3ish+jenkins+20200704T1616Z+R2e94d367f5.dmg

c) If that was build as a test release: 4.22.3+R2e94d367f5 - i.e. filename JMRI.4.22.3+R2e94d367f5.dmg

Having the SHA there is useful because it allows recreation of the exact content later on (helpful for the “ish” builds in A&B, not really necessary for C as we do other bookkeeping on that). The time (20200704T1616Z) is helpful for sorting out earlier and later, as the SHA doesn’t do that by inspection.

What should be do in the new system?

A) For development work, there is no always-reliable equivalent of our current 4.22.3ish because we don’t (always) progress to that _next_ version: Branches can be crossed without a release, for example after `dev-update` is released `dev-update` is merged to “dev-minor” and a new head of `dev-update` is created.

B) For development work, is the most important thing the adjacent release number, or which branch is being built on? I.e. instead of 4.22.3ish+jake how about dev-update+jake? That makes it cleared whether this is development of a major, minor or update line of code. But most of the time, the actual source of the work will be the current head of `master`: Until the change is made, it’s not clear where it will end up.

I think the answer should be:

C) Start with the most recent release from the code, and say it’s a forward motion from there: say i.e. “4.22.2 plus stuff”, perhaps 4.22.2-base or 4.22.2-updated for example (there should be a “-“ there under semantic versioning standards; omitting that with ‘ish’ should not be repeated). With this, the three types would be 4.22.2-updated+jake+20200704T1718Z+R2e94d367f5 (note the 4.22.2 instead of 4.23.3), 4.22.2-updated+jenkins+20200704T1616Z+R2e94d367f5 and 4.22.3+R2e94d367f5 (unchanged).

"most recent release from the code” has a convenient operational definition: The one that’s on the currently-used branch in the release.properties file. If you’re developing something from `master`, it’ll be the last published release. If you’re working on `dev-major` or `dev-minor`, that is likely to be different (`dev-update` is released more often), but it’s still a clear and reproducible starting point.

Aside from reformatting “ish” to “-something”, the only change (C) requires is a change to when release.properties is updated during the release process. Now it’s release-then-increment. It would become increment-then-release. But we need that anyway because of how changes can be released as update, minor or major depending on decisions later on.

Would it be OK to adopt (C)? Is there a reason I’ve overlooked to prefer (A) or (B)? Or is there a (D) that’s still better? (If you propose one, please give the full examples and how JMRI will know to build it)

Bob

Bob Jacobsen
@BobJacobsen


danielb987
 

2020-07-04 20:27 skrev Bob Jacobsen:
Would it be OK to adopt (C)?
I think so. But I don't know enough of the release process to be sure.

Daniel


Randall Wood <rhwood@...>
 

I’m a little scared of C and worry that it will result in users acting as if the “-update” is a published thing. I’d prefer to note in our process and versioning docs that a release we are building towards may, in fact, not be released.

I don’t know that I would prefer A.B.(C+1)-SNAPSHOT+... following the release of A.B.C or that the branch name be in a release.

If the branches were named for their target release (i.e. a branch is vA.B.C until A.B.C is tagged and released and then vA.B.(C+1) is branches off it and branch vA.B.C is terminated, we may be able to make the build tooling use the branch to get the release versions and not have to worry about release numbers in version.properties except on master.

Randall

On Jul 4, 2020, at 19:24, danielb987 <db123@...> wrote:

2020-07-04 20:27 skrev Bob Jacobsen:
Would it be OK to adopt (C)?
I think so. But I don't know enough of the release process to be sure.

Daniel


Bob Jacobsen
 

(C) never shows a release number that hasn’t already been released, unlike our current approach. So that helps with the concern "that a release we are building towards may, in fact, not be released”.

I would prefer _not_ to use branch names to generate the version number, as it’s not clear how to do that reliably during development with lots of branches (I’ve currently got 6 active ones, for example; I can’t give them all the same name!); since the proposed development process doesn’t (and can’t) produce a linear Git graph, it’s not even unambiguous which is the parent tag.

Something that can be read as “this specific version, hence tag, plus changes” also seems more robust to me that just an indication of coming from a branch. The branch name, even if it’s a conventional one, doesn’t define a well-known point on that branch. Yes, if you know the SHA, you can find the parentage (though not necessarily the branch), but you can do that without having the name.

SNAPSHOT has the same meaning as our “ish” notation: It denotes “not quite to the next release”. From the Maven docs:

A snapshot version in Maven is one that has not been released. The idea is that before a 1.0 release (or any other release) is done, there exists a 1.0-SNAPSHOT. ... That means that downloading 1.0-SNAPSHOT today might give a different file than downloading it yesterday or tomorrow.
As to the proposal for branches called vA.B.C: I don’t see we can make that work. I expect we’ll have enough trouble with three branches with constant names. But I certainly could be wrong about this, so I’d certainly be interested in seeing a writeup of how it would work,. (That’s why I haven’t merged the one in https://github.com/bobjacobsen/JMRI/blob/release-update-doc/help/en/html/doc/Technical/ReleaseProcess.md ; there might be a better solution!)

Bob

On Jul 4, 2020, at 7:42 PM, Randall Wood via groups.io <rhwood=mac.com@groups.io> wrote:

I’m a little scared of C and worry that it will result in users acting as if the “-update” is a published thing. I’d prefer to note in our process and versioning docs that a release we are building towards may, in fact, not be released.

I don’t know that I would prefer A.B.(C+1)-SNAPSHOT+... following the release of A.B.C or that the branch name be in a release.

If the branches were named for their target release (i.e. a branch is vA.B.C until A.B.C is tagged and released and then vA.B.(C+1) is branches off it and branch vA.B.C is terminated, we may be able to make the build tooling use the branch to get the release versions and not have to worry about release numbers in version.properties except on master.

Randall
On Jul 4, 2020, at 19:24, danielb987 <db123@...> wrote:

2020-07-04 20:27 skrev Bob Jacobsen:
Would it be OK to adopt (C)?
I think so. But I don't know enough of the release process to be sure.

Daniel



Bob Jacobsen
@BobJacobsen


Randall Wood <rhwood@...>
 



On 05-Jul-2020, at 02:49, Bob Jacobsen <rgj1927@...> wrote:

(C) never shows a release number that hasn’t already been released, unlike our current approach.  So that helps with the concern "that a release we are building towards may, in fact, not be released”.

"that a release we are building towards may, in fact, not be released” is not a concern I have; it’s almost the opposite of my concern.

My concern is that currently users are reporting bugs in the user’s group against “ish” releases and dropping the “ish" in the version number they use, so I would rather have the Jenkins builds use an unreleased version number, instead of having them report a bug present in a released version “+changes” (while silently dropping the “+changes" on us when reporting).

I would prefer _not_ to use branch names to generate the version number, as it’s not clear how to do that reliably during development with lots of branches (I’ve currently got 6 active ones, for example; I can’t give them all the same name!); since the proposed development process doesn’t (and can’t) produce a linear Git graph, it’s not even unambiguous which is the parent tag.

I’m not proposing *you* use versions in branch names, but that github.com/JMRI/JMRI use versions in branch names, so when you open a PR, you are opening a PR against “vA.B.C" (e.g. I would push my branch “fix-foo” against JMRI’s branch “v5.6.7”). 

Something that can be read as “this specific version, hence tag, plus changes” also seems more robust to me that just an indication of coming from a branch. The branch name, even if it’s a conventional one, doesn’t define a well-known point on that branch. Yes, if you know the SHA, you can find the parentage (though not necessarily the branch), but you can do that without having the name.

I am worried that “version+changes” will be treated as “version” by users and we will be unable to reproduce bugs in “version” that a user has reported because the user is dropping the “+changes” in his report.

SNAPSHOT has the same meaning as our “ish” notation:  It denotes “not quite to the next release”. From the Maven docs:

A snapshot version in Maven is one that has not been released. The idea is that before a 1.0 release (or any other release) is done, there exists a 1.0-SNAPSHOT. ... That means that downloading 1.0-SNAPSHOT today might give a different file than downloading it yesterday or tomorrow.

I’m aware, but think whatever term we use needs to be in ALL CAPS to draw attention to it (I picked on SNAPSHOT because of its conventional use in maven.)

As to the proposal for branches called vA.B.C:  I don’t see we can make that work.  I expect we’ll have enough trouble with three branches with constant names.  But I certainly could be wrong about this, so I’d certainly be interested in seeing a writeup of how it would work,.  (That’s why I haven’t merged the one in  https://github.com/bobjacobsen/JMRI/blob/release-update-doc/help/en/html/doc/Technical/ReleaseProcess.md ; there might be a better solution!)

I’ll see what I can do; it’ll take a couple of evening though.

Bob

On Jul 4, 2020, at 7:42 PM, Randall Wood via groups.io <rhwood@...> wrote:

I’m a little scared of C and worry that it will result in users acting as if the “-update” is a published thing. I’d prefer to note in our process and versioning docs that a release we are building towards may, in fact, not be released.

I don’t know that I would prefer A.B.(C+1)-SNAPSHOT+... following the release of A.B.C or that the branch name be in a release.

If the branches were named for their target release (i.e. a branch is vA.B.C until A.B.C is tagged and released and then vA.B.(C+1) is branches off it and branch vA.B.C is terminated, we may be able to make the build tooling use the branch to get the release versions and not have to worry about release numbers in version.properties except on master.

Randall
On Jul 4, 2020, at 19:24, danielb987 <db123@...> wrote:

2020-07-04 20:27 skrev Bob Jacobsen:
Would it be OK to adopt (C)?

I think so. But I don't know enough of the release process to be sure.

Daniel







Bob Jacobsen
rgj1927@...







danielb987
 

2020-07-05 13:57 skrev Randall Wood via groups.io:
I’m not proposing *you* use versions in branch names, but that
github.com/JMRI/JMRI [2] use versions in branch names, so when you
open a PR, you are opening a PR against “vA.B.C" (e.g. I would push
my branch “fix-foo” against JMRI’s branch “v5.6.7”).
Are you suggesting that we as developers should work against different branches, like v5.6.7, instead of working on branches based on master? The latest time we tried that, it didn't worked well. Partly because many tools defaults to master. I use GitHub Desktop, and while it's possible to create a branch of whatever other branch, GitHub Desktop warns about not have master as the base of a different branch than master. And if you don't watch up, it's easy to get a new branch based on master even if the intention was to base it on another branch.

Daniel


Randall Wood <rhwood@...>
 

On 05-Jul-2020, at 09:15, danielb987 <db123@...> wrote:

2020-07-05 13:57 skrev Randall Wood via groups.io:
I’m not proposing *you* use versions in branch names, but that
github.com/JMRI/JMRI [2] use versions in branch names, so when you
open a PR, you are opening a PR against “vA.B.C" (e.g. I would push
my branch “fix-foo” against JMRI’s branch “v5.6.7”).
Are you suggesting that we as developers should work against different branches, like v5.6.7, instead of working on branches based on master? The latest time we tried that, it didn't worked well. Partly because many tools defaults to master. I use GitHub Desktop, and while it's possible to create a branch of whatever other branch, GitHub Desktop warns about not have master as the base of a different branch than master. And if you don't watch up, it's easy to get a new branch based on master even if the intention was to base it on another branch.
If you are making a fix against 5.6.7 while master is at 6.0.0 with incompatible changes (like a dependency on a newer Java version), you can’t work off master without destroying the point of maintaining the branch containing 5.6.7, so yes, there are circumstances where I am expecting you as a developer may need to exercise caution and start work off the correct branch.

Daniel



danielb987
 

2020-07-05 15:23 skrev Randall Wood via groups.io:
On 05-Jul-2020, at 09:15, danielb987 <db123@...> wrote:
2020-07-05 13:57 skrev Randall Wood via groups.io:
I’m not proposing *you* use versions in branch names, but that
github.com/JMRI/JMRI [2] use versions in branch names, so when you
open a PR, you are opening a PR against “vA.B.C" (e.g. I would push
my branch “fix-foo” against JMRI’s branch “v5.6.7”).
Are you suggesting that we as developers should work against different branches, like v5.6.7, instead of working on branches based on master? The latest time we tried that, it didn't worked well. Partly because many tools defaults to master. I use GitHub Desktop, and while it's possible to create a branch of whatever other branch, GitHub Desktop warns about not have master as the base of a different branch than master. And if you don't watch up, it's easy to get a new branch based on master even if the intention was to base it on another branch.
If you are making a fix against 5.6.7 while master is at 6.0.0 with
incompatible changes (like a dependency on a newer Java version), you
can’t work off master without destroying the point of maintaining the
branch containing 5.6.7, so yes, there are circumstances where I am
expecting you as a developer may need to exercise caution and start
work off the correct branch.
OK. I agree with you.

Daniel


Ken Cameron
 

Randall,

I see the issue of what they say they have not being quite accurate enough.
But if we form the habit of always getting the console log, we can read
whatever version it was from there. But this would be improved if we ever
figure out how to make the upload debug work again. It has the logs with the
real identity so we have no question of the version being reported.

Any time the user is trying recreate the version id from what they felt like
typing will have your point of likely losing important detail.

-Ken Cameron, Member JMRI Dev Team
www.jmri.org
www.fingerlakeslivesteamers.org
www.cnymod.org
www.syracusemodelrr.org