-
Notifications
You must be signed in to change notification settings - Fork 16
Stock Synthesis: practices for maintainers
This page documents practices by the SS development team regarding project management and maintenance.
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.
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 auxiliary 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.
- 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 double check that the issue was added to the correct milestone)
Any member of the SS 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 categores)
- New requests should be checked against current issues for duplication.
- Modify the titles when the issue is not made clear with the title.
- New requests may be added to "wishlist" and moved from new request if they are high priority
- Bugs should get assigned immediately to the upcoming milestone, because they are of high priority to address.
- 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 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"
- Note that Rick will assign the label "On Rick's Workbench" or "In progress" (these are synonomous) when working an issue
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 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.
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.
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. Evolution to release through FIT is anticipated in future.
Checklist for release - this can be copied and pasted into an issue.
## Checklist for before prerelease
- [ ] SS testing and debugging completed (KD)
- [ ] r4ss updated (IT)
- [ ] Put together pre-release announcement (RM or KD)
- [ ] code committed and tagged in repo as v3.30.20-prerel (KD)
- [ ] All exes added to github releases as v3.30.20-prerel (KD)
- [ ] Announce prerelease (RM)
## Checklist for before release
- [ ] Manual updated and tagged in repo (CW)
- [ ] Manual added to a github release, include attaching a pdf version (KD or CW)
- [ ] Manual release version on website updated once pdf and html built (KD)
- [ ] SSI updated (NS)
- [ ] Make changes to SS3 if any bugs caught in prerelease
- [ ] Change log updated in Stock Synthesis repo (KD)
- [ ] Code committed and tagged in repo as v3.30.20 (KD)
- [ ] Exe and .tpl archived on Google drive (KD)
- [ ] All exes added to github releases as v3.30.19 (KD)
- [ ] Add GUI to vlab (KD)
- [ ] Send out release announcement msg (RM)
## Checklist for after release
- [ ] examples updated in user-examples repo using [this script](https://github.com/nmfs-stock-synthesis/user-examples/blob/main/R/update_examples.R) (KD)
- [ ] Update ss-test-models reference files to the release version using [this update script](https://github.com/nmfs-stock-synthesis/test-models/blob/main/.github/r_scripts/update_ref_files.R) (KD)
- [ ] Removed "resolved" tag and close all issues worked in the milestone for this release (KD)
- [ ] Move unworked issues for the release milestone to the next milestone (KD)
- 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.
All commands should be done from the command line.
- Make sure your local branch is even with the main branch (use
git fetchfollowed bygit merge --ff-onlyto catch up. Then, usegit status. The status should be:
On branch main
Your branch is up to date with 'origin/main'.
Nothing to commit, working tree clean
- 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) - Push the tag up to github by using
git push origin my-tag-name.
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:
- Model input files (starter, data, control, forecast, and optionally weight at age).
- 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:
- clone the repo locally to get the original model files
- Make the model changes and run with the last "good" version of SS (default to the last release unless there is a reason not to).
- commit the new model input files and reference model output files to the repository
- Push up the changes to the main branch of ss-test-models
- 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.
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. 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.
- Check version info is correct. Convention is 3.30.release_numbers.fix_numbers
- Run github actions build-win, build-mac, build-centos
- Download the artifacts from the github actions and rename if needed (follow conventions of last release). Should be 6 total binaries.
- Upload the artifacts to the fixes folder on vlab. Is within the latest executables folder.
- Update the change log text document for the fixes (located on vlab) added to the new fixes executable.
- tag the repository with a lightweight tag. Tag should be named v3.30.release.fix, e.g., v3.30.17.01.
- Communicate to users about the fix (specifically, the folks who discovered the issue).