RACK v5.0 ontology changelog

[Robert-Adelard]

Why do the RACK ontology changes for v5.0 merit their own Wiki page?

https://github.com/ge-high-assurance/RACK/wiki/RACK-v5.0-Ontology-Changelog

Should this page be merged with the RACK ontology detailed changelogs?

https://github.com/ge-high-assurance/RACK/wiki/RACK-ontology-detailed-changelogs

Is the v5.0 changelog still relevant for v6.0 and/or should there be a separate v6.0 changelog page?

[Ptival]

The 5.0 changelog was manually compiled, which was a lot of work.

The detailed changelog is semi-automated, with a script that detects changes made to the ontology and asks a maintainer (me) to provide a machine representation of the changes, so as to generate the logs and help in building migration tooling.

The latter make the former somewhat redundant, though the 5.0 changelog contains human text describing the intent behind some of the changes that is not compiled in the detailed changelog.

@tuxji

• Do you think we should remove the 5.0 changelog?
• Should I add some notes to the data I gather for making the detailed changelog, so that we keep some of those human-readable descriptions of the intent behind the changes?

[tuxji]

Hi @Ptival my thoughts are:

1) I suggest an alternative approach that would make it unnecessary to add notes to your changelog data. Your script already prints commit ids with hyperlinks to the pull requests that merged these commits. When I click on these links, I see most of these pull request have one line messages describing the intent behind the changes. Your script could use the GitHub API to retrieve these pull request messages and print the first line of human text above or below the commit ids. Even after the fact, we might be able to edit these pull request messages if a PR doesn't have a message or the message's first line isn't clear enough.

2) If we can show the first line of each commit's PR message as human text in the detailed changelog, then we'll probably make the 5.0 changelog completely redundant and be able to remove it.

[Ptival]

@tuxji I actually quite like your suggestion, I will give it a try! :-)

[GregIthaca]

I did think that the manually-written 5.0 changelog did a lot to capture the design intent for these rather significant structural changes, and so provides useful information to anyone who is still navigating that transition. However, at this point in time, many people may not be looking back as far as the 4.0->5.0 change, so it might not be important to retain it.

[Ptival]

I gave a try to this change, which you can see here:

https://github.com/ge-high-assurance/RACK/wiki/RACK-ontology-detailed-changelogs

Interesting details:

• For merge commits, the commit message is just Merge <branch> or Merge <pull_request>, which is very useless information. So for these, I list the commits in the merged branch. It's fairly noisy, but has tiny bits of information.
• In general, I don't find the information in the list super useful, but at least the list links to every single commit, which can help point the reader to the whole commit message and find out why certain changes happened.

Let me know what you think!

[tuxji]

I like the new output! It's more informative than the old output thanks to the human-readable descriptions and it was generated automatically. Over time, we can encourage RACK developers to write more informative commit messages (maybe use squash & merge when appropriate too) to improve the quality of the future human-readable descriptions. I would be happy to use this as our changelog! Kit and Abha, what do you think?

[kityansiu]

I like the new human-readable descriptions as well! Just one more request: if possible, instead of listing the changes in pre-releases, can we group them all under the release? For example, it's more meaningful to me if those listed under "Changes to v5.9" are instead listed under "Changes to v6.0" and get rid of the v5.9 section altogether.

[Ptival]

Done! Should we delete the 5.0 changelog then?

[kityansiu]

Yes, I think we can delete the older, manually generated RACK-v5.0-Ontology-Changelog. @Ptival, just one more question (hopefully)--on your new page, the following section seems like extra information that doesn't have to do with ontology changes: Changes for v5.0 -> Merge branch 'master' of https://github.com/ge-high-assurance/RACK. Just wanted to point that out.

[Ptival]

@kityansiu It's a little more complicated than that, but I might be able to make it slightly better.

The problem is that all these changes came in as one commit in the master branch history. It's a weird commit that adds a lot of noise indeed. Some of the commits it brought in are ontology changes (the ones with Incorporating ontology review), while others have nothing to do with it.

I think what I can try and do is to filter out that list for commits that actually touch the ontology. That way we should only have relevant commits listed on that page. I think it'll be much nicer that way, so thanks for pointing it out!

[tuxji]

Wrapping this up as done.