Contributing to sbt

This repository contains both an actively developed RTMB stock-assessment model and a frozen V1 implementation used to verify agreement with the historical ADMB model. Changes should preserve that distinction and make their scientific scope explicit.

Set up the package

Work from the sbt repository root. Install the development dependencies, then load the package sources:

devtools::install_deps(dependencies = TRUE)
devtools::load_all()

Do not use objects from the neighbouring sbt2026 assessment repository as implicit package inputs. Package examples and tests must declare all inputs and provenance needed to reproduce their results.

Make and verify a code change

Add or update focused testthat coverage with the implementation.
Regenerate NAMESPACE and man/ files after changing roxygen comments:
```
devtools::document()
```
Run the affected tests while developing:
```
devtools::test(filter = "grid")
```
Before handing off a completed change, run:
```
devtools::test()
devtools::check()
```

Warnings and notes must be inspected rather than treated as passing output. Avoid changing generated files by hand when they are owned by roxygen.

Protect the scientific implementations

Treat changes to model equations, data transformations, likelihoods, parameter maps, priors, dynamics, MSY calculations, and projections as scientific changes. For these changes:

update or add tests for the scientific behaviour, not only object structure;
compare the objective, gradient, and all relevant report values before and after a refactor that is intended to be numerically neutral;
update vignettes/equations_rtmb.qmd when the implemented equations change;
record user-visible changes in NEWS.md; and
do not describe a fit, grid, MCMC, MSY, or projection run as successful until its required diagnostics and final artifacts exist.

The sbt_model_v1() implementation is a frozen comparison model. It should call its _v1 helpers rather than active-model helpers so later development of the current model cannot silently change the V1 benchmark. A deliberate V1 change requires full comparison with the bundled ADMB reference outputs in vignettes/sbt_vs_admb.qmd.

Preserve fitted work and portable artifacts

RTMB objectives contain session-specific external pointers and must not be saved as production artifacts. Use:

sbt_fit_save() and sbt_fit_read() for fitted models;
the portable per-cell sbt_fit files produced by run_grid_mcmc() for MCMC grids; and
sbt_add_optimisation() or sbt_add_mcmc() when existing expensive results need to enter the portable lifecycle.

Repeated optimization should start from the best available parameter vector, including obj$env$last.par.best where appropriate. Do not discard a useful optimization or MCMC attempt merely because a later attempt is preferred; retain the result with its diagnostics and provenance.

Test fixtures

Bundled fixtures are test evidence, not current stock-assessment results. Do not silently overwrite them or regenerate them merely to make a failing test pass.

The conditional API fixture is built by:

Rscript data-raw/build-fit-api-fixture.R .

Its builder, source manifest, checksums, and explicit scientific_fit = FALSE metadata must remain consistent. If a model or canonical-data change invalidates a fixture, first establish whether the scientific behaviour changed and preserve the previous artifact as evidence when appropriate.

Articles and website

The Quarto files under vignettes/ are source-rendered pkgdown articles. The directory is excluded from the installed package by .Rbuildignore, so package checks do not replace explicit article rendering.

Render an affected article directly:

quarto render vignettes/sbt.qmd

Build the complete website when navigation or several articles change:

pkgdown::build_site()