Topics

Proposing a change to the repository location of release notes

Bob Jacobsen
 

Currently, draft and final JMRI release notes live in the JMRI/website repository, i.e. at

https://github.com/JMRI/website/blob/master/releasenotes/jmri4.15.2.shtml

I propose to move the next 4.15.3 draft, and all further ones, to a new directory in the main JMRI/JMRI repo at

https://github.com/JMRI/JMRI/blob/master/help/en/releasenotes/jmri4.15.3.shtml

The goal is to make it easier, and hence more likely, for people to add a few lines to the note when the make a change or create a PR.

We’ve discussed this before, and concerns were raised about:

1) There are likely to be lots of merge conflicts.
2) If somebody creates a PR aimed for release N, and it ends up delayed into N+1, the note’ll be in the wrong place.
3) Having release notes in the part of the tee that’s shipped with JMRI will make it bigger.

I think a little perspective is in order. Across the entire set releases in JMRI 4.13 sequence, only seven people made commits to the release notes. _None_ of the commits to the “changes” section would have conflicted within an individual release, even if _all_ of those changes had been made in parallel. We do have some PRs that hang out for over a month; there’d be more if counting the time before they got pushed. But it’s not that hard to move a comment from one release note file to another file if they’re _right_ _there_. And none of the JMRI 4.13.* release notes were over 20kB, i.e. less than 0.0001 of the install size.

If there are other concerns about this, I’d like to address them if possible over the next week.

Past discussions have also gone sideways over ideas to change the form (i.e. away from hand-edited HTML) and location (i.e. away from a dedicated web page) of the release notes. That would be great. If people want to discuss that, please start a new thread. This one is about a smaller, quicker change that hopefully get more info into the release notes next month.

Bob

--
Bob Jacobsen
@BobJacobsen

db123@bergqvist.se
 

It seems good to me.

Personally I feel a bit scared of changing the release notes. For me, it's a kind of official document that maybe only the maintainers should update. So maybe it would be good to add a note about it on the http://jmri.org/help/en/html/doc/Technical/ page that everyone is welcome to update it and a note about when it's recommended to do it.

Daniel

2019-01-06 20:58 skrev Bob Jacobsen:

Currently, draft and final JMRI release notes live in the JMRI/website
repository, i.e. at
https://github.com/JMRI/website/blob/master/releasenotes/jmri4.15.2.shtml
I propose to move the next 4.15.3 draft, and all further ones, to a
new directory in the main JMRI/JMRI repo at
https://github.com/JMRI/JMRI/blob/master/help/en/releasenotes/jmri4.15.3.shtml
The goal is to make it easier, and hence more likely, for people to
add a few lines to the note when the make a change or create a PR.
We’ve discussed this before, and concerns were raised about:
1) There are likely to be lots of merge conflicts.
2) If somebody creates a PR aimed for release N, and it ends up
delayed into N+1, the note’ll be in the wrong place.
3) Having release notes in the part of the tee that’s shipped with
JMRI will make it bigger.
I think a little perspective is in order. Across the entire set
releases in JMRI 4.13 sequence, only seven people made commits to the
release notes. _None_ of the commits to the “changes” section would
have conflicted within an individual release, even if _all_ of those
changes had been made in parallel. We do have some PRs that hang out
for over a month; there’d be more if counting the time before they got
pushed. But it’s not that hard to move a comment from one release
note file to another file if they’re _right_ _there_. And none of the
JMRI 4.13.* release notes were over 20kB, i.e. less than 0.0001 of the
install size.
If there are other concerns about this, I’d like to address them if
possible over the next week.
Past discussions have also gone sideways over ideas to change the form
(i.e. away from hand-edited HTML) and location (i.e. away from a
dedicated web page) of the release notes. That would be great. If
people want to discuss that, please start a new thread. This one is
about a smaller, quicker change that hopefully get more info into the
release notes next month.
Bob
--
Bob Jacobsen
@BobJacobsen

Alain LM
 

On Sun, Jan 6, 2019 at 08:58 PM, Bob Jacobsen wrote:
Across the entire set releases in JMRI 4.13 sequence, only seven people made commits to the release notes.
I'll be happy to prepare the lines for the release note in parallel to any change that I introduce, once the PR is accepted and assigned to a release.

There has been not so clear instructions after the move to Github to not commit changes in the release note, that instead would be updated directly in the repo by the very few who have write access to it. I therefore refrained from proposing updates to the release note since then.
 
--
Alain LM

Bob Jacobsen
 

Thanks for the comment on this. They made it better.

The proposed changes are in two PRs:
https://github.com/JMRI/JMRI/pull/6440
https://github.com/JMRI/website/pull/304

You can see the updated help page that talks about adding to the release note via the diffs: https://github.com/JMRI/JMRI/pull/6440/files#diff-70612d62e169facc8749c70659c90383

Comments welcome!

Bob
--
Bob Jacobsen
@BobJacobsen