|
| 1 | +# How to contribute |
| 2 | + |
| 3 | +Operator Controller is an Apache 2.0 licensed project and accepts contributions via GitHub pull requests (PRs). |
| 4 | + |
| 5 | +This document outlines some conventions on commit message formatting, contact points for developers, and other resources |
| 6 | +to help Operator Controller contributors. |
| 7 | + |
| 8 | +## Communication |
| 9 | + |
| 10 | +- Email: [operator-framework-olm-dev ](mailto:[email protected]) |
| 11 | +- Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2) |
| 12 | +- Google Group: [olm-gg](https://groups.google.com/g/operator-framework-olm-dev) |
| 13 | +- Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) |
| 14 | + |
| 15 | +## Contribution flow |
| 16 | + |
| 17 | +Any new contribution should be accompanied by a new or existing issue. This issue can help track work, discuss the |
| 18 | +design and implementation, and help avoid wasted efforts of multiple people working on the same issue. Trivial changes, |
| 19 | +like fixing a typo in the documentation, do not require the creation of a new issue. |
| 20 | + |
| 21 | +### Small Contributions |
| 22 | + |
| 23 | +For simple contributions, this is a rough outline of what a contributor's workflow looks like: |
| 24 | + |
| 25 | +- Identify or create a GitHub Issue. |
| 26 | +- Create a topic branch from where to base the contribution. This is usually the main branch. |
| 27 | +- Make commits of logical units, be sure to include tests, and sign each commit to satisfy [the DCO](https://github.com/cncf/foundation/blob/main/dco-guidelines.md). |
| 28 | +- Make sure commit messages are in the proper format (see [code review](#code-review)). |
| 29 | +- Push changes in a topic branch to a personal fork of the repository. |
| 30 | +- Submit a PR to the operator-framework/operator-controller repository. |
| 31 | +- Wait and respond to feedback from the maintainers listed in the OWNERS file, we will do our best to respond promptly |
| 32 | +but encourage you to tag us on the PR if it isn't addressed within a week. |
| 33 | + |
| 34 | +### Large Contributions |
| 35 | + |
| 36 | +The Operator Controller project is an open source project featuring contributors from many companies and backgrounds. |
| 37 | +In an effort to coordinate ongoing efforts from multiple contributors, large scale features are tracked on the |
| 38 | +[OLM V1 GitHub Project](https://github.com/orgs/operator-framework/projects/8/views/14?pane=info) in a `Milestone #` tab. |
| 39 | +Unassigned tickets in a `Milestone #` are available for contributors to take, simply assign the ticket to yourself and |
| 40 | +reach out to the community by commenting on the issue or by messaging us on the [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2) Slack Channel. |
| 41 | + |
| 42 | +If you are interested in proposing a "focus" for a milestone, the contribution workflow should be similar to the following: |
| 43 | + |
| 44 | +- Create a [GitHub Issue](https://github.com/operator-framework/operator-controller/issues/new), labeled with "milestone-proposal", that includes a link to a [HackMD](https://hackmd.io) capturing the proposed changes. |
| 45 | +- Add an item to the [OLM Working Group and Issue Triage Meeting Agenda](https://docs.google.com/document/d/1Zuv-BoNFSwj10_zXPfaS9LWUQUCak2c8l48d0-AhpBw/edit) to introduce your design to the community. |
| 46 | +- Introduce your proposed changes at the weekly [OLM Working Group Meeting](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) |
| 47 | + |
| 48 | +The community will then discuss the proposal, consider the benefits and cost of the feature, iterate on the design, and decide if it project should pursue the design. If accepted, the design will be queued up for a subsequent milestone. |
| 49 | + |
| 50 | +Thanks for contributing! |
| 51 | + |
| 52 | +### Code Review |
| 53 | + |
| 54 | +Contributing PRs with a reasonable title and description can go a long way with helping the PR through the review |
| 55 | +process. |
| 56 | + |
| 57 | +When opening PRs that are in a rough draft or WIP state, prefix the PR description with `WIP: ...` or create a draft PR. |
| 58 | +This can help save reviewer's time by communicating the state of a PR ahead of time. Draft/WIP PRs can be a good way to |
| 59 | +get early feedback from reviewers on the implementation, focusing less on smaller details, and more on the general |
| 60 | +approach of changes. |
| 61 | + |
| 62 | +When contributing changes that require a new dependency, check whether it's feasible to directly vendor that |
| 63 | +code [without introducing a new dependency](https://go-proverbs.github.io/). |
| 64 | + |
| 65 | +Currently, PRs require at least one approval from a operator-controller maintainer in order to get merged. |
| 66 | + |
| 67 | +### Code style |
| 68 | + |
| 69 | +The coding style suggested by the Golang community is used throughout the operator-controller project: |
| 70 | + |
| 71 | +- [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) |
| 72 | +- [EffectiveGo](https://golang.org/doc/effective_go) |
| 73 | + |
| 74 | +In addition to the linked style documentation, operator-controller formats Golang packages using the `golangci-lint` tool. Before |
| 75 | +submitting a PR, please run `make lint` locally and commit the results. This will help expedite the review process, |
| 76 | +focusing less on style conflicts, and more on the design and implementation details. |
| 77 | + |
| 78 | +Please follow this style to make the operator-controller project easier to review, maintain and develop. |
| 79 | + |
| 80 | +### Documentation |
| 81 | + |
| 82 | +If the contribution changes the existing APIs or user interface it must include sufficient documentation to explain the |
| 83 | +new or updated features. |
| 84 | + |
| 85 | +The Operator Controller documentation is primarily housed at the root-level README. |
0 commit comments