Skip to content

Contributing

Jump to bottom
Srishti Thakkar edited this page Jun 17, 2021 · 4 revisions

Table of contents

Introduction

We really encourage everyone to contribute and to make our system better. We ask contributors, however, to read this guide carefully and follow the established guidelines. We don't claim this is perfect, so these guidelines will change over time as we feel that it is not complete or appropriate. Suggestions on how to improve this guide for contributors are also welcome.

Issues and Pull requests

To produce a pull request, follow these steps:

  • Create an issue: Create an issue and describe what you are trying to solve. It doesn't matter whether it is a new feature, a bug fix, or an improvement. All pull requests need to be associated to an issue. See more here: Creating an issue

  • Issue branch: Create a new branch on your fork of the repository. Typically, you need to branch off master, but there could be exceptions. To branch off master, use git checkout master; git checkout -b <new-branch-name>.

  • Push the changes: To be able to create a pull request, push the changes to origin: git push --set-upstream origin <new-branch-name>. I'm assuming that origin is your personal repo, e.g., SrishT/charts.git.

  • Branch name: Use the following pattern to create your new branch name: issue-number-description, e.g., issue-1023-reformat-testutils.

  • Create a pull request: Github gives you the option of creating a pull request. Give it a title following this format [component-name] Issue ###: Description, e.g., [bookkeeper-operator] Issue 1023: Updating CRD. Follow the guidelines in the description and try to provide as much information as possible to help the reviewer understand what is being addressed. It is important that you try to do a good job with the description to make the job of the code reviewer easier. A good description not only reduces review time, but also reduces the probability of a misunderstanding with the pull request.

  • Checks: The user should ensure that the following checks are adhered to before raising a pull request

    1. Must pass DCO check
    2. Must follow charts best practices
    3. The chart version should follow semver principles

Another important point to consider is how to keep up with changes against the base the branch (the one your pull request is comparing against). Let's assume that the base branch is master. To make sure that your changes reflect the recent commits, we recommend that you rebase frequently. The command we suggest you use is:

git pull --rebase upstream master
git push --force origin <pr-branch-name>

Very important: in the above, I'm assuming that:

  • upstream is pravega/charts.git
  • origin is youraccount/charts.git

The rebase might introduce conflicts, so you better do it frequently to avoid outrageous sessions of conflict resolving.

Creating an issue

When creating an issue, there are two important parts: title and description. The title should be succinct, but give a good idea of what the issue is about. Try to add all important keywords to make it clear to the reader. For example, if the issue is about changing the log level of some messages in the segment store, then instead of saying "Log level" say "Change log level in the segment store". The suggested way includes both the goal where in the code we are supposed to do it.

For the description, there three parts:

  • Problem description: Describe what it is that we need to change. If it is a bug, describe the observed symptoms. If it is a new feature, describe it is supposed to be with as much detail as possible.

  • Problem location: This part refers to which component (and preferably where in that component) we are supposed to make changes. For example, if it is bug in the pravega operator charts, then in this part say at least "Pravega Operator Charts". If you know more about it, then please add it. For example, if you that there is an issue with a specific file, then specify it in this part.

  • Suggestion for an improvement: This section is designed to let you give a suggestion for how to fix the bug described in the Problem description or how to implement the feature described in that same section. Please make an effort to separate between problem statement (Problem Description section) and solution (Suggestion for an improvement).

We next discuss how to create a pull request.

Creating a pull request

When creating a pull request, there are also two important parts: title and description. The title can be the same as the one of the issue, but it must be prefixed with the name of the component followed by the issue number, for e.g.:

[bookkeeper-operator] Issue 24: Adding support for custom annotations

The description has four parts:

  • Changelog description: This section should be the two or three main points about this PR. A detailed description should be left for the What the code does section. The two or three points here should be used by a committer for the merge log.

  • Purpose of the change: Say whether this closes an issue or perhaps is a subtask of an issue. This section should link the PR to at least one issue.

  • What the code does: Use this section to freely describe the changes in this PR. Make sure to give as much detail as possible to help a reviewer to do a better job understanding your changes.

  • How to verify it: For most of the PRs, the answer here will be trivial: the build must pass, system tests must pass, visual inspection, etc. This section becomes more important when the way to reproduce the issue the PR is resolving is non-trivial, like running some specific command or workload generator.

  • Checklist: This contains a few points as checklists, which is meant to help both the committer as well as the reviewer. It serves as a final reminder to the committer to perform these checks before creating the pull request. At the same time, it also helps the reviewer to understand whether these checks have been performed by the committer or not. The points covered in this section include

    1. Checking that the title of the PR follows the naming guidelines
    2. Ensuring that the output of helm lint command has been verified
    3. Ensuring whether the changes in the PR have been tested manually

Signing your commits

The Developer Certificate of Origin (DCO) is a lightweight way for contributors to certify that they wrote or otherwise have the right to submit the code they are contributing to the project. Contributors must sign-off that they adhere to these requirements by adding a Signed-off-by line to commit messages.

Using the git command line

Use either --signoff or -s with the commit command. See this document for an example.

Make sure you have your user name and e-mail set. The --signoff | -s option will use the configured user name and e-mail, so it is important to configure it before the first time you commit. Check the following references:

Using InteliJ

Intellij has a checkbox in the top-right corner of the Commit Dialog named Sign-off commit. Make sure you also enter your correct email address in the Author box right above it.

Using Eclipse

The EGit plugin supports signing commits. See their instructions. To enable it by default, in Window -> Preferences -> Team -> Git -> Commiting under "Footers" check "Insert Signed-off-by".

Using Sourcetree

When you commit right above where you enter the commit message on the far right, the "Commit options..." pull down has a "Sign Off" option. Selecting it will enable it for the commit. There is no configuration to force it always to be on.

I forgot to sign-off a commit in my pull request

There are a few ways to fix this, one such a way is to squash commits into one that is signed off. Use a command like:

git rebase --signoff -i <after-this-commit>

where <after-this-commit> corresponds to the last commit you want to maintain as is and follow the instructions here.

Clone this wiki locally