SPDK Development

In this document:

License

SPDK is primarily licensed using a BSD 3-clause license. Some optional or utility code, such as kernel modules, is licensed using a dual BSD/GPLv2 license. All submitted code must carry the appropriate license.

Development Guidelines

These general guidelines help ensure that the SPDK development community remains fun, fair, and efficient.

  • Developers should strive to be active on GerritHub in order to stay in the loop on upcoming changes.
  • Trello is where we maintain our backlog and is a great place for design material for more complex patches. Once code has been merged, however, the documentation in the repository supersedes any materials found on Trello (i.e., collateral found on Trello is not maintained once a feature is merged).
  • The maintainers do their best to “star” patches that are likely to have impact on applications or other ongoing work, please keep an eye out for those items.
  • Coding and submission guidelines (i.e. being clear and concise in the commit message) should always be respected.
  • Developers do not need to add specific reviewers to patches, the maintainers and everyone else in the community should always be on the lookout for incoming patches. If a developer would like to be added to a review, or would like a specific person added to their patch, they should feel free to do so.
  • There’s no min or max time for the lifecycle of a patch, depending on a variety of factors a patch may go through in hours or possibly weeks or longer. How efficiently our community operates is a direct result of how well our community developers interact with each other.

Source Code

SPDK’s source code is hosted by GitHub and code review is done through GerritHub.

Directions for getting the code, building the modules, running tests, etc., are all found in the GitHub.

Contributing

Everyone is welcome to contribute! Design pre-work and general discussion occurs via one of the communications channels described on the Community page.

Patch submission is done through GerritHub where patches are voted on by everyone in the community. A patch requires a minimum of two +2 votes before it will be merged. +2 votes are reserved for the project maintainers who can also be found on the mailing list or in IRC.

GerritHub Configuration

You’ll log in to GerritHub using your GitHub account. Here are a few common settings you might want to setup for SPDK:

  • Profile: Verify that the information is correct here.
  • Preferences:
    • Set Maximum Page Size to 100 rows per page. Otherwise you’ll be hitting ‘next’ a lot.
    • We highly recommend you set your Email Notifications to None. Gerrit can send a lot of emails!
    • In the My Menu section, add the following entry:
    Name: SPDK Open Reviews
    URL: #/dashboard/?Outgoing=projects:spdk+o:self+status:open&Needs%20Review=projects:spdk+r:self+-o:self+status:open&Open=projects:spdk+status:open+-r:self+-o:self
    

    You can probably also delete the other entries in there. This will add a link at the top of the page under “My” that will show you a nice dashboard of all of the SPDK review activity.

Now that you’re configured, you can clone the GerritHub repository locally:

git clone https://review.gerrithub.io/spdk/spdk
cd spdk
git submodule update --init

Or if you already cloned directly from GitHub, you can change your repository to point at GerritHub by doing:

git remote set-url origin https://review.gerrithub.io/spdk/spdk

This will prompt you for a username and a password. The username is your GitHub name, but the password is the one generated from the HTTP Password section on GerritHub. You can use the git credential helper to store your password for you. You can enable it for the SPDK repository with:

git config credential.helper store

Finally, you’ll need to install the Gerrit commit-msg hook. This inserts a unique change ID each time you commit and is required for Gerrit to work.

curl -Lo .git/hooks/commit-msg https://review.gerrithub.io/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

Now open .git/config in a text editor and add these lines: (this will make pushing reviews easier)

[remote "review"]
  url = https://review.gerrithub.io/spdk/spdk
  push = HEAD:refs/for/master

Now you should be all set!

Submitting a Patch

Submission Requirements:

  • All commits must be signed off by the developer which indicates that you agree to the Developer Certificate of Origin. This is done using the -s or --signoff option when committing your changes.

  • All commits must conform to the SPDK style guide. The style guide is defined by the script located in scripts/check_format.sh, which will programmatically fix coding style issues using the tools astyle and pep8. Be sure to run this script prior to submitting a patch.

  • All new code must include accompanying unit test code.

  • Commits should be rebased and all unit tests should be passing prior to submission.

  • Squash commits prior to submitting a review such that each commit has a clear purpose that takes an incremental step toward the goal of the series of commits.

  • Provide a clear commit message describing the purpose of the commit. Good commit messages provide a very brief summary of what the commit does in the title followed by a short paragraph providing context for the change. For example, what problem is being solved, how was it discovered and how this patch solves the problem.

Development on SPDK is all done based on the master branch, so start by making sure you have the latest. The below assumes origin is pointed at GerritHub.

git checkout master
git pull

Next, create a branch for your development work.

git checkout -b <my_branch>

Then, make your changes and commit as you go. You’ll build up a branch off of master with a series of commits. Once you are done, pull the latest from master again and rebase your changes on top.

git checkout master
git pull
git checkout <my_branch>
git rebase -i master

Now your branch should be based on the tip of master and you should have the tip of checked out. You can push your code to Gerrit for review by doing the following:

git push review

Continuous Integration

SPDK employs continuous integration (CI), which means all patches are run through a series of tests before they are even reviewed. The SPDK CI system periodically looks at GerritHub, pulls the patches down, and runs them on a pool of multiple machines with real NVMe SSDs. The tests are all checked in to the main SPDK repository (follow autorun.sh in the root of the repository). That means that users can add tests to the CI system by simply submitting a patch. Tests are required to be added in the same patch as the new code they are testing.

The status of the CI system includes an overview of the queued patches. Note that patches will not automatically be queued up, but instead require a cursory approval from one of the SPDK maintainers before they run. Patches pending approval for a run through the CI system are listed under the ‘Pending Approval’ table on the CI status page.

When the CI system completes, it will post a comment on the Gerrit review with a +/-1 Verified flag, plus a link to the logs of the test run. This is particularly useful if the tests fail. Patches will not be merged without a +1 Verified from the CI system.

If the CI system gives your patch a -1 but you believe it is in error (not related to your patch), please ask a maintainer (via IRC) to have your patch re-run.

Code Review

Everyone is encouraged to review all patches and mark them with a +1 (thumbs up) or -1 (thumbs down). Code review feedback is highly valued, so even if you are a beginner with SPDK, please jump in and start reviewing patches. For a patch to be merged, two maintainers must give it a +2 vote, only maintainers are allowed to use +2.

Revising Patches

SPDK has fairly high standards for patch approval. We try to strike a balance between maintaining a high velocity and not allowing ourselves to become overwhelmed in technical debt. Given this, you should expect all non-trivial patches to go through at least a few rounds of code review.

Fortunately, Gerrit makes it very easy to update an outstanding review. You simply update the commits in your git repository to incorporate the new changes and push again. For instance:

git checkout <my_branch>
  address code review feedback
git commit -a --amend
git push review

Multi-Commit Patch Series

Gerrit has excellent support for creating series of patches, where each commit is reviewable separately but is dependent on the previous one for merging. You can push an entire series of patches to Gerrit using the following steps:

git checkout master
git pull
git checkout <my_series>
    make some changes
git commit -s -a # Change 1
    make some changes
git commit -s -a # Change 2
    make some changes
git commit -s -a # Change 3
git push review

Gerrit will create three reviews, each dependent on one another. Inevitably, a reviewer will ask you to make a change during code review on change #2. To address that feedback, you could do the following:

git checkout <sha of change #2>
git checkout -b tmp # 'tmp' or any name you want
    address code review feedback
git commit -s -a --amend # The amend modifies change #2 to include your updates
git checkout <my_series> # Points at change #3
git rebase -i tmp # Move change #3 on top of the new change #2
git push review
git branch -D tmp # Clean up the 'tmp' branch