Maintainer's Guide

This page is intended for members of the satijalab organization.

Initial Setup

Same as for contributors, except there's no need to fork your own copy of the repository since you should have write access.

Pull Requests

One of the maintainer's main responsibilities is making sure that PRs are properly reviewed and merged. If a PR makes changes to the core package (i.e. any file not listed in ``) then the version must be bumped. Always rebase onto main before merging a PR to keep the Git history linear (you can generally do this in the GitHub UI).

When merging a pull request into main, be sure to always make a merge commit (do not squash merge).

Release Cycle

Our release cycle follows a continuous delivery model backed by GitHub Actions. The main branch is always kept production‑ready, with automated checks running on every pull request & push. We cut releases when we decide there are sufficient new features and fixes merged, or on a regular schedule (e.g., quarterly). Each release goes through a dedicated branch and final preparation before publication, according to GitLab Flow.

Major & Minor releases

On demand, we create minor release branches only when preparing a CRAN release. Each branch is named {MAJOR}.{MINOR}-stable (e.g. 5.2-stable) and is forked from main as late as possible to minimize maintenance.

Once a release branch is cut:

• Only serious bug fixes go into the branch (i.e., CRAN errors)
• Adopt an upstream-first policy: merge fixes into main first, then cherry-pick into the release branch to prevent regressions in future releases.
• After adding a fix to the stable branch, bump the patch version and create a corresponding Git tag (following Semantic Versioning).

Cut a new release branch

git fetch origin
git checkout -b v{MAJOR}.{MINOR}-stable
git push origin v{MAJOR}.{MINOR}-stable

Start a new branch for final release prep

git checkout -b release/{major.minor.version}

Bump the version

Finalize news.md

Push & Open a PR against the stable branch

git push origin release/{major.minor.version}

Use the following template for your PR description:

Final updates before submitting `SeuratObject` v{MAJOR}.{MINOR}.{PATCH} to CRAN 🚀 

- [x] Bump version
- [x] Finalize changelog
- [ ] [Pre-Release Checks](https://github.com/satijalab/seurat/actions/workflows/release_checks.yaml)
- [ ] [Reverse Dependency Checks](https://github.com/satijalab/seurat/actions/workflows/reverse_dependency_checks.yaml)
- [ ] [win-builder](https://win-builder.r-project.org/) (R-release, R-devel, R-oldrel)
- [ ] [macOS builder](https://mac.r-project.org/macbuilder/submit.html) (R-release, R-devel)
- [ ] Update CRAN comments

Run Reverse Dependency Checks

Build the package

Use the satijalab/seurat-ci:latest Docker image for a reproducible environment:

docker pull satijalab/seurat-ci:latest
docker run --rm -it -v .:/seurat-object satijalab/seurat-ci:latest bash

From inside the container:

cd seurat/
installDeps.r -s
R CMD build .

Submit package to the win-builder (R-release, R-devel, R-oldrel)

Submit package to the macOS builder (R-release, R-devel)

Update cran-comments.md and finalize the PR

Merge the PR

Make sure to do a squash merge.

Rebuild the package

Submit to CRAN

Tag the release

Update the cran branch

git fetch origin
git checkout cran
git reset --hard v{MAJOR}.{MINOR}-stable
git push origin cran --force-with-lease

Rebuild and deploy package docs

Run the Documentation Action to rebuild the pkgdown site and deploy it the GitHub Pages. Make sure to select the Deploy to Pages option.