Skip to content

Stock Synthesis: practices for maintainers

Jump to bottom
Kathryn Doering edited this page Apr 28, 2021 · 20 revisions

Stock Synthesis maintainence

This page documents practices by the SS development team regarding project management and maintainence of SS.

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 as well as the model runs on Jenkins.

Small changes that are very unlikely to change Stock Synthesis model results (e.g., editing readmes, updating a few words in a warning message) may be pushed directly to the main branch.

For larger changes, 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 SS development team and the SS community regarding the issue. When ready to merge in the work, a pull request should 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 full jenkins model run should be done (let @k-doering-NOAA know to start the run), unless the change is not to the SS source code, but to auxilary items like github actions build jobs, documentation, adding code comments.
  • A member of the SS development team should test the feature and/or review the code. For example, this person can download the SS executable generated from the pull request and test on at least 1 model that the feature developed works as intended.

Maintaining issues

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

  • adding applicable labels to the issues. Try to use existing ones, but new ones can be added if something is missing.
  • adding yourself as the assignee if you intend to work the issues
  • adding someone else as the assignee if it is something only they can work on (it is also fine to ask someonein the comments if they would like to be assigned if unsure)

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 compeleted 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 can remain open or closed if you prefer. 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 ss-documentation 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 SS

Test versions of SS are available from the build-win-basic github action. Download the artifact to get a version of SS from the desired run to test out locally. More details are available in the compiling SS notes section on github actions.

Releases

This section is subject to change, as we have not done a release since transitioning to github.

Github release will be used in addition to vlab (for now) to distribute SS executables.

Checklist for release - this can be copied and pasted into an issue.

- [ ] SS testing and debugging completed (IT or KD)
- [ ] r4ss updated (IT)
- [ ] code committed and tagged in repo (RM)
- [ ] examples updated and added to vlab (KD)
- [ ] Helper spreadsheets updated (KD)
- [ ] Helper spreadsheets added to vlab (KD)
- [ ] Change log updated on vlab community (KD)
- [ ] SS manual updated and tagged in repo (CW)
- [ ] Updated SS manual added to vlab (KD or CW)
- [ ] Exe and .tpl archived on Google drive (RM)
- [ ] OSX and linux exes built (KD)
- [ ] All exes added to vlab (KD)
- [ ] All exes added to github releases (KD)
- [ ] Upload 3.30.16 .tpl to vlab (KD)
- [ ] Put together release announcement (RM or KD)
- [ ] Send out release announcement msg (RM)
- [ ] SS GUI updated (NS)
- [ ] Submit r4ss to CRAN (IT)
- [ ] Submit ss3sim to CRAN (KJ)
- [ ] Update ss-test-models reference files to the release version (KD)

Modifying or updating the ss-test-models set

The model set for testing SS is available in the ss-test-models repository models folder. This is used by the Jenkins job that does full model runs, as well as by the build-no-est github action job. Each subfolder contains models for a different SS 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" vesrion of SS (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 ss-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. KD has a script to do this.

Clone this wiki locally