I recommend implementing release notes in documentation and removing the long history in the code. Maybe Brian can take this on as part of StateMod documentation updates.
The StateMod statem.for file contains a long history of modifications. I recommend that this history be moved to documentation release notes and removed from the StateMod code, for the following reasons:
The text in the code is difficult to read because it is formatted using Fortran code limitations (columns 6-72, etc.). Moving to Markdown would be easier to read.
The output is only available to people that install and run the software, whereas release notes in online documentation would be available to anyone.
The output from the model is not hyperlinked. Using Markdown would allow linking to appropriate sections of the documentation for updated features.
Continuing to maintain the history in the code is not necessary because version control tracks changes. Ray's habit of adding code comments for specific edits could continue to be used, although old comments that are no longer relevant should be removed over time as code is maintained.
The large amount of text in the code causes the executable to be larger because that text is included character by character in the executable. There is a significant amount of text.
Having more visible release notes will allow people to more easily track down information about when features were added and bugs fixed.
Release notes can be linked to repository issues, although that can be a challenge if not one-to-one.
Online release notes facilitate correlation with software download pages because people can find a software version where a change was made.
The downside of moving release notes to documentation is that programmers will need to also update the documentation in parallel fashion, or work with someone to do it. However, this is actually a good thing and is typical for software projects. An issue can be posted to documentation to accumulate release notes from developers and then someone can integrate in the documentation before release. It really is not that much work to coordinate.
I recommend implementing release notes in documentation and removing the long history in the code. Maybe Brian can take this on as part of StateMod documentation updates.
See also StateMod code issue 43.
The StateMod
statem.forfile contains a long history of modifications. I recommend that this history be moved to documentation release notes and removed from the StateMod code, for the following reasons:The downside of moving release notes to documentation is that programmers will need to also update the documentation in parallel fashion, or work with someone to do it. However, this is actually a good thing and is typical for software projects. An issue can be posted to documentation to accumulate release notes from developers and then someone can integrate in the documentation before release. It really is not that much work to coordinate.