The Stock Synthesis development workflow
Stock Synthesis is a generalized population dynamics modeling program used for stock assessments. It is used both for operational assessments and for research.
Stock Synthesis has one primary developer, but a total team of six. The other team members occasionally contribute directly to the Stock Synthesis codebase, but primarily work on other aspects (e.g., documentation, development/maintenance of tools, contributing ideas on improving Stock Synthesis).
Our workflow has evolved over time, mostly to facilitate better communication amongst team members and to produce a more reliable product for end users of Stock Synthesis through the use of increasingly standardized operating procedures and automated steps. There was a learning curve, so over time we have slowly formalized our workflow and arrived at our current state based on our team members’ comfort level with being able to manage the steps.
We use github flow
We still use the Stock Synthesis forum on vlab to communicate new releases to users, as well as for users to ask questions. The Stock Synthesis vlab website provides links to Stock Synthesis executables and resources, although many are managed on GitHub. Users also send their questions to nmfs.stock.synthesis@noaa.gov and (very occasionally) open GitHub issues. Information for users is also included in the readme on GitHub.
- Workflow evolves over time, so assume this will happen. Your team will learn by trial and error what you like and don’t like (e.g., we used to use vlab to host our repositories, but now use GitHub; we tried out using a google “room” group chat (now called spaces) for communication, but we didn’t like it).
- Choose a workflow that your team can use. E.g., we don't use git-flow because it is far too complicated for our team’s knowledge of git right now. Instead, we opted for a simpler main branch + feature branches structure which we can all reliably use.
- Integrate testing and review into your workflow. Many of us are used to just pushing up code without any checks, but this means the mistakes are caught later on (or maybe not caught at all). For Stock Synthesis, we haven’t needed to release as many “fixes” between releases since adding testing and (somewhat informal) code review to our workflow.
- Don’t forget about documentation. We’ve used github issues in the doc repository to help us remember to make changes to documentation.
- Automate repetitive tasks as much as you can. E.g., we used to have to log onto separate mac and linux machines and manually compile Stock Synthesis; now gh actions does this for us, which saves time. We also used to run tests locally on our computers, and now gh actions runs it for us, so we run tests more frequently with less work.
- Stock Synthesis is one integrated code that must be compiled in its entirety. This precludes unit testing.
- As new features are added they typically bring in a feature that is untestable by the existing testbed of examples. Of course, it is still important to know that the code to implement the new feature has not broken something, but testing of new features requires custom examples.
- Our team has other responsibilities, and a constantly evolving workflow can be challenging to keep track of.
- When we release “fixes” they also include any new features that had been worked on, because we don’t keep fixes and new features on separate branches.