From f7d8772439b245fa4fd80d981d22b12e71831cde Mon Sep 17 00:00:00 2001 From: Rashmi Gottipati Date: Thu, 21 Sep 2023 11:04:17 -0400 Subject: [PATCH] Address review comments Signed-off-by: Rashmi Gottipati --- CONTRIBUTING.md | 149 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 118 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 66f604b5..8e89e4eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,77 +1,164 @@ # How to Contribute -Catalogd is [Apache 2.0 licensed](LICENSE.md) and accepts contributions via GitHub pull requests. This document puts together some guidelines on how to make contributions to Catalogd and provides contacts to get in touch with the Catalogd maintainers and developers. To learn more about Catalogd and how it fits into `OLM V1`, please refer to [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit#heading=h.dbjdp199nxjk). +Catalogd is [Apache 2.0 licensed](LICENSE.md) and accepts contributions via +GitHub pull requests. This document puts together some guidelines on how to make +contributions to Catalogd and provides contacts to get in touch with the +Catalogd maintainers and developers. To learn more about Catalogd and how it +fits into `OLM V1`, please refer to [Operator Lifecycle Manager (OLM) V1 Product +Requirements Document +(PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit#heading=h.dbjdp199nxjk). ## Certificate of Origin -By contributing to this project you agree to the Developer Certificate of Origin (DCO). This document was created by the Linux Kernel community and is a -simple statement that you, as a contributor, have the legal right to make the contribution. See the [DCO](https://github.com/operator-framework/catalogd/blob/main/DCO) file for details. +By contributing to this project you agree to the Developer Certificate of Origin +(DCO). This document was created by the Linux Kernel community and is a simple +statement that you, as a contributor, have the legal right to make the +contribution. See the +[DCO](https://github.com/operator-framework/catalogd/blob/main/DCO) file for +details. ## Communication Channels -- Mailing List: [operator-framework-olm-dev](mailto:operator-framework-olm-dev@googlegroups.com) +- Mailing List: + [operator-framework-olm-dev](mailto:operator-framework-olm-dev@googlegroups.com) - Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2) -- Working Group Meeting: [olm-wg](https://groups.google.com/g/operator-framework-olm-dev) +- Working Group Meeting: + [olm-wg](https://groups.google.com/g/operator-framework-olm-dev) ## Getting started - Fork the repository on GitHub. -- Clone the repository onto your local development machine via `git clone https://github.com/{$GH-USERNAME}/catalogd.git`. -- Add `operator-framework/catalogd` upstream remote by running `git remote add upstream https://github.com/operator-framework/catalogd.git`. -- Create a new branch from the default `main` branch and begin development in the area of your interest. +- Clone the repository onto your local development machine via `git clone + https://github.com/{$GH-USERNAME}/catalogd.git`. +- Add `operator-framework/catalogd` upstream remote by running `git remote add + upstream https://github.com/operator-framework/catalogd.git`. +- Create a new branch from the default `main` branch and begin development in + the area of your interest. ## Reporting bugs and creating issues -Any new contribution should be linked to a new or existing github issue in the Catalogd project. This issue can help track work, discuss the design and implementation, and help avoid duplicate efforts of multiple people working on the same issue. Trivial changes, like fixing a typo in the documentation, do not require the creation of a new issue but can be linked to an existing issue if it exists. - -Proposing larger changes to the Catalogd project may require an enhancement proposal, or some documentation, before being considered. The maintainers typically use [HackMD](https://hackmd.io) or standard RFC to write small design drafts for any new features. - -Any changes to Catalogd's existing behavior or features, APIs, or changes and additions to tests do not require an enhancement proposal. +Any new contribution should be linked to a new or existing github issue in the +Catalogd project. This issue can help track work, discuss the design and +implementation, and help avoid duplicate efforts of multiple people working on +the same issue. Trivial changes, like fixing a typo in the documentation, do not +require the creation of a new issue but can be linked to an existing issue if it +exists. + +Proposing larger changes to the Catalogd project may require an enhancement +proposal, or some documentation, before being considered. The maintainers +typically use Google Docs and an RFC process to write design drafts for any new +features. If you're interested in proposing ideas for new features, you can use +the [RFC +Template](https://docs.google.com/document/d/1aYFGdq3W3UKzkRbNopISIdzABh-o5S0et7q0h2qPFGw/edit#heading=h.x3tfh25grvnv) +to write an RFC and place it in the [Design Docs +Folder](https://drive.google.com/drive/u/1/folders/1c5jSCrXuE9bziZcEiIX3X89OEC5tRgEg). + +Any changes to Catalogd's existing behavior or features, APIs, or changes and +additions to tests do not require an enhancement proposal. ## Contribution flow Below is a rough outline of what a contributor's workflow looks like: -- Identify an existing issue or create a new issue. If you're new to Catalogd and looking to make a quick contribution and ramp up on the project, a good way to do this is to identify `good-first-issues` from [Catalogd Github Issues](https://github.com/operator-framework/catalogd/issues) by using the filter by label and search for "good first issue". Also, please feel empowered to work on other issues that interest you which are not good first issues. -- Create a new branch from the branch you would like to base your contribution from. Typically, this is the main branch. +- Identify an existing issue or create a new issue. If you're new to Catalogd + and looking to make a quick contribution and ramp up on the project, a good + way to do this is to identify `good-first-issues` from [Catalogd Github + Issues](https://github.com/operator-framework/catalogd/issues) by using the + filter by label and search for "good first issue". Also, please feel empowered + to work on other issues that interest you which are not good first issues. +- Create a new branch from the branch you would like to base your contribution + from. Typically, this is the main branch. - Create commits that are of logical units. -- Commit your changes and make sure to use commit messages that are in proper format following best practices and guidelines for git commit messages. -- Once you've committed your changes, push the new branch that contains your changes to your personal fork of the repository. +- Commit your changes and make sure to use commit messages that are in proper + format following best practices and guidelines for git commit messages (see + below). +- Once you've committed your changes, push the new branch that contains your + changes to your personal fork of the repository. - Submit a pull request to `operator-framework/catalogd` repository. -- Respond to feedback from the Catalogd maintainers and community members and address any review suggestions. The PR must receive an approval from atleast one Catalogd maintainer. +- Respond to feedback from the Catalogd maintainers and community members and + address any review suggestions. The PR must receive an approval from at least + one Catalogd maintainer. + +### Format of the commit message + +We follow a rough convention for commit messages that is designed to answer two +questions: what changed and why. The subject line should feature the what and +the body of the commit should describe the why. + +```text +(feature): create a minimal client library + +- Fixes #10 +- Add unit tests for the client library +``` + +The format can be described more formally as follows: + +```text +: + + + +