Skip to content

Latest commit

 

History

History
272 lines (201 loc) · 17.7 KB

CONTRIBUTING.md

File metadata and controls

272 lines (201 loc) · 17.7 KB
Raw

OpenEBS Umbrella Contributing Guidelines

Important

OpenEBS is an "umbrella" project, composed as a federation of individual sub projects (repositories). The umbrella project, every sub project, repository/repo and file in the OpenEBS organization adopts and follows the same set of umbrella policies in the OpenEBS Community repo. This is the Umbrella Contributing Guidelines.


There are many exciting ways you can contribute to OpenEBS ❤️

  • We are a large GitHub project that consists of many active members operating globally, across all time zones, 24 x 7 x 365.
  • There are many different methods, processes, forums, and project tools to use when contributing.
  • This means that contributing can be a little scary at times (like many large CNCF Open source GitHub hosted projects).
  • If you are unsure or afraid of anything, just ask via Slack, Discussion, or Issue. // It’s simple.

This document will help guide your workflow and experience to provide you with the best and most efficient interaction possible.


Ask a question ❓

Try our Slack channel First
If you have questions about using OpenEBS, please use the CNCF Kubernetes OpenEBS slack channel, it is open for anyone to ask a question

Issues ‼️

Issues are a standard way of working and contributing to GitHub projects. GitHub Issues are the 2nd most common way after Slack that users interact and contribute to the project. Working with Issues requires you to make a few simple decisions.

  • Is my issue more of a discussion topic?
  • Does my Issue relate to a Product?
  • Is it an issue that spans Horizontally across all products?
  • Is my issue related to technology, bugs, product, code?
  • Is my issue more relevant to roadmap, strategy, docs (not technology, bugs, product, code)?
After this, you're ready to create an Issue and know where to create it.

Note

Issues come in 3 basic flavors

  1. Organizational issues that aren't specifically related to individual products, technology, or code
  2. Issues that span multiple products
  3. Issues focused on 1 specific Product
    • For this type of issue, create your issue in the Issue tab of the correct project/product repo
    • View the list of our product components here

Reporting a product issue

If you have a problem using OpenEBS, first check the troubleshooting guide, you can also ask a question in the CNCF Kubernetes OpenEBS slack channel.

Note

  • Our support and engineering teams primarily focus their support on the OpenEBS STANDARD (OSS) parent project.
  • Questions & issues relating to the Legacy Archived, Deprecated & Migrated OpenEBS projects, repos, code & dependencies are not the focus of the parent OSS project; and may be provided on a best effort basis by the team.
  • The OpenEBS slack community provides most of the support for the Legacy Archived, Deprecated & Migrated OpenEBS projects.
  • please Do Not post Deprecated & Archived project Discussions, Issues or PR's into the OpenEBS STANDARD (OSS) parent project.

If you have an issue not solved by the troubleshooting guide or by asking a question in Slack, first check the GitHub issue list to see if the issue is already recorded, then add a new Issue in the correct repo issue management section.


Multiple products

Our project spans multiple product components. We don't use a single centralized GitHub issue tracker for all product issues. We like to group product issues tightly into their specific product Issue trackers. (Please try to do this). Currently OpenEBS Unifies 5 main Storage engines...

ID Data-Engines Where to create your issues
Replicated PV Replicated storage and data volumes
1 Replicated PV Mayastor Create your Issues here
 
Local PV Non-replicated node local storage and volumes
2. LocalPV-HostPath Create your Issues here
3. LocalPV-ZFS Create your Issues here
4. LocalPV-LVM Create your Issues here
5. LocalPV-Rawfile Create your Issues here


When creating a new issue, please use this simple template

  • Summary of the issue

  • Expected result and the observed result

  • Errors and log messages

  • Setup details, and steps for reproducing the issue, so a reviewer can easily replicate the issue, and confirm the fix

Report a documentation issue

We use the same GitHub issue tracker for documentation issues, with a label for documentation:
▶️ OpenEBS Documentation Issues

  • Issues are triaged and prioritized in the regular community meeting

Report a security issue or vulnerability

Important

Because of the sensitive nature of security issues (reporting a security issue also alerts bad-actors of the security issue), we ask you to report these by emailing the umbrella project maintainers.
▶️   Email security issue to OpenEBS maintainers

After addressing any security issue, they will be discussed in the regular community meeting


Contribute to Source Code and Bug Fixes

We encourage users to engage in and contribute code. Doing this can be complex and requires following the GitHub methodology that we subscribe to as a member of CNCF. In a nutshell, the GitHub methodology is:

  • Discussion/Proposal ⏩ Create Issue ⏩ PR draft + code ⏩ PR Review(s) + code changes 🔄 PR approve ⏩ DCO Sign-off 🔀 Merge

  • When creating your PR, please use appropriate tags to identify your source code. For a list of tags that could be used, see this.
  • For contributing to K8s demo, please refer to this document.
  • For understanding how OpenEBS works with K8s, refer to this document
  • For contributing to K8s OpenEBS Provisioner, refer to this document.
  • For code structuring and guidelines, refer to this document
  • Feel free to discuss developer topics in our OpenEBS DEV Kubernetes Slack Channel


Solve Existing Issues

Head over to Parent org issues to find issues where help is needed from contributors, or check the issues section of the product component that you are interested in.

See our list of labels guide to help you find issues that you can solve faster.

A person looking to contribute can take up an issue by claiming it as a comment/assign their GitHub ID to it. In case there is no PR or update in progress for a week on the said issue, then the issue reopens for anyone to take up again. We need to consider high priority issues/regressions where response time must be a day or so. You can discuss the issue in our OpenEBS developer Kubernetes Slack Channel:
▶️ OpenEBS DEV Kubernetes Slack Channel

Sponsor a new feature or enhancement

New enhancements are referred to as OpenEBS Enhancement Proposals (OEPs). Anyone can sponsor a new OEP. Here is the process:

  1. Sponsor creates a GitHub issue to track the OEP as a whole.
  2. Sponsor creates a GitHub (pull request) PR with a provisional OEP, with its oep-number set to the tracking GitHub issue number.
  3. Discussions are encouraged, either on the OEP related issues or the PR.
  4. OEPs are reviewed in the maintainer and community meetings.
  5. The OEP is submitted for approval by modifying its status to implementable via a PR (this may be the original PR for simple enhancements).
  6. The community may vote on the OEP, maintainers have binding votes.

Sign your work


Important

Our Organization enforces Developer Certificate of Origin (DCO) on all Pull Requests, as an additional safeguard for the OpenEBS project. This requires all commit messages to contain the Signed-off-by line, with an email address that matches the commit author name.

  • This is a well established and widely used mechanism
  • DCO ensures contributors have confirmed their right to license their contribution under the project's license.
  • Please read developer-certificate-of-origin release statement to understand what you are consenting to and agreeing to adhere to when you create a commit and a PR.
  • ALL PR's will automatically have their status set to FAILED if any commits in a Pull Request do not contain a valid Signed-off-by line.

You must certify that your commits and PR's are your own work and authorized by you by adding a line to every git commit message. Any PR with Commits that Do Not have DCO Signoff will not be accepted:

Examples of how to DCO Sign-off your work...


Example of manual DCO signoff commit signature message:
Signed-off-by: Random J Developer <random@developer.example.org>

Example of automated git cli command:
git commit -s -m "Sign off details and message. Does not include DCO signature line"

NOTE: the cli -s flag will auto add your DCO sign-off signature as a extra line in your commit message
if you have setup you git Global config correctly.

ℹ️ INFO:
🚫 When using the GitHub Web App, you cannot auto DCO sign-off your commits. Your DCO signature line must be manually added each time, in each commit message. This is by design and enforced by the GitHub WebApp.
✅ When using GitHub Desktop App, you can generate automatic DCO sign-off commits if your underlying git cli config is setup correctly.


The generally accepted GitHub DCO policy requires that all committing users must provide their real name in their DCO signature message (sorry, no pseudonyms or anonymous contributions).

  • If you set your user.name and user.email git configs, you can DCO sign-off your commits automatically with git commit -s.
  • You can also use git aliases like: git config --global alias.ci 'commit -s'. Now you can commit with git ci and the commit will be signed.

Some of the repos use the GitHub Integration Merge BOT App called BORS-NG as a CI Pipeline automation workflow front tool.
Some of the BORS commands are as follows:

Syntax Description
bors r+ Run the test suite and push to master if it passes. Short for "reviewed: looks good."
bors merge Equivalent to bors r+.
bors r=[list] Same as r+, but the "reviewer" in the commit log will be recorded as the user(s) given as the argument.
bors merge=[list] Equivalent to bors r=[list]
bors r- Cancel an r+, r=, merge, or merge=
bors merge- Equivalent to bors r-
bors try Run the test suite without pushing to master.
bors try- Cancel a try
bors delegate+
bors d+		 Allow the pull request author to r+ their changes.
bors delegate=[list]
bors d=[list]		 Allow the listed users to r+ this pull request's changes.
bors ping Check if bors is up. If it is, it will comment with pong.
bors retry Run the previous command a second time.
bors p=[priority] Set the priority of the current pull request. Pull requests with different priority are never batched together. The pull request with the bigger priority number goes first.
bors r+ p=[priority] Set the priority, run the test suite, and push to master (shorthand for doing p= and r+ one after the other).
bors merge p=[priority] Equivalent to bors r+ p=[priority]


We are evaluating bringing BORS to all repos or alternatively switch to the new GitHub Merge queues.

Monthly Community Meetings

Other ways to keep in touch

Email

You can email the maintainers at any time:
▶️ CNCF Mailing List
▶️ Google Groups

Social Media

Social media links
▶️ TwitterX
▶️ LinkedIn
▶️ Youtube


A good contributor workflow

The following table is a guide to help you decide which channel, method and mechanism to use when contributing.
- In most cases, consider starting at the top (post a Slack channel question)
- and then work your way down, Discussion, Issue, Projects
- Ending at a Pull Request; the most complex community contribution/interaction type.
Priority Type Description
1. Global Slack CNCF provides the OpenEBS project with a global Slack support Channel.
All users and community members are welcome to engage all project members via the Slack channel.
2. Org Discussions Our GitHub Discussions are enabled at the Parent OpenEBS Org level and aggregate all project/repo discussions into ONE Unified Umbrella scope for the best community discussion experience.
Individual projects/repos Do Not have repos level GitHub discussions enabled.
3. Org Issues Non-Product Issues not related to technology, bugs, or product code are managed in the top-level Org repo.
You can create/submit ORG level issues as per the normal GitHub methodology & rules. Consider doing this for issues that are horizontal across all projects/repos/products.
4. Product Issues Product Issues are managed for each individual repo.
You can create/submit issues as per the normal GitHub methodology & rules. Please choose carefully if you are engaging the team in a General Discussion or need help with a very specific Product Issue. This will help you get the best community experience. Please create your interactions in the correct GitHub forum/tool.
5 Our Projects We manage some major initiatives via the GitHub Projects tool.
Users and community members are welcome to contribute, comment and participate in Public projects.
Projects are enabled and managed on a per-repo basis. Few sub-projects may have their specific CONTRIBUTING guides, please refer them as well.
6. Repo PR's You may engage and contribute via the standard GitHub PR (Pull Request) methodology.
PR's are low-level repo/product/component focused engineering process used to manage low-level changes to code.
For the best community experience, Do Not create PR's for Discussions, Issues or support tickets. (such items may be migrated to the appropriate forum/tool and could become stale and/or be closed without action/comment.
7. OEP's You may propose features via an OpenEBS Enhancement Proposal (OEP) through a GitHub PR (Pull Request) methodology.
For more information please refer to the OEP process.