-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add meeting details to README Update contributing Add ROADMAP link Signed-off-by: Tiago Castro <[email protected]>
- Loading branch information
1 parent
51ed486
commit 656c8d4
Showing
5 changed files
with
106 additions
and
55 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,35 +1,37 @@ | ||
| # 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. | ||
| <BR> | ||
| There are many exciting ways you can contribute to OpenEBS ❤️ <BR> | ||
|
|
||
| - 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). <BR> | ||
| - 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](#a-good-contributor-workflow) and experience to provide you with the best and most efficient interaction possible. | ||
|
|
||
|
|
||
| <BR> | ||
|
|
||
|
|
||
| ## Ask a question :question: | ||
|
|
||
| | [<img src="/images/slack_icon_small.png" width="100">](https://kubernetes.slack.com/messages/openebs) | **Try our Slack channel First** <BR>If you have questions about using OpenEBS, please use the CNCF Kubernetes **OpenEBS slack channel**, it is open for [anyone to ask a question](https://kubernetes.slack.com/messages/openebs/) <BR> | | ||
| | :--- | :--- | | ||
|
|
||
| <BR> | ||
|
|
||
| ## Issues :bangbang: | ||
|
|
||
| # Issues :bangbang: | ||
| ```Issues``` are a standard way of working and contributing to GitHub projects. GitHub Issues are the **2nd most** common way [after Slack](https://kubernetes.slack.com/messages/openebs) 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)? | ||
|
|
||
| ```ruby | ||
| After this, you're ready to create an Issue and know where to create it. | ||
| ``` | ||
|
|
@@ -38,6 +40,7 @@ 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 | ||
| > - For this type of issue, [create your issue here](https://github.com/openebs/openebs/issues) | ||
| > - You might also consider creating a discussion in the [parent org discussions area](https://github.com/orgs/openebs/discussions) | ||
|
|
@@ -50,21 +53,21 @@ After this, you're ready to create an Issue and know where to create it. | |
|
|
||
| ### Reporting a product issue | ||
|
|
||
|
|
||
| If you have a problem using OpenEBS, first check the [troubleshooting guide](https://openebs.io/docs/troubleshooting), 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](https://github.com/openebs). <BR> | ||
| > - Questions & issues relating to the [Legacy Archived, Deprecated & Migrated OpenEBS projects](https://github.com/openebs-archive), repos, code & dependencies are **not the focus** of the parent OSS project; and may be provided on a ```best effort``` basis by the team. <BR> | ||
| > - The OpenEBS slack community provides most of the support for the **Legacy** ```Archived```, ```Deprecated``` & ```Migrated``` OpenEBS projects. | ||
| > - please **```Do Not```** post [```Deprecated & Archived project```](https://github.com/openebs-archive) 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. | ||
| <BR> | ||
| ### 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 | | ||
|
|
@@ -77,23 +80,28 @@ Our project spans multiple product components. We ```don't``` use a single centr | |
| | 3. | [LocalPV-ZFS](https://github.com/openebs/zfs-localpv) | [Create your Issues here](https://github.com/openebs/zfs-localpv/issues) | | ||
| | 4. | [LocalPV-LVM](https://github.com/openebs/lvm-localpv) | [Create your Issues here](https://github.com/openebs/lvm-localpv/issues) | | ||
| | 5. | [LocalPV-Rawfile](https://github.com/openebs/rawfile-localpv) | [Create your Issues here](https://github.com/openebs/rawfile-localpv/issues) | | ||
| <BR> | ||
| <BR> | ||
| ### 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 | ||
| ### 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: | ||
| <BR> | ||
| :arrow_forward: [OpenEBS Documentation Issues](https://github.com/openebs/openebs/labels/documentation%2Fdevel) | ||
| <BR> | ||
| - Issues are triaged and prioritized in the regular community meeting | ||
| <BR> | ||
|
|
@@ -111,6 +119,7 @@ We use the same GitHub issue tracker for documentation issues, with a label for | |
| ## 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: <BR> | ||
| - Discussion/Proposal :fast_forward: Create Issue :fast_forward: PR draft + code :fast_forward: PR Review(s) + code changes :arrows_counterclockwise: PR approve :fast_forward: DCO Sign-off :twisted_rightwards_arrows: Merge <BR> | ||
| <BR> | ||
|
|
@@ -125,6 +134,7 @@ We encourage users to engage in and contribute code. Doing this can be complex a | |
| <BR> | ||
| ## Solve Existing Issues | ||
| Head over to [Parent org issues](https://github.com/openebs/openebs/issues) to find issues where help is needed from contributors, or check the issues section of the [product component](./CONTRIBUTING.md#multiple-products) that you are interested in. | ||
| See our [list of labels guide](https://github.com/openebs/openebs/blob/main/contribute/labels-of-issues.md) to help you find issues that you can solve faster. | ||
|
|
@@ -135,6 +145,7 @@ A person looking to contribute can take up an issue by claiming it as a comment/ | |
| <BR> | ||
| ## 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: | ||
|
|
@@ -147,8 +158,8 @@ Anyone can sponsor a new OEP. Here is the process: | |
| --- | ||
| ### Sign your work | ||
| <BR> | ||
| > [!Important] | ||
|
|
@@ -159,34 +170,37 @@ Anyone can sponsor a new OEP. Here is the process: | |
| > - Please read [developer-certificate-of-origin](https://github.com/openebs/openebs/blob/main/contribute/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. <BR> | ||
| > - 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:<BR> | ||
| <BR> | ||
| ### Examples of how to DCO Sign-off your work...<BR> | ||
| <BR> | ||
| > Example of manual DCO signoff commit signature message: <BR> | ||
| > ```Signed-off-by: Random J Developer <random@developer.example.org>``` | ||
| > | ||
| > Example of automated git cli command: <BR> | ||
| > ```git commit -s -m "Sign off details and message. Does not include DCO signature line"``` | ||
| > | ||
| > ```ruby | ||
| > 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. | ||
| > ``` | ||
| > | ||
| > :information_source: **```INFO```:** <BR> | ||
| > :no_entry_sign: 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. <BR> | ||
| > :white_check_mark: When using GitHub Desktop App, you can generate automatic DCO sign-off commits if your underlying git cli config is setup correctly. <BR> | ||
| <BR> | ||
| 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). <BR> | ||
| - If you set your ```user.name``` and ```user.email``` git configs, you can DCO sign-off your commits automatically with ```git commit -s```. <BR> | ||
| - You can also use git [aliases](https://git-scm.com/book/en/v2/Git-Basics-Git-Aliases) like: ``` git config --global alias.ci 'commit -s' ```. Now you can commit with git ci and the commit will be signed. <BR> | ||
| <BR> | ||
| --- | ||
| We use the GitHub Integration <kbd>Merge BOT</kbd> App called ``` BORS-NG ``` as a CI Pipeline automation workflow front tool. <BR> | ||
| Some of the repos use the GitHub Integration <kbd>Merge BOT</kbd> App called ``` BORS-NG ``` as a CI Pipeline automation workflow front tool. <BR> | ||
| Some of the BORS commands are as follows: | ||
| | Syntax | Description | ||
|
|
@@ -207,43 +221,39 @@ Some of the BORS commands are as follows: | |
| | 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](https://github.blog/news-insights/product-news/github-merge-queue-is-generally-available/). | ||
| ## Regular Community Meeting | ||
| --- | ||
| OpenEBS hosts a bi-weekly (fortnightly) community meeting on Tuesday 7:00 am Americas/Los Angeles time, using the [CNCF's community event platform](https://community.cncf.io/openebs-community/). Please register for the event, prior to the meeting. You'd have to register for the meeting before the actual meeting time. | ||
| <BR> | ||
| :arrow_forward: [Add agenda items for the next meeting](https://hackmd.io/tRmnyg9AQPShxFAXOyFpSA?edit) | ||
| <BR> | ||
| :arrow_forward: [Review minutes from previous meetings](https://hackmd.io/tRmnyg9AQPShxFAXOyFpSA?edit) | ||
| <BR> | ||
| ## [Monthly Community Meetings](./README.md#monthly-community-meetings) | ||
| ## Other ways to keep in touch | ||
| You can email the maintainers at any time: | ||
| <BR> | ||
| :arrow_forward: [Email OpenEBS maintainers](mailto:[email protected]) | ||
| ### Mailing List | ||
| OpenEBS announces new features and enhancements to a CNCF email group | ||
| :arrow_forward: [CNCF Mailing List](mailto:[email protected]) | ||
| <BR> | ||
| :arrow_forward: [CNCF OpenEBS announcements](https://lists.cncf.io/g/cncf-openebs-announcements) | ||
| :arrow_forward: [Google Groups](mailto:openebs-[email protected]) | ||
| ### Social Media | ||
| Social media links | ||
| <BR> | ||
| :arrow_forward: [TwitterX OpenEBS page](https://twitter.com/openebs/) | ||
| :arrow_forward: [TwitterX](https://twitter.com/openebs/) | ||
| <BR> | ||
| :arrow_forward: [LinkedIn OpenEBS page](https://www.linkedin.com/company/openebs/) | ||
| :arrow_forward: [LinkedIn](https://www.linkedin.com/company/openebs/) | ||
| <BR> | ||
| :arrow_forward: [Youtube](https://www.youtube.com/@openebscommunity6021) | ||
| <BR> | ||
| --- | ||
| ## A good contributor workflow | ||
| ```ruby | ||
| 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) | ||
|
|
@@ -253,9 +263,10 @@ The following table is a guide to help you decide which channel, method and mech | |
|
|
||
| | Priority | Type | Description | | ||
| | :---: | :--- | :--- | | ||
| | 1. | Global Slack | CNCF provides the **OpenEBS project** with a [```global Slack support Channel```](https://kubernetes.slack.com/messages/openebs/). All users and community members are welcome to engage all project members via the Slack channel. | | ||
| | 2. | [Org Discussions](https://github.com/orgs/openebs/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](https://github.com/openebs/openebs/issues) | Non-Product Issues not related to technology, bugs, or product code are managed in the top-level [```Org repo```](https://github.com/openebs/openebs). 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](https://github.com/openebs/openebs/issues). | | ||
| | 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```](https://github.com/orgs/openebs/discussions) 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. | | ||
| | 1. | Global Slack | CNCF provides the **OpenEBS project** with a [```global Slack support Channel```](https://kubernetes.slack.com/messages/openebs/).<BR> All users and community members are welcome to engage all project members via the Slack channel. | | ||
| | 2. | [Org Discussions](https://github.com/orgs/openebs/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.<BR> Individual projects/repos ```Do Not``` have repos level GitHub discussions enabled. | | ||
| | 3. | [Org Issues](https://github.com/openebs/openebs/issues) | Non-Product Issues not related to technology, bugs, or product code are managed in the top-level [```Org repo```](https://github.com/openebs/openebs).<BR> 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](https://github.com/openebs/openebs/issues). | | ||
| | 4. | Product Issues | Product Issues are managed for each ```individual repo```.<BR> 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```](https://github.com/orgs/openebs/discussions) 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**.<BR> Users and community members are welcome to contribute, comment and participate in Public projects.<BR> 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.<BR> PR's are low-level repo/product/component focused engineering process used to manage **```low-level changes to code```**.<BR> 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.<BR> For more information please refer to the [OEP process](https://github.com/openebs/openebs/blob/main/designs/oep-process.md). | | ||
Oops, something went wrong.