diff --git a/.github/weekly-digest.yml b/.github/weekly-digest.yml deleted file mode 100644 index 1300345..0000000 --- a/.github/weekly-digest.yml +++ /dev/null @@ -1,9 +0,0 @@ -# Configuration for weekly-digest - https://github.com/apps/weekly-digest -# Added by: Dave Brace @orville-wright on: 16 June 2024 -# -publishDay: sun -canPublishIssues: true -canPublishPullRequests: true -canPublishContributors: true -canPublishStargazers: true -canPublishCommits: true diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ea5158c..6f6d0d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,277 +1,103 @@ # 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. -
+> OpenEBS is an "umbrella project". Every sub-project, repository and file in the OpenEBS organization adopts and follows the policies found in the Community repo umbrella project files. -There are many exciting ways you can contribute to OpenEBS ❤️
+# Contributing 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. +We welcome contributions to OpenEBS! Thank you for taking the time to help improve the project. This guide outlines our approach to contributions and helps you get started. -This document will help guide [your workflow](#a-good-contributor-workflow) and experience to provide you with the best and most efficient interaction possible. - -
- -## Ask a question :question: - -| [](https://kubernetes.slack.com/messages/openebs) | **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](https://kubernetes.slack.com/messages/openebs/)
| -| :--- | :--- | - -
- -## 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. -``` - -
- -> [!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) -> 2. Issues that span ```multiple products``` -> - For this type of issue, [create your issue here](https://github.com/openebs/openebs/issues) -> 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](./CONTRIBUTING.md#multiple-products) -
- -### 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).
-> - 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.
-> - 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. - -
- -### 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](https://github.com/openebs/mayastor) | [Create your Issues here](https://github.com/openebs/mayastor/issues) | -|   | | -| | ```Local PV``` | ```Non-replicated node local storage and volumes``` | | -| 2. | [LocalPV-HostPath](https://github.com/openebs/dynamic-localpv-provisioner) | [Create your Issues here](https://github.com/openebs/dynamic-localpv-provisioner/issues) | -| 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) | - -
- -
- -### 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 - ---- +## Code of Conduct -## Report a documentation issue +Please review our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing. Adherence to these guidelines is expected from all community members. -We use the same GitHub issue tracker for documentation issues, with a label for documentation: -
-:arrow_forward: [OpenEBS Documentation Issues](https://github.com/openebs/openebs/labels/documentation%2Fdevel) -
+## Topics -- Issues are triaged and prioritized in the regular community meeting -
+* [Reporting general issues](#reporting-general-issues) +* [Reporting security issues](#reporting-security-issues) +* [Code and documentation contributions](#code-and-documentation-contributions) +* [Review process](#review-process) +* [How to engage](#how-to-engage) +* [Final notes](#final-notes) ---- +## Reporting general issues -## Report a security issue or vulnerability +We appreciate your feedback and encourage every user to become a contributor. To report an issue or suggest an improvement, please follow these steps: -> [!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.
-> :arrow_forward:   [Email security issue to OpenEBS maintainers](mailto:cncf-openebs-maintainers@lists.cncf.io)
->
-> After addressing any security issue, they will be discussed in the regular community meeting
-
+1. Navigate to the [OpenEBS issue tracker](https://github.com/openebs/openebs/issues) and click on **New issue**. +2. Select the appropriate issue type and click **Get started**. +3. Fill in the issue title and details as prompted by the issue template. +4. Click **Submit new issue**. -## Contribute to Source Code and Bug Fixes +We value **clear**, **detailed**, and **explicit** issue reports. Before creating a new issue, please search existing issues to avoid duplication. If your concern has already been raised, add your details in the comments. -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:
+Examples of issues include: +- Bug reports +- Feature requests +- Performance concerns +- Design proposals +- Requests for additional tests or documentation +- General questions -- 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
-
+*Remember:* Always remove sensitive data (passwords, secret keys, network locations, private business data, etc.) from your issue report. -> - When creating your PR, please use appropriate tags to identify your source code. For a list of tags that could be used, see [this](https://github.com/openebs/openebs/blob/main/contribute/labels-of-issues.md). -> - For contributing to K8s demo, please refer to this [document](https://github.com/openebs/openebs/blob/main/contribute/CONTRIBUTING-TO-K8S-DEMO.md). -> - For understanding how OpenEBS works with K8s, refer to this [document](https://github.com/openebs/openebs/blob/main/k8s/README.md) -> - For contributing to K8s OpenEBS Provisioner, refer to this [document](https://github.com/openebs/openebs/blob/main/contribute/CONTRIBUTING-TO-KUBERNETES-OPENEBS-PROVISIONER.md). -> - For code structuring and guidelines, refer to this [document](https://github.com/openebs/openebs/blob/main/contribute/design/code-structuring.md) -> - Feel free to discuss developer topics in our [OpenEBS DEV Kubernetes Slack Channel](https://kubernetes.slack.com/messages/openebs-dev/) -
+## Reporting security issues -
+We take security issues very seriously. If you discover a security vulnerability in OpenEBS, **do not** open a public issue or discuss it openly. Please refer to [Security Guidelines](./SECURITY.md). -## Solve Existing Issues +## Code and Documentation Contributions -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. +Contributions that improve OpenEBS code, tests, or documentation always welcome. If you see something that can be improved or fixed, please feel free to submit a pull request (PR). Some examples include: -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. +* Fixing typos or documentation errors +* Resolving bugs or adding missing tests +* Refactoring code for clarity and efficiency +* Enhancing existing features or adding new ones +* Removing redundant code or clarifying implicit logic -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: -
-:arrow_forward: [OpenEBS DEV Kubernetes Slack Channel](https://kubernetes.slack.com/messages/openebs-dev/) -
+Please follow Contribution to Developer docs [here](./contribute/CONTRIBUTING-TO-DEVELOPER-DOC.md). +To avoid duplicate work, please check the community discussions or existing issues before starting your work. Review our [PR guidelines](#pr-guidelines) below for additional details. -## Sponsor a new feature or enhancement +### Contribution Setup -New enhancements are referred to as OpenEBS Enhancement Proposals (OEPs). -Anyone can sponsor a new OEP. Here is the process: +Please follow the [Contribution Setup Guidelines](./contribute/contribution-setup.md). -1. Sponsor creates a GitHub issue to track the OEP as a whole. -1. Sponsor creates a GitHub (pull request) PR with a `provisional` OEP, with its oep-number set to the tracking GitHub issue number. -1. Discussions are encouraged, either on the OEP related issues or the PR. -1. OEPs are reviewed in the maintainer and community meetings. -1. The OEP is submitted for approval by modifying its status to `implementable` via a PR (this may be the original PR for simple enhancements). -1. The community may vote on the OEP, maintainers have binding votes. +### Branch Definition ---- +We expect that contributions via pull requests target the `develop` branch unless otherwise noted. Additional branches (such as release candidates, release branches, and backport branches) may exist for testing and maintenance purposes. Please check any project-specific guidelines if you plan to contribute outside the `develop` branch. -### Sign your work +### PR Guidelines -
+* Ensure your local repository is up-to-date with the upstream repository. +* Limit your PR to a single focus (e.g., one bug fix or feature) to simplify review. +* Push your changes to your forked repository. +* Navigate to your repository on GitHub, click New pull request, and select the branch with your changes. +* Fill in the pull request template with detailed information about your changes. +* Submit the pull request and monitor the CI results. +* If additional commits are added later, ensure they remain focused on the issue at hand. It is often best to keep your pull request as a single logical change to simplify the review process. -> [!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. +### Review Process -> - This is a [well established and widely used mechanism](https://github.com/apps/dco)
-> - DCO ensures contributors have confirmed their right to license their contribution under the project's license.
-> - 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.
-> - 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. +Reviewing contributions is an essential part of maintaining a high-quality project. To review someone else’s pull request: -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:
-
+* Browse open pull requests at the OpenEBS pull requests page. +* Click Files changed to examine the changes. +* Use inline commenting (click the + sign next to a line) to suggest improvements or ask questions. Start a review if needed, then add comments. +* Once your review is complete, click Finish your review and then Submit review. +* Your constructive feedback helps maintain OpenEBS’s quality and guides contributors. -### Examples of how to DCO Sign-off your work...
+### How to Engage +Beyond code contributions, there are many ways to support OpenEBS: -
+* Answer questions and provide support on GitHub issues. +* Review and comment on pull requests. +* Discuss proposals and designs to improve clarity and robustness. +* Advocate for OpenEBS within the CNCF community and beyond. +* Write blog posts or share your experience with OpenEBS. +* Every contribution—big or small—helps improve the project and supports the community. -> Example of manual DCO signoff commit signature message:
-> ```Signed-off-by: Random J Developer ``` -> -> Example of automated git cli command:
-> ```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```:**
-> :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.
-> :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.
-
- -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](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.
-
- ---- -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](https://github.blog/news-insights/product-news/github-merge-queue-is-generally-available/). - ---- - -## [Monthly Community Meetings](./README.md#monthly-community-meetings) - -## Other ways to keep in touch - -### Email - -You can email the maintainers at any time: -
-:arrow_forward: [CNCF Mailing List](mailto:cncf-openebs-maintainers@lists.cncf.io) -
-:arrow_forward: [Google Groups](mailto:openebs-team@googlegroups.com) - -### Social Media - -Social media links -
-:arrow_forward: [TwitterX](https://twitter.com/openebs/) -
-:arrow_forward: [LinkedIn](https://www.linkedin.com/company/openebs/) -
-:arrow_forward: [Youtube](https://www.youtube.com/@openebscommunity6021) - -
- ---- - -## A good contributor workflow - -The following table is a guide to help you decide which channel, method and mechanism to use when contributing. - -1. In most cases, consider starting at the top (post a Slack channel question) -1. And then work your way down, Discussion, Issue, Projects -1. 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```](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). | -| 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](https://github.com/openebs/openebs/blob/main/designs/oep-process.md). | +### Final Notes -## Code of Conduct +OpenEBS is one of the many projects under the CNCF umbrella, and our repository is part of a broader ecosystem of cloud-native technologies. We invite you to explore other OpenEBS repositories and engage with the community. Together, we can make OpenEBS even better! -OpenEBS follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). +Thank you for your contributions! diff --git a/README.md b/README.md index 5908de4..0f552a4 100644 --- a/README.md +++ b/README.md @@ -1,76 +1,71 @@ -# Community Repo Cafe +# OpenEBS Community -[![OpenEBS Welcome to Community Repo Coffee SHop](/images/coffe-shop-hacker-pixel-art_HERO_banner.png)](https://www.openebs.io/) -[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenebs%2Fcommunity.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenebs%2Fcommunity?ref=badge_shield) -[![Slack](https://img.shields.io/badge/chat-slack-ff1493.svg?style=flat-square)](https://kubernetes.slack.com/messages/openebs/) -
+[![CNCF Status](https://img.shields.io/badge/cncf%20status-sandbox-blue.svg)](https://www.cncf.io/projects/openebs/) +[![LICENSE](https://img.shields.io/github/license/openebs/openebs.svg)](./LICENSE) +[![FOSSA Status](https://app.fossa.com/api/projects/custom%2B162%2Fgithub.com%2Fopenebs%2Fopenebs.svg?type=shield&issueType=license)](https://app.fossa.com/projects/custom%2B162%2Fgithub.com%2Fopenebs%2Fopenebs?ref=badge_shield&issueType=license) +[![CLOMonitor](https://img.shields.io/endpoint?url=https://clomonitor.io/api/projects/cncf/openebs/badge)](https://clomonitor.io/projects/cncf/openebs) +[![Slack](https://img.shields.io/badge/chat-slack-ff1493.svg?style=flat-square)](https://kubernetes.slack.com/messages/openebs) +[![Community Meetings](https://img.shields.io/badge/Community-Meetings-blue)](https://us05web.zoom.us/j/87535654586?pwd=CigbXigJPn38USc6Vuzt7qSVFoO79X.1) +[![Artifact HUB](https://img.shields.io/endpoint?url=https://artifacthub.io/badge/repository/openebs)](https://artifacthub.io/packages/helm/openebs/openebs) > [!Important] -> OpenEBS is an umbrella :open_umbrella: project, composed as a federation of individual sub projects (repositories). The project files in this repository apply to the umbrella project, every sub project, repository and file in the OpenEBS organization. -
+> OpenEBS is an umbrella :open_umbrella: project, composed as a federation of individual sub-projects. The project files in this repository apply to the umbrella project and every sub-project in the OpenEBS organization. -## About the Community Repo Cafe
+## What is OpenEBS? -This Community repository is the ```central location``` for project info and files (like [our GOVERNANCE contract](GOVERNANCE.md) & [our CONTRIBUTING guide](CONTRIBUTING.md) etc) for the OpenEBS organization. You'll also find a [Top level Issues List](https://github.com/openebs/openebs/issues) for Organization related issues that span across products/projects. We also provide a [main Discussions forum](https://github.com/openebs/openebs/discussions) where **```everyone```** can collaborate and discuss anything. -
+OpenEBS is an open-source Container Native Storage solution that provides persistent storage for Kubernetes workloads. It enables dynamic provisioning of storage resources using containerized storage controllers, making it highly flexible and cloud-native. OpenEBS supports various storage engines, including LocalPVs for direct node storage and Replicated PV advanced data replication and resilience. It is designed to integrate seamlessly with Kubernetes, offering benefits like storage policies, resize, thin-provisioning, snapshots, and restore capabilities, making it an ideal choice for stateful applications. To read more about OpenEBS, check [here](https://github.com/openebs/openebs/). -## Important documents and contacts +Below are the list of sub-projects: -This repository contains all the project files for the organization, and the following project files are important for understanding the OpenEBS project, and how we operate: +- [Local PV Hostpath](https://github.com/openebs/dynamic-localpv-provisioner/) +- [Local PV ZFS](https://github.com/openebs/zfs-localpv) +- [Local PV LVM](https://github.com/openebs/lvm-localpv) +- [Mayastor](https://github.com/openebs/mayastor) -* [OpenEBS Vision](/VISION.md) Defines the vision, mission statement; what is in-scope and out-of-scope for the project -* [Governance](/GOVERNANCE.md) How the project operates -* [Contributing](/CONTRIBUTING.md) How to contribute, guidelines for being a contributor -
+## Who we are -## Project Leadership team +We are a community of innovative Data Storage engineers that contribute to this project. OpenEBS is the result of hundreds of amazing individuals, contributors and storage engineers who provide brainstorming ideas, feedback, code reviews and high-quality code to the project. Anyone who is passionate about storage and data is welcome here.
-This Community is managed by the OpenEBS ```Maintainers``` and **Senior leaders** within the OpenEBS project team. We liaise with the Linux Foundation and CNCF on project, governance -and operational matters. We curate the daily operations of the project, product, roadmaps, initiatives, all engineering/code activities and all events (including conferences). -
+## Community -## Who we are +This Community repository is the ```central location``` for project info and files like our governance, contribution, code of conduct, security and vision for the OpenEBS organization laid out by the Maintainers. You'll also find a [Top level Issues List](https://github.com/openebs/openebs/issues) for Organization related issues that span across products/projects. We also provide a [main Discussions forum](https://github.com/openebs/openebs/discussions) where **```everyone```** can collaborate and discuss anything. -We are a community of innovative Data Storage engineers that contribute to this project. We are grateful for the major sponsorship provided by [DataCore (also known as DataCore Software)](https://datacore.com), who donate a team of dedicated Dev/QA/Engineers, Product Mgmt, Marketing, Business and Operational leadership as well as significant engineering infrastructure resources and financial funding. Without DataCore OpenEBS would not be the successful product that it is today. OpenEBS is the result of hundreds of amazing individuals, contributors and storage engineers who provide brainstorming ideas, feedback, code reviews and high-quality code to the project. Anyone who is passionate about storage and data is welcome here.
+- Homepage: [openebs.io](https://openebs.io/) +- Mailing list: openebs-team@googlegroups.com +- Slack: [slack](https://kubernetes.slack.com/messages/openebs) +- Twitter: [openebs](https://twitter.com/intent/follow?screen_name=openebs) +- Community Meeting: OpenEBS holds a monthly community meeting via Zoom on the last Thursday of the month, at 14:00 UTC. [Meeting Link](https://us05web.zoom.us/j/87535654586?pwd=CigbXigJPn38USc6Vuzt7qSVFoO79X.1) +- Community Meeting Recordings: [Youtube](https://www.youtube.com/@openebscommunity6021) -## Monthly Community Meetings +## Documents -OpenEBS holds a monthly community meeting via Zoom on the last Thursday of the month, at 14:00 UTC.
+- [Official Documentation](https://openebs.io/docs) +- [Governance](./GOVERNANCE.md) +- [Contributing Guidelines](./CONTRIBUTING.md) +- [Security Guidelines](./SECURITY.md) +- [Vision](./VISION.md) +- [Roadmap Tracker](https://github.com/orgs/openebs/projects/78) -Meeting Link:
-Starting from August 2024, the meetings are recorded and posted on YouTube:
+## Project Leadership team -## Code of Conduct +This Community is managed by the OpenEBS [Maintainers](./MAINTAINERS.md) within the OpenEBS project team. We liaise with the Linux Foundation and CNCF on project, governance +and operational matters. We curate the operations of the project, product, roadmaps, initiatives, all engineering/code activities and all events (including conferences). -OpenEBS follows the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/main/code-of-conduct.md). + [Container Storage Interface group](https://github.com/kubernetes/community/tree/HEAD/sig-storage) [Storage Technical Advisory Group](https://github.com/cncf/tag-storage)     [Cloud Native Community Groups](https://github.com/cncf/communitygroups) ---- -[![OpenEBS Welcome Banner](/images/community_banner_retro_gamer_level-up-2024_transp.png)](https://www.openebs.io/) +## How can I get involved? -> [!NOTE] -> CNCF Project status: SANDBOX
-> ```⚠️```   In Jan 2024, under the guidance of CNCF TOC, our project moved from Sandbox level to Archive level, enabling us to implement an extensive restructuring initiative. We are actively working to archive legacy sub projects, repositories and dependencies to a CNCF owned GitHub organization called: [OpenEBS-Archive](https://github.com/openebs-archive), plus updating our governance and operating procedures.
-> ```⚠️```   On 13 June 2024, under guidance of CNCF TOC, our project re-Applied for CNCF promotion from ```Archive``` up to ```Sandbox``` level and was accepted back into -```Sandbox``` in Oct 2024. See our Sandbox promotion [application here](https://github.com/cncf/sandbox/issues/104) -> -> * What's changing in the technology stack? The product team is unifying ``` Five ``` major Storage Engines (Mayastor, LocalPV-LVM, LocalPV-ZFS, LocalPV-Hostpath, RawFile) into one core OpenEBS code-base. -> * For more information, see [the parent issue]( https://github.com/openebs/openebs/issues/3701) in our main repo for more detail. -> -
+One of the easiest ways to contribute is to participate in discussions at community engagements. ---- +If you're looking for something to work on, read the [contribution guidelines](./CONTRIBUTING.md) and then you start by looking for GitHub issues, marked with `kind/good-first` or the `kind/help-wanted` labels. -[![CNCF logo](/images/CNCF_member-silver-color.svg)](https://www.datacore.com/) -OpenEBS is a CNCF project and DataCore is a CNCF Silver member. DataCore supports CNCF extensively and has funded OpenEBS participating in every KubeCon event since 2020. Our project team is managed under the CNCF Storage Landscape and we contribute to the CNCF CSI and TAG Storage project initiatives. We proudly support CNCF Cloud Native Community Groups initiatives.
-
+And, we can always use more testing, have more and improved docs, or just write a blog post on what you have discovered whilst using OpenEBS. -| [Container Storage Interface group](https://github.com/kubernetes/community/tree/master/sig-storage) | [Storage Technical Advisory Group](https://github.com/cncf/tag-storage) |     [Cloud Native Community Groups](https://github.com/cncf/communitygroups)| -| :--- | :---: | ---: | +## Code of Conduct -
+OpenEBS adopts the [CNCF Code of Conduct](https://github.com/cncf/foundation/blob/HEAD/code-of-conduct.md). -**Thanks for dropping by.\ -We appreciate everyone in our community and would love to hear from you.** +This open governance applies to all repos under the `openebs` org. Enjoy coding and collaboration in OSS world! ## Activity dashboard @@ -79,3 +74,7 @@ We appreciate everyone in our community and would love to hear from you.** ## License [![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fopenebs%2Fcommunity.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2Fopenebs%2Fcommunity?ref=badge_large) + +## OpenEBS is a [CNCF Sandbox Project](https://www.cncf.io/projects/openebs) + +![OpenEBS is a CNCF Sandbox Project](https://github.com/cncf/artwork/blob/main/other/cncf/horizontal/color/cncf-color.png) \ No newline at end of file diff --git a/VISION.md b/VISION.md index 9284e1f..e91f268 100644 --- a/VISION.md +++ b/VISION.md @@ -16,7 +16,7 @@ This document presents the project: ## Vision, Mission Statement and Scope -**Our Vision:** The Kubernetes enterprise storage standard
+**Our Vision:** The democratized Kubernetes enterprise storage standard
**Our Mission Statement:** OpenEBS is a *CNCF project* that provides fast, resilient, available, native, enterprise-grade storage to applications running in *Kubernetes clusters*. | Term | Meaning | @@ -28,6 +28,7 @@ This document presents the project: | *Native* | Implemented as ```container native storage```, a Kubernetes natively integrated component, optimized for storage contained inside a Kubernetes cluster (Hyper-converged). | | *Enterprise grade* | A fully featured, community-proven, rigorously tested, trustworthy, Mission Critical product. | | *Kubernetes* | OpenEBS focus is for Kubernetes-on-Linux. | +| *Democratized* | Accessible to Everyone. |
@@ -37,7 +38,7 @@ This document presents the project: ### Scope -In the past, the OpenEBS project has tried to accomplish too much. Our scope was too broad and not clearly defined enough for our community. We are explicitly naming the following capabilities as ```in-scope``` and ```out-of-scope``` for the project: +The OpenEBS project has a clearly defined focus for our community. We are explicitly naming the following capabilities as `in-scope` and `out-of-scope` for the project: > **In Scope**
@@ -89,21 +90,7 @@ OpenEBS is a self-governing project, and operates within the following restraint * The OpenEBS project is open source, and operations are governed by CNCF rules set up for CNCF projects. * The OpenEBS project adds ```domain-specific Governance```, ```Contribution``` and ```operating rules``` on **top of the CNCF rules**. We provide for exceptions from the CNCF rules if approved by the CNCF Technical Oversight Committee (TOC). -[![CNCF logo](/images/CNCF_member-silver-color.svg)](https://www.datacore.com/) -DataCore, Inc. is a CNCF Silver member. DataCore supports CNCF extensively and funds all OpenEBS CNCF events. The project team is managed under the CNCF Storage Landscape and contributes to the CNCF CSI and TAG Storage project initiatives at the CNCF membership level that funding allows. OpenEBS proudly supports CNCF Cloud Native Community Groups initiatives.
-
- -| Container Storage Interface group | Storage Technical Advisory Group |     Cloud Native Community Groups | -| :--- | :---: | ---: | - -### DataCore -> -> [!IMPORTANT] -> -> * OpenEBS was created by MayaData (now part of [DataCore Software, Inc.](https://datacore.com) ), and donated to [CNCF](https://cncf.io) in 2019. -> * DataCore engineers contribute a majority of the contributions, program management, Engineering, Dev, and QA resources as well as considerable infrastructure funding to the daily operations of the project. -> * The project requires multiple Full-Time ```Subject Matter Experts```, Full-Time storage engineers and Full-Time QA Engineers/testers. While the project requires this commitment, it is expected DataCore engineers may be a majority of the contributing Eng/Dev/QA/PM community. -> * OpenEBS is a community project, and DataCore has been and continues to be a significant part of the community. + [Container Storage Interface group](https://github.com/kubernetes/community/tree/master/sig-storage) [Storage Technical Advisory Group](https://github.com/cncf/tag-storage)     [Cloud Native Community Groups](https://github.com/cncf/communitygroups) ## Conformance diff --git a/contribute/CONTRIBUTING-TO-DEVELOPER-DOC.md b/contribute/CONTRIBUTING-TO-DEVELOPER-DOC.md new file mode 100644 index 0000000..aec8399 --- /dev/null +++ b/contribute/CONTRIBUTING-TO-DEVELOPER-DOC.md @@ -0,0 +1,55 @@ +# Contributing to OpenEBS [Developer Documentation] + +This document describes the process for improving developer documentation by creating PRs at OpenEBS. + +The developer documentation includes anything that will help the community like: + +- Architecture and Design documentation +- Technical or Research Notes +- FAQ +- Process Documentation +- Generic / Miscellaneous Notes + +We are also looking for an explainer video or presentation from the community that helps new developers in understanding the OpenEBS Architecture, its use cases, and installation procedure locally. + +At a very high level, the process to contributing and improving the code is pretty simple: + +- Submit an issue describing your proposed change +- Create your development branch +- Commit your changes +- Submit your Pull Request + +The following sections describe some guidelines that can come in handy with the above process. +*Followed by the guidelines, is a [cheatsheet](https://github.com/openebs/openebs/blob/HEAD/contribute/git-cheatsheet.md) with frequently used git commands.* + +## Submit an issue describing your proposed change + +Some general guidelines when submitting issues for developer documentation: + +- If the proposed change requires an update to the existing page, please provide a link to the page in the issue. +- If you want to add a new page, then go ahead and open an issue describing the requirement for the new page. + +You can also help with some existing issues under this category available at [developer documentation issues list](https://github.com/openebs/openebs/issues?q=is%3Aopen%20label%3A%22kind%2Fdocumentation%22%20) + +## Create your development branch + +- Fork the [OpenEBS](https://github.com/openebs/openebs/) repository and if you have forked it already, rebase with develop branch to fetch latest changes to your local system. +- Create a new development branch in your forked repository with the following naming convention: *"task description-#issue"* + + **Example:** This change is being developed with the branch named: *OpenEBS-DevDoc-PR-Workflow-#213* + +## Commit your changes + +- Reference the issue number along with a brief description in your commits +- Set your commit.template to the `COMMIT_TEMPLATE` given in the `.github` directory. + `git config --local commit.template $GOPATH/src/github.com/openebs/openebs/.github` + +## Submit a Pull request + +- Rebase your development branch +- Submit the PR from the development branch to the openebs/openebs:develop +- Incorporate review comments, if any, in the development branch. +- Once the PR is accepted, close the branch. +- After the PR is merged the development branch in the forked repository can be deleted. + +If you need any help with git, refer to this [git cheat sheet](./git-cheatsheet.md) and go back to the [**contributing to OpenEBS Documentation**](../CONTRIBUTING.md) guide to proceed. diff --git a/contribute/contribution-setup.md b/contribute/contribution-setup.md new file mode 100644 index 0000000..56c0ad4 --- /dev/null +++ b/contribute/contribution-setup.md @@ -0,0 +1,86 @@ +# OpenEBS Contributing Setup Guide + +Fork the [openebs/openebs](https://github.com/openebs/openebs) repository into your account, referred in the below instructions as $user. You can follow the same approach for all the other repositories where you want to contribute. + +## Setting up Development Environment for OpenEBS projects + +```bash +working_dir=$GOPATH/src/github.com/openebs +mkdir -p $working_dir +cd $working_dir +``` + +Set `user` to match your Github profile name: +for setting global configurations use - +git config --global user.name "your usernae here" +git config --global user.email "your email used in github account" + +and for configuring locally use the above commands just remove the --global flag +```bash +user={your Github profile name} +``` + +## The steps mentioned here are w.r.t contribution towards openebs/openebs project + +```bash +git clone https://github.com/$user/openebs.git +cd openebs/ +git remote add upstream https://github.com/openebs/openebs.git +git remote set-url --push upstream no_push +git remote -v +``` + +## Synchronizing your local develop(i.e. your $user/openebs project) with upstream develop(i.e. openebs/openebs) + +```bash +git checkout develop +git fetch upstream develop +git rebase upstream/develop +git status +git push origin develop +``` + +## Create Branch (based on feature or bug name) + +```bash +git branch +git checkout +git push --set-upstream origin +``` + +## Synchronizing (i.e rebase) your local branch with upstream develop + +```bash +git checkout +git fetch upstream develop +git rebase upstream/develop +git status +git push +``` + +## Make changes to your local branch + +```bash +# make your changes +# keep fetching the commits from upstream develop & rebase them here +git add -A +git commit -m "creating changes in local repository" +git push + +# submit the PR to upstream from browser link https://github.com/$user/openebs +``` + +## Delete Branch + +```bash +git push origin --delete +git branch -d +``` + +## Writing a Unit Test + +Though it is important to write unit tests, do not try to achieve 100% code coverage if it complicates writing these tests. If a unit test is simple to write & understand, most probably it will be extended when new code gets added. However, the reverse will lead to its removal on the whole. In other words, complicated unit tests will lead to decrease in the overall coverage in the long run. + +OpenEBS being an OpenSource project will always try to experiment with new ideas and concepts. Hence, writing unit tests will provide the necessary checklist that reduces the scope for errors. + +Go back to [**Contributing to OpenEBS**](../CONTRIBUTING.md). diff --git a/contribute/developer-certificate-of-origin b/contribute/developer-certificate-of-origin new file mode 100644 index 0000000..8201f99 --- /dev/null +++ b/contribute/developer-certificate-of-origin @@ -0,0 +1,37 @@ +Developer Certificate of Origin +Version 1.1 + +Copyright (C) 2004, 2006 The Linux Foundation and its contributors. +1 Letterman Drive +Suite D4700 +San Francisco, CA, 94129 + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. + + +Developer's Certificate of Origin 1.1 + +By making a contribution to this project, I certify that: + +(a) The contribution was created in whole or in part by me and I + have the right to submit it under the open source license + indicated in the file; or + +(b) The contribution is based upon previous work that, to the best + of my knowledge, is covered under an appropriate open source + license and I have the right under that license to submit that + work with modifications, whether created in whole or in part + by me, under the same open source license (unless I am + permitted to submit under a different license), as indicated + in the file; or + +(c) The contribution was provided directly to me by some other + person who certified (a), (b) or (c) and I have not modified + it. + +(d) I understand and agree that this project and the contribution + are public and that a record of the contribution (including all + personal information I submit with it, including my sign-off) is + maintained indefinitely and may be redistributed consistent with + this project or the open source license(s) involved. diff --git a/contribute/general/quick-start-with-vim-go.md b/contribute/general/quick-start-with-vim-go.md new file mode 100644 index 0000000..0d9edd4 --- /dev/null +++ b/contribute/general/quick-start-with-vim-go.md @@ -0,0 +1,51 @@ +# Setting up vim-go on Ubuntu 22.04 + +## Pre-requisites +Ensure you have a working Go environment. Also, make sure that your `$GOPATH/bin` is included in your `PATH`. + +## Install Vim (if not already installed) +```sh +sudo apt update +sudo apt install vim +``` + +## Install and setup vim-go +The following steps will help you set up `vim-go` on Ubuntu 22.04. + +### Step 1: Install vim-plug and vim-go +```sh +curl -fLo ~/.vim/autoload/plug.vim --create-dirs \ + https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim +git clone https://github.com/fatih/vim-go.git ~/.vim/plugged/vim-go +``` + +### Step 2: Configure vimrc to use the plugins +Create or update `~/.vimrc` with the following content: +```vim +call plug#begin() +Plug 'fatih/vim-go', { 'do': ':GoInstallBinaries' } +call plug#end() +``` + +### Step 3: Install plugins and initialize Go dependencies +Launch Vim and run the following command to install plugins: +```vim +:PlugInstall +``` +This will show a window indicating that plugins are installed. + +Now, install the required Go binaries: +```vim +:GoInstallBinaries +``` +This will download and install the Go dependencies into your `GOPATH/bin`. + +## Using vim-go +The `vim-go` plugin provides various shortcuts and enhancements. With the default `.vimrc` configuration above, you can: +- Build your Go project: `:GoBuild` +- Navigate to a definition: `Ctrl-]` +- Navigate back: `Ctrl-o` + +For more customization and additional features, refer to the official `vim-go` documentation: +- https://github.com/fatih/vim-go + diff --git a/contribute/general/systemtap-and-go.pdf b/contribute/general/systemtap-and-go.pdf new file mode 100644 index 0000000..96e2459 Binary files /dev/null and b/contribute/general/systemtap-and-go.pdf differ diff --git a/contribute/git-commit-message.md b/contribute/git-commit-message.md new file mode 100644 index 0000000..8510918 --- /dev/null +++ b/contribute/git-commit-message.md @@ -0,0 +1,72 @@ +# Commit Message Guidelines for OpenEBS Projects + +This document borrows concepts, conventions, and text mainly from the following sources, extending them in order to provide a sensible guideline for writing commit messages for OpenEBS projects. +- Tim Pope's [article](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) on readable commit messages +- Thanks to @stephenparish https://gist.github.com/stephenparish/9941e89d80e2bc58a153 +- Thanks to @abravalheri https://gist.github.com/abravalheri/34aeb7b18d61392251a2 + +These conventions are aimed at tools to automatically generate useful documentation, or by developers during debugging process. + +## Proposed Commit Message Format + +Any line of the commit message cannot be longer than 80 characters! This allows the message to be easier to read on github as well as in various git tools. To read more about conventional commits refer [here](https://www.conventionalcommits.org/en/v1.0.0/#specification). + +``` +(): + + + +