Basic Workflow

The following chart illustrates basic development workflow:

../../../_images/c9b17295327f5c4d2b53471b99bc16c2875fb3b7331e5d66474eee4febccfdfc.png

This page assumes that you are a new contributor with an idea for a bugfix or an enhancement, but you do not know how to proceed. Watch the Getting Started with Ceph Development video for a practical summary of this workflow.

Update the tracker

Find the Redmine issue tracker number of the bug you intend to fix. If no tracker issue exists, create one. There is only one case in which you do not have to create a Redmine tracker issue: the case of minor documentation changes.

Simple documentation cleanup does not require a corresponding tracker issue. Major documenatation changes do require a tracker issue. Major documentation changes include adding new documentation chapters or files, and making substantial changes to the structure or content of the documentation.

A (Redmine) tracker ticket explains the issue (bug) to other Ceph developers to keep them informed as the bug nears resolution. Provide a useful, clear title and include detailed information in the description. When composing the title of the ticket, ask yourself “If I need to search for this ticket two years from now, which keywords am I likely to search for?” Then include those keywords in the title.

If your tracker permissions are elevated, assign the bug to yourself by setting the Assignee field. If your tracker permissions have not been elevated, just add a comment with a short message that says “I am working on this issue”.

Ceph Workflow Overview

Three repositories are involved in the Ceph workflow. They are:

  1. The upstream repository (ceph/ceph)

  2. Your fork of the upstream repository (your_github_id/ceph)

  3. Your local working copy of the repository (on your workstation)

The procedure for making changes to the Ceph repository is as follows:

  1. Configure your local environment

    1. Create a fork of the “upstream Ceph” repository.

    2. Clone the fork to your local filesystem.

  2. Fix the bug

    1. Synchronize local master with upstream master.

    2. Create a bugfix branch in your local working copy.

    3. Make alterations to the local working copy of the repository in your local filesystem.

    4. Push the changes in your local working copy to your fork.

  3. Create a Pull Request to push the change upstream

    1. Create a Pull Request that asks for your changes to be added into the “upstream Ceph” repository.

Preparing Your Local Working Copy of the Ceph Repository

The procedures in this section, “Preparing Your Local Working Copy of the Ceph Repository”, must be followed only when you are first setting up your local environment. If this is your first time working with the Ceph project, then these commands are necessary and are the first commands that you should run.

Creating a Fork of the Ceph Repository

See the GitHub documentation for detailed instructions on forking. In short, if your GitHub username is “mygithubaccount”, your fork of the upstream repo will appear at https://github.com/mygithubaccount/ceph.

Cloning Your Fork

After you have created your fork, clone it by running the following command:

$ git clone https://github.com/mygithubaccount/ceph

You must fork the Ceph repository before you clone it. If you fail to fork, you cannot open a GitHub pull request.

For more information on using GitHub, refer to GitHub Help.

Configuring Your Local Environment

The commands in this section configure your local git environment so that it generates “Signed-off-by:” tags. They also set up your local environment so that it can stay synchronized with the upstream repository.

These commands are necessary only during the initial setup of your local working copy. Another way to say that is “These commands are necessary only the first time that you are working with the Ceph repository. They are, however, unavoidable, and if you fail to run them then you will not be able to work on the Ceph repository.”.

  1. Configure your local git environment with your name and email address.

    git config user.name "FIRST_NAME LAST_NAME"
    git config user.email "MY_NAME@example.com"
    
  2. Add the upstream repo as a “remote” and fetch it:

    git remote add ceph https://github.com/ceph/ceph.git
    git fetch ceph
    

    These commands fetch all the branches and commits from ceph/ceph.git to the local git repo as remotes/ceph/$BRANCH_NAME and can be referenced as ceph/$BRANCH_NAME in local git commands.

Fixing the Bug

Synchronizing Local Master with Upstream Master

In your local git environment, there is a copy of the master branch in remotes/origin/master. This is called “local master”. This copy of the master branch (https://github.com/your_github_id/ceph.git) is “frozen in time” at the moment that you cloned it, but the upstream repo (https://github.com/ceph/ceph.git, typically abbreviated to ceph/ceph.git) that it was forked from is not frozen in time: the upstream repo is still being updated by other contributors.

Because upstream master is continually receiving updates from other contributors, your fork will drift farther and farther from the state of the upstream repo when you cloned it.

You must keep your fork’s master branch synchronized with upstream master in order to reduce drift between your fork’s master branch and the upstream master branch.

Here are the commands for keeping your fork synchronized with the upstream repository:

$ git push -u origin master

Bugfix branch

Next, create a branch for the bugfix:

Creating a Bugfix branch

$ git checkout master $ git checkout -b fix_1 $ git push -u origin fix_1

This creates a fix_1 branch locally and in our GitHub fork. At this point, the fix_1 branch is identical to the master branch, but not for long! You are now ready to modify the code.

Fix bug locally

The first command (git checkout master) makes sure that the bugfix branch “fix_1” is created from the most recent state of the master branch of the upstream repository.

The second command (git checkout -b fix_1) creates a “bugfix branch” called “fix_1” in your local working copy of the repository. The changes that you make in order to fix the bug will be commited to this branch.

The third command (git push -u origin fix_1) pushes the bugfix branch from your local working repository to your fork of the upstream repository.

Fixing the bug in the local working copy

  1. Updating the tracker

    In the Ceph issue tracker, change the status of the tracker issue to “In progress”. This communicates to other Ceph contributors that you have begun working on a fix, which helps to avoid duplication of effort. If you don’t have permission to change that field, your comment that you are working on the issue is sufficient.

  2. Fixing the bug itself

    This guide cannot tell you how to fix the bug that you have chosen to fix. This guide assumes that you know what required improvement, and that you know what to do to provide that improvement.

    It might be that your fix is simple and requires only minimal testing. But that’s unlikely. It is more likely that the process of fixing your bug will be iterative and will involve trial, error, skill, and patience.

    For a detailed discussion of the tools available for validating bugfixes, see the chapters on testing.

Pushing the Fix to Your Fork

You have finished work on the bugfix. You have tested the bugfix, and you believe that it works.

  1. Commit the changes to your local working copy.

    Commit the changes to the fix_1 branch of your local working copy by using the --signoff option (here represented as the s portion of the -as flag):

    git commit -as
    
  2. Push the changes to your fork:

    Push the changes from the fix_1 branch of your local working copy to the fix_1 branch of your fork of the upstream repository:

    git push origin fix_1
    

    Note

    In the command git push origin fix_1, origin is the name of your fork of the upstream Ceph repository, and can be thought of as a nickname for git@github.com:username/ceph.git, where username is your GitHub username.

    It is possible that origin is not the name of your fork. Discover the name of your fork by running git remote -v, as shown here:

      $ git remote -v
      ceph   https://github.com/ceph/ceph.git (fetch)
      ceph   https://github.com/ceph/ceph.git (push)
      origin git@github.com:username/ceph.git (fetch)
      origin git@github.com:username/ceph.git (push)
    
    The line "origin git@github.com:username/ceph.git (fetch)" and the line
    "origin git@github.com:username/ceph.git (push)" provide the information
    that "origin" is the name of your fork of the Ceph repository.
    

The next step is to open a GitHub pull request. The purpose of this step is to make your bugfix available to the community of Ceph developers. They will review it and may do additional testing on it.

After you have pushed the bugfix to your fork, open a GitHub pull request (PR). This makes your bugfix visible to the community of Ceph contributors. They will review it. They may perform additional testing on your bugfix, and they might request changes to the bugfix.

Be prepared to receive suggestions and constructive criticism in the form of comments within the PR.

If you don’t know how to create and manage pull requests, read this GitHub pull request tutorial.

To learn what constitutes a “good” pull request, see the Git Commit Good Practice article at the OpenStack Project Wiki.

See also our own Submitting Patches document.

After your pull request (PR) has been opened, update the issue tracker by adding a comment directing other contributors to your PR. The comment can be as simple as this:

*PR*: https://github.com/ceph/ceph/pull/$NUMBER_OF_YOUR_PULL_REQUEST

Automated PR validation

When you create or update your PR, the Ceph project’s Continuous Integration (CI) infrastructure automatically tests it. At the time of this writing (May 2022), the automated CI testing included many tests. These five are among them:

  1. a test to check that the commits are properly signed (see Submitting Patches):

  2. a test to check that the documentation builds

  3. a test to check that the submodules are unmodified

  4. a test to check that the API is in order

  5. a make check test

Additional tests may be run depending on which files your PR modifies.

The make check test builds the PR and runs it through a battery of tests. These tests run on servers that are operated by the Ceph Continuous Integration (CI) team. When the tests have completed their run, the result is shown on GitHub in the pull request itself.

Test your modifications before you open a PR. Refer to the chapters on testing for details.

Notes on PR make check test

The GitHub make check test is driven by a Jenkins instance.

Jenkins merges your PR branch into the latest version of the base branch before it starts any tests. This means that you don’t have to rebase the PR in order to pick up any fixes.

You can trigger PR tests at any time by adding a comment to the PR - the comment should contain the string “test this please”. Since a human who is subscribed to the PR might interpret that as a request for him or her to test the PR, you must address Jenkins directly. For example, write “jenkins retest this please”. If you need to run only one of the tests, you can request it with a command like “jenkins test signed”. A list of these requests is automatically added to the end of each new PR’s description, so check there to find the single test you need.

If there is a build failure and you aren’t sure what caused it, check the make check log. To access the make check log, click the “details” (next to the make check test in the PR) link to enter the Jenkins web GUI. Then click “Console Output” (on the left).

Jenkins is configured to search logs for strings that are known to have been associated with make check failures in the past. However, there is no guarantee that these known strings are associated with any given make check failure. You’ll have to read through the log to determine the cause of your specific failure.

Integration tests AKA ceph-qa-suite

Since Ceph is a complex beast, it may also be necessary to test your fix to see how it behaves on real clusters running either on real or virtual hardware. Tests designed for this purpose live in the ceph/qa sub-directory and are run via the teuthology framework.

The Ceph community has access to the Sepia lab where integration tests can be run on real hardware. Other developers may add tags like “needs-qa” to your PR. This allows PRs that need testing to be merged into a single branch and tested all at the same time. Since teuthology suites can take hours (even days in some cases) to run, this can save a lot of time.

To request access to the Sepia lab, start here.

Integration testing is discussed in more detail in the integration tests chapter.

Code review

Once your bugfix has been thoroughly tested, or even during this process, it will be subjected to code review by other developers. This typically takes the form of correspondence in the PR itself, but can be supplemented by discussions on IRC and the Mailing list.

Amending your PR

While your PR is going through testing and Code Review, you can modify it at any time by editing files in your local branch.

After the changes are committed locally (to the fix_1 branch in our example), they need to be pushed to GitHub so they appear in the PR.

Modifying the PR is done by adding commits to the fix_1 branch upon which it is based, often followed by rebasing to modify the branch’s git history. See this tutorial for a good introduction to rebasing. When you are done with your modifications, you will need to force push your branch with:

$ git push --force origin fix_1

Merge

The bugfixing process culminates when one of the project leads decides to merge your PR.

When this happens, it is a signal for you (or the lead who merged the PR) to change the Ceph issue tracker status to “Resolved”. Some issues may be flagged for backporting, in which case the status should be changed to “Pending Backport” (see the Backporting chapter for details).