Developers

How can I contribute?

While the most obvious ways to contribute are to report bugs, suggest features, and add code, we want to make it clear that you don't have to contribute code to make SSMSE better. In particular, we would love help with documentation, creating examples, and designing graphics (e.g., a hex sticker). However, we would love to hear other ways you would like to contribute, too, so please don't hesitate to reach out.

Conventions for contributing code

For those who wish to contribute code to SSMSE, please be aware that we try to follow these conventions.

Style

In general, please follow the Tidyverse style guide when developing new code. We strive to follow this guide, although you may find slip-ups within the code. Periodically, we use the Styler package on the whole codebase to keep code style consistent.

Making descriptive commit messages can be helpful; we recommend following these guidelines to improve formatting of commit messages. If a commit is associated with an issue, it is also helpful to include the issue number in the commit (e.g., including #123 in the commit message will add a note to issue 123 that the commit referenced the issue).

Workflows for contributing

See this nmfs-fish-tools resource for general workflow advice on github. Specific workflow guidance for SSMSE is outlined below.

Workflow for developers with direct push access

Developers with push access to the SSMSE repository will use a feature branch workflow with pull requests. Note that the "master" in the linked resource would be how the "development" branch is treated in SSMSE. If the developer wants work to be reviewed before being merged into development, they will follow this workflow. Otherwise, for work that they do not want reviewed, they can push directly to the development branch.

Workflow for developers without direct push access

Developers without direct push access can fork the repositoryto do their work in and then submit a pull request. This workflow would be the easiest way to incorporate your work into the existing code base. However, SSMSE's primary developers are open to other ways of incorporating work into the code base for those who are not comfortable submitting pull requests, as we do not want pull requests to be an impediment to adding in useful work. Just ask!

Want to contribute, but need help understanding SSMSE?

Maybe this wiki page on organization or the user manual can help.

Notes on how to edit and update the bookdown user manual

The SSMSE user manual is written using bookdown. The source code for the manual is in .Rmd files in the inst/bookdown subfolder of SSMSE. Each chapter is in a separate .Rmd file.

To update the user manual:

1. Edit .Rmd locally on your computer and commit changes.
2. use bookdown::serve_book(dir = "inst/bookdown", output_dir = "../../docs/manual) to update the .html output files in docs/manual. This will also show a preview of the output. Note that if more changes are made and save to the .Rmd files, the serve_book command will automatically recompile the output on saving. To stop recompiling, restart the R session.
3. Output is saved in the docs/manual subfolder of SSMSE. Commit the changes made to this folder and push them to remote to update the documentation online. Note that these changes need to be in the main branch to show up online.

How to make Linux/mac versions of Stock synthesis (and other programs) executable

Linux and Mac versions of SS need to have executable permissions to run, which is not always the case. It is not obvious how to know when this is the case if developing on a Windows Machine. However, this article explains how to easily see the permissions and change the permissions using git on a Windows machine.