-
Notifications
You must be signed in to change notification settings - Fork 932
Home
Thank you for your interest in contributing.
This guide assumes that you have created your own fork of the seurat 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.
- Introduce yourself to Git by running the following commands in a terminal:
git config --global user.email [email protected]
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 for more information.
- Navigate to the root directory of your local copy of
seurat/and run:
git remote add upstream [email protected]:satijalab/seurat.git
This associates the name upstream with the official seurat 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 from upstream (the official repository), make changes locally, push your changes to origin (your fork), and then submit a pull request asking seurat to merge your changes from origin into upstream.
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 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 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 Seurat - 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 @rsatija and/or @dcollins15.
In general, we try to adhere to Google's R Style Guide which is a fork of the Tidyverse Style Guide. The main exceptions are described below.
According to [section 2.1] of the Tidyverse Style Guide:
Variable and function names should use only lowercase letters, numbers, and . Use underscores () (so called snake case) to separate words within a name.
Base R uses dots in function names (contrib.url()) and class names (data.frame), but it’s better to reserve dots exclusively for the S3 object system. In S3, methods are given the name function.class; if you also use . in function and class names, you end up with confusing methods like as.data.frame.data.frame().
However, we make liberal use of dots in variable names (e.g. pt.size).
According to section 2.4.1 of the Tidyverse Style Guide:
A function’s arguments typically fall into two broad categories: one supplies the data to compute on; the other controls the details of computation. When you call a function, you typically omit the names of data arguments, because they are used so commonly.
However, thoughout much of the codebase we explicitly name all arguments in function calls. Moving forward, we'd like to ammend this practice to conform to the Tidyverse style guide. Although you may notice in the form mean(x = 1:10, na.rm = TRUE), we now prefer mean(1:10, na.rm = TRUE) instead.
We following section 7 of the Tidyverse Style Guide, rather than Google's guidance, meaning we document our code in-line using roxygen2's syntax.