Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improvements to Changelog #178

Open
AndrewAnnex opened this issue Jan 13, 2023 · 2 comments
Open

Improvements to Changelog #178

AndrewAnnex opened this issue Jan 13, 2023 · 2 comments

Comments

@AndrewAnnex
Copy link
Member

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
Copy link
Collaborator

jlaura commented Jan 13, 2023

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
Copy link
Collaborator

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants