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

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

Open
iantaylor-NOAA opened this issue Oct 17, 2022 · 3 comments
Open
Labels
documentation Improvements or additions to documentation User Guides

Comments

@iantaylor-NOAA
Copy link
Contributor

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 nmfs-ost/ss3-source-code#352 (comment) or the github action descriptions: https://docs.google.com/document/d/1hniPVEobdzEQqdIsAiHavZgze70TgGQzYiwP7T4SUWw/.

@iantaylor-NOAA iantaylor-NOAA added documentation Improvements or additions to documentation User Guides labels Oct 17, 2022
@chantelwetzel-noaa
Copy link
Contributor

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

k-doering-NOAA commented Oct 17, 2022

The process is definitely not streamlined. I opened an issue on this a while back, but unfortunately did not work on it: #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
Copy link
Contributor Author

@chantelwetzel-noaa this is definitely confusing.
I see a commit to the gh-pages branch: 519bf3a, 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).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation User Guides
Projects
None yet
Development

No branches or pull requests

3 participants