planetarysoftware / ISIS_TC

ISIS Technical Committee
https://github.com/USGS-Astrogeology/ISIS3
6 stars 11 forks source link

Improvements to Changelog #178

Open AndrewAnnex opened 1 year ago

AndrewAnnex commented 1 year ago

During the last TC meeting, a topic that was discussed was the need to better communicate changes to ISIS to help with misconceptions about the ISIS release frequency. One of the approaches considered were to improve the ISIS changelog https://github.com/USGS-Astrogeology/ISIS3/blob/dev/CHANGELOG.md document, and this issue was created to facilitate discussion around ideas.

Some ideas we had were:

  1. defining some sort of length requirement for entires in the changelog to ensure pertinent changes are highlighted.
  2. creating a more-for-humans version of the changelog that doesn't discuss specific commits but attempts to communicate the most important details about the changes for developers and users separately

an idea I should have mentioned before is that 2 above could be addressed by using the space under the release subheadings (eg line under ## [7.1.0] - 2022-07-27) for a paragraph or two discussing those changes.

jlaura commented 1 year ago

Another important discussion point made was that the changelog is currently developer-centric. From that perspective, the changelog may be entirely adequate and a supplemental, plain language document may be more appriopriate for other use cases.

Perhaps we can identify what goals the document(s) would ideally meet and then we can determine where changes might be best applied?

rfergason commented 1 year ago

Another discussion point is that any needed changes made to changelog requirements will also impact the process for contributing to the ISIS repository. I think the responsibility of documenting the change should be on the individual who developed the code and submitted the PR for that change (i.e., not ASC developers when they are working to release a new version of ISIS). Thus, any additional needed changelog requirements would also need to be reflected in that documentation as well.