Update the contributing doc based on feedback

Author: awgreene

CONTRIBUTING.md

@@ -1,53 +1,73 @@
-# How to contribute
+# How to Contribute
 
 Operator Controller is an Apache 2.0 licensed project and accepts contributions via GitHub pull requests (PRs).
 
-This document outlines some conventions on commit message formatting, contact points for developers, and other resources
-to help Operator Controller contributors.
+Thanks for you interest in contributing to the Operator-Controller. 
 
-## Communication
+As you may or may not know, the Operator-Controller project aims to deliver the user experience described in the [Operator Lifecycle Manager (OLM) V1 Product Requirements Document (PRD)](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit). The design requirements captured in the OLM V1 PRD were born from customer and community feedback based on the experience they had with the released version of [OLM V0](github.com/operator-framework/operator-lifecycle-manager).
+
+The user experience captured in the OLM V1 PRD introduces many requirements that are best satisfied by a microservices architecture. The OLM V1 experience currently relies on four projects:
+- [The Operator-Controller project](https://github.com/operator-framework/operator-controller/), which is the top level component allowing users to specify operators they'd like to install.
+- [The Catalogd project](https://github.com/operator-framework/catalogd/), which hosts operator content and helps users discover installable content.
+- [The Deppy project](https://github.com/operator-framework/deppy/), which enables the operator-controller to identify valid installs and upgrades from the list of installable content provided via the Catalod project
+- [The RukPak project](https://github.com/operator-framework/rukpak/), which facilitates the installation of operators.
+
+Each of the projects listed above have their own governance, release milestones, and release cadence. However, from a technical perspective, the "OLM V1 experience" matches the experienced offered by the operator-controller project, the top level component which introduces dependencies on RukPak, Deppy, and the Catalogd projects.
+
+## How do we collaborate
+
+> "We need to accept that random issues and pull requests will show up" - Joe L.
+
+Before diving into our process for coordinating community efforts, I think it's important to set the expectation that Open Source development can be messy. Any effort to introduce a formal workflow for project contributions will almost certainly be circumvented by new community users. Rather than pestering users to subscribe to a project-specific process, we strive to make it as simply as possible to provide valuable feedback. With that in mind, changes to the project will almost certainly follow this process:
+
+1. The community engages in discussion in the #olm-dev slack channel.
+2. The community creates GitHub Issues, GitHub Discussions, or pull requests in the appropriate repos based on (1) and potentially continue the discussion.
+3. The community utilize the Working Group and talk about (1) and (2) stuff and anything else that comes to mind.
+
+The workflow defined above implies that the community is always ready for discussion and that ongoing work can be found in the GitHub repository as GitHub Issues, GitHub Discussions, or pull requests, and that milestone planning is async, happening as part of (1), (2), and (3).
+
+Please keep this workflow in mind as you read through the document.
+
+### Communication Channels
 
 - Email: [operator-framework-olm-dev](mailto:[email protected])
 - Slack: [#olm-dev](https://kubernetes.slack.com/archives/C0181L6JYQ2)
 - Google Group: [olm-gg](https://groups.google.com/g/operator-framework-olm-dev)
 - Weekly in Person Working Group Meeting: [olm-wg](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) 
 
-## Contribution flow
+## How are Milestones Designed?
+
+It's unreasonable to attempt to consider all of the design requirements laid out in the [OLM V1 PRD](https://docs.google.com/document/d/1-vsZ2dAODNfoHb7Nf0fbYeKDF7DUqEzS9HqgeMCvbDs/edit) from the onset of the project. Instead, the community attempts to design Milestones with the following principles:
+- Milestones are tightly scoped units of work, ideally lasting one to three weeks.
+- Milestones are derived from the OLM V1 PRD.
+- Milestones are "demo driven", meaning that a set of acceptance criteria is defined upfront and the milestone is done as soon as some member of the community can run the demo.
+- Edge cases found during development are captured in issues and assigned to the GA Milestone, which contains a list of issues that block the release of operator-controller v1.0.0 .
+
+This "demo driven" development model will allow us to collect user experience and regularly course correct based on user feedback. Subsequent milestone may revert features or change the user experience based on community feedback.
 
-Any new contribution should be accompanied by a new or existing issue. This issue can help track work, discuss the
-design and implementation, and help avoid wasted 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.
+The project maintainer will create a [GitHub Discussion](github.com/operator-framework/operator-controller/discussions) for the upcoming milestone once we've finalized the current milestone. Please feel encouraged to contribute suggestions for the milestone in the discussion.
 
-### Small Contributions
+## Where are Operator Controller Milestones?
 
-For simple contributions, this is a rough outline of what a contributor's workflow looks like:
+Ongoing or previous Operator-Controller milestones can always be found in the [milestone section of our GitHub Repo](https://github.com/operator-framework/operator-controller/milestones).
 
-- Identify or create a GitHub Issue.
-- Create a topic branch from where to base the contribution. This is usually the main branch.
-- 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).
-- Make sure commit messages are in the proper format (see [code review](#code-review)).
-- Push changes in a topic branch to a personal fork of the repository.
-- Submit a PR to the operator-framework/operator-controller repository.
-- Wait and respond to feedback from the maintainers listed in the OWNERS file, we will do our best to respond promptly
-but encourage you to tag us on the PR if it isn't addressed within a week.
+### How are Subproject Issues Tracked?
 
-### Large Contributions
+As discussed earlier, the operator-controller adheres to a microservice architecture, where multiple projects contribute to the overall experience. As such, when designing an operator-controller milestone, the community may need to file an issue against RukPak, Deppy, or Catalogd. Unfortunately, the operator-controller milestone cannot contain issues from one of its subprojects. As such, we've introduced the concept of a "Dependency Issue", described below:
 
-The Operator Controller project is an open source project featuring contributors from many companies and backgrounds.
-In an effort to coordinate ongoing efforts from multiple contributors, large scale features are tracked on the
-[OLM V1 GitHub Project](https://github.com/orgs/operator-framework/projects/8/views/14?pane=info) in a `Milestone #` tab.
-Unassigned tickets in a `Milestone #` are available for contributors to take, simply assign the ticket to yourself and
-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.
+> Dependency Issues: An issue tracked in a milestone that "points" to an issue in another project with a URL.
 
-If you are interested in proposing a "focus" for a milestone, the contribution workflow should be similar to the following:
+## Submitting Issues
 
-- 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.
-- 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.
-- Introduce your proposed changes at the weekly [OLM Working Group Meeting](https://github.com/operator-framework/community#operator-lifecycle-manager-working-group) 
+Unsure where to submit an issue? 
+- The Operator-Controller project
+- The RukPak project
+- The Deppy project
+- The Catalogd project
 
-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.
+Don't worry if you accidentally submit an issue against the wrong project, if we notice that an issue would fit better with a separate project we'll move it to the correct repository and mention it in the #olm-dev slack channel.
 
-Thanks for contributing!
+## Submitting Pull Requests
 
 ### Code Review
 
@@ -82,4 +102,4 @@ Please follow this style to make the operator-controller project easier to revie
 If the contribution changes the existing APIs or user interface it must include sufficient documentation to explain the
 new or updated features.
 
-The Operator Controller documentation is primarily housed at the root-level README.
+The Operator Controller documentation is primarily housed at the root-level [README](https://github.com/operator-framework/operator-controller/blob/main/README.md).