search

nmfs-ost / ss3-doc

Source code for the Stock Synthesis manual and other documentation
https://nmfs-ost.github.io/ss3-website/
Creative Commons Zero v1.0 Universal
4 stars 3 forks source link

better document process for updating the user manual after a release #129

Closed iantaylor-NOAA closed 3 days ago

iantaylor-NOAA commented 2 years ago

The links at the top of https://nmfs-stock-synthesis.github.io/doc/ needed updating from the 3.30.19 manual to the 3.30.20 version instead. I just attached the pdf version to the release by editing https://github.com/nmfs-stock-synthesis/stock-synthesis/releases/tag/v3.30.20 and manually uploading the 3.30.20 pdf.

To create the HTML manual for the for the 3.30.20 release I tried to run the "Build html for last release using texlive" action but it failed: https://github.com/nmfs-stock-synthesis/doc/actions/workflows/call-ss3-manual-html-release.yml. However, it looks like the last time @k-doering-NOAA ran that action was in December 2021 whereas the 3.30.19 release was in April 2022, so maybe the particular features of that action aren't important.

Given that the changes to the manual since the release have all been fixes rather than reflecting changes to the model, I went ahead and replaced the online file https://nmfs-stock-synthesis.github.io/doc/SS330_User_Manual_release.html with the artifact of the most recent run of the "Build html using texlive" action: https://github.com/nmfs-stock-synthesis/doc/actions/workflows/call-ss3-manual-html.yml.

Before the 3.30.21 release it would be good to better document the steps to update the manual and either deprecate the failed action or get it to work. That documentation may exist, but wasn't obvious from looking at the release checklist https://github.com/nmfs-stock-synthesis/stock-synthesis/issues/352#issue-1308326395 or the github action descriptions: https://docs.google.com/document/d/1hniPVEobdzEQqdIsAiHavZgze70TgGQzYiwP7T4SUWw/.

chantelwetzel-noaa commented 2 years ago

I am definitely confused here because I have a distinct memory of updating these links on the github.io page on the Friday of the last release. I remember because I had to dig to figure out where this was done at and I think I remember testing the links out. Either way, I do agree that having full documentation would create a smoother release process.

k-doering-NOAA commented 2 years ago

The process is definitely not streamlined. I opened an issue on this a while back, but unfortunately did not work on it: https://github.com/nmfs-stock-synthesis/doc/issues/161

I think the gha may be failing because the tag for the manual release within the doc repository is called 3.30.20 rather than v3.30.20(which is what the gha currently assumes). I suspect I ended up not running this for the last release because I just pulled from the "Build html using texlive" action as @iantaylor-NOAA did. I thought it might be nice to have just in case you ever need to "roll back" to that tag to regenerate the html or pdf when the repo has moved on past the release.

iantaylor-NOAA commented 2 years ago

@chantelwetzel-noaa this is definitely confusing. I see a commit to the gh-pages branch: https://github.com/nmfs-stock-synthesis/doc/commit/519bf3a72b9640b4e8589b550ab65b3a12e048f1, but I think that this branch gets automatically overwritten by one of the github actions based on whatever is in the contents of this file: https://github.com/nmfs-stock-synthesis/doc/blob/main/docs/index.md, so maybe that's the source of the confusion.

@k-doering-NOAA, I look for issues in stock-synthesis and docs but forget to look in workflows. Now that the updated manual seems to be in place and working, I'm assuming there's no point in aligning the tags (adding "v" to "3.30.20" or subtracting from the older ones).

e-perl-NOAA commented 3 days ago

Resolved with release workflow