diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58b8fc8d..8e89e4eb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,11 +1,164 @@ # How to Contribute -This project is [Apache 2.0 licensed](LICENSE.md) and accepts contributions via -GitHub pull requests. +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](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) +- Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2) +- 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. + +## 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 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. +- 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 (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 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 +: + + + +