Stock Synthesis: practices for maintainers

Stock Synthesis maintenance

This page documents practices by the SS3 development team regarding project management and maintenance.

Making changes to the source code

The default branch is main and is the current "working" version of Stock Synthesis building up to the next release. It should be passing all checks on github actions.

A feature branch should be created off of main and development should be done in the feature branch. Please open an issue and assign yourself to it to communicate to the SS3 development team and the SS3 community regarding the issue. When ready to merge in the work, a pull request must be used.

Submitting a pull request

A pull request should be opened to merge the feature branch into the main branch. Before merging in, the following requirements should be met:

• All github actions checks should be passing
• A member of the SS3 development team should test the feature and/or review the code. For example, this person can download the SS3 executable generated from the pull request and test on at least 1 model that the feature developed works as intended. They should also review every line on the code and feel free to as for changes as needed. Note that the main branch is protected, which means in this case that all changes must be submitted as pull request and at least 1 person must approve the changes before the code can be merged in.
• Once the reviewer is satisfied that the code is working as expected, the feature branch can be merged into the main branch and deleted. The issue can be marked as "Resolved" and should be added to the next release milestone to ensure it will be documented.

Maintaining issues

Any member of the SS3 development team should feel free to respond to or open issues. Good practices are:

• When new issues come in, they should be labeled either as bug or new request (If they fit these categories)
• New requests should be checked against current issues for duplication.
• Make the title as clear as possible to highlight what the issue is
• New requests should be added to the ss3-issue-triage board and can be ranked by time and priority there.
• Bugs should get assigned immediately to the upcoming milestone, because they are of high priority to address.
• add applicable labels to the issues. Try to use existing ones, but new ones can be added if something is missing.
• add yourself as the assignee if you intend to work an issue
• add someone else as the assignee if it is something only they can work on (it is also fine to ask someone in the comments if they would like to be assigned if unsure)
• searching for open, unresolved issues is facilitated by the search term "is:issue is:open -label:resolved"

Communication can happen about the issue as it is being worked. Others involved in the issue should be tagged with their github usernames to increase the chance that they will see the comment.

When work on an issue has been completed ,the "resolved" label should be added and it should be added to the milestone for the next release (e.g., 3.30.17 milestone). The issue should remain open until all documentation is completed. This includes entries in the change log and possibly revisions to the user manual, r4ss, and the SSI. The final entry to the Issue commentary should summarize the steps taken to effect the correction or change. It should only be closed if it requires no further action or if the actions to take have been documented in another issue (e.g., if a new feature needs to be documented, an issue can be opened in the doc repository to do this. Issues connected to a milestone will be closed (if it is appropriate to do so) shortly before a release.

Testing out versions of SS3

Test versions of SS3 are available from the call-build-ss3 job. Download the artifact to get a version of SS3 from the desired run to test out locally. More details are available in the compiling SS3 notes section on github actions.

Releases

We use Github Releases to distribute executables.

When a new release is coming up, open a new issue and select the "SS3 release checklist option" which uses the release checklist template here

Tag naming conventions in the stock-synthesis repository

• For a prerelease: v3.30.release_numbers-prerel, e.g., v3.30.18-prerel, where the release of 18 is to come shortly.
• For a release: v3.30.release_numbers, e.g., v3.30.18
• For a fix: v3.30.release_numbers.fix_numbers, e.g., v3.30.18.01, where .18 was the last release to happen.

These versions will be included in Stock Synthesis, added in by gh actions. Note that for untagged commits, the version in stock synthesis will be 3.30.release_numbers.beta, where release_numbers (e.g., 18) is the last release that has happened.

How to push a local tag up to github

All commands should be done from the command line.

1. Make sure your local branch is even with the main branch (use git fetch followed by git merge --ff-only to catch up. Then, use git status. The status should be:

On branch main
Your branch is up to date with 'origin/main'.
Nothing to commit, working tree clean

2. Add a lightweight tag locally using git tag my-tag-name, replacing my-tag-name with the appropriate convention (e.g., v3.30.19 for the .19 release)
3. Push the tag up to github by using git push origin my-tag-name.

Modifying or updating the test-models set

The model set for testing SS3 is available in the test-models repository models folder. call-run-ss3-with-est and call-run-ss3-with-no-est github action job. Each subfolder contains models for a different SS3 model, including:

1. Model input files (starter, data, control, forecast, and optionally weight at age).
2. Reference model output files (ss.par, warnings.sso, and ss_summary.sso). This is what we consider to be a "good" run of the model and what we want to test against. Typically, this is the last release, unless there have been changes since the release that means a more recent version of the model is more reliable.

To update a model, the following steps should be done:

1. clone the repo locally to get the original model files
2. Make the model changes and run with the last "good" version of SS3 (default to the last release unless there is a reason not to).
3. commit the new model input files and reference model output files to the repository
4. Push up the changes to the main branch of test-models
5. run the build-no-est job manually on the main branch of the stock-synthesis to see if the main branch is still passing with the new model changes. If not, more investigation into whether this is a problem with SS or the model will be needed.

Upon each release, the reference model output files should be updated to that release by manually running this github action

Posting a fix to a release

If a bug with the release version of Stock Synthesis is found and deemed widespread enough, a fix version of the executable will be compiled and posted to github releases. Note that this is an experimental exe and may include new features, so users probably should err on the side of using the release.

Checklist for compiling and posting a fix:

• Check all github actions are passing.
• Update the stock-synthesis change log.
• tag the repository with a lightweight tag. Tag should be named v3.30.release.fix, e.g., v3.30.17.01. This must be done before compiling.
• Run github actions call-build-ss3 to compile the executables
• Download the artifacts from the github actions run. Should be 4 total binaries. Confirm the version info is correct in the ss.tpl file downloaded with the binaries.
• Upload the artifacts to a new github release associated with the tag created.
• Communicate to users about the fix (specifically, the folks who discovered the issue).