Home

Contributor's Guide

Thank you for your interest in contributing! We're always appreciative when folks take the time to help improve SeuratObject.

Initial Setup

This guide assumes that you have created your own fork of the seurat-object repository, cloned the repository on your local machine, and successfully installed it. Before getting started, there are a couple of other one-time setup steps you need to complete.

1. Introduce yourself to Git by running the following commands in a terminal:

git config --global user.email you@yourdomain.com
git config --global user.name "Your Name"

This information credits you for your work, but note that it will become publicly available if you “push” your work to GitHub. See Setting your commit email address in Git for more information.

2. Navigate to the root directory of your local copy of seurat-object and run:

git remote add upstream git@github.com:satijalab/seurat-object.git

This associates the name upstream with the official seurat-object repository. Note that when you cloned your fork, Git automatically associated it with the name origin. You need both of these remotes because you will typically start with the latest version of seurat-object from upstream (the official repository), make changes locally, push your changes to origin (your fork), and then submit a pull request asking seurat-object to merge your changes from origin into upstream.

Development workflow

Start a new feature branch

Fetch new commits from the upstream repository:

git fetch upstream

Next, create a new branch based off the upstream repository's main branch - the branch name should help to indicate the change being made:

git checkout -b <branch-name> upstream/main

Make and commit local changes

Make some changes. When you feel that you've made a complete, working set of related changes, identify which files have been updated:

git status

Stage the files you want to include in your commit:

git add <file1> <file2>

Commit your changes — commit messages should be written in the present tense using the imperative mood, and should provide a brief description of the change being made:

git commit -m "Improve feature X"

Push the feature branch and submit a pull request

Push your feature branch to your fork:

git push origin <branch-name>

Before submitting a pull request, please ensure that:

• You have added a description of your updates to the package's changelog
• You have updated and regenerated all documentation with roxygen2 — see Roxygen2's documentation for guidance
• You have incremented the package version*
• You have written or updated tests for your changes**
• All tests are passing

*origin/main always contains a pre-release version of SeuratObject - version bumps should increment the pre-release version number (e.g. 5.0.2.9001 -> 5.0.2.9002)

**The current test coverage for the package is a bit limited. While we encourage contributors to write unit tests for their changes, it is not mandatory. If no tests are introduced or updated, please include a small reproducible example of your fix/feature in the description of your pull request.

When you feel that your work is finished, create a pull request by following GitHub's guide and request a review from @dcollins15.