Merge pull request #158 from mallardduck/branching-docs

Update docs for branching

README.md

@@ -5,13 +5,14 @@ This repo contains a set of three interlinked projects:
 
 - The **Prometheus Federator** is a k8s Operator that manages deploying Project Monitoring Stacks.
 - The **Helm Project Operator** is a generic design for a Kubernetes Operator that acts on `ProjectHelmChart` CRs.
+  - This project depends heavily on and expands functionality of `helm-controller`. 
 - **Helm Locker** is a Kubernetes operator that prevents resource drift on (i.e. "locks") Kubernetes objects that are tracked by Helm 3 releases.
 
 > [!NOTE]
 > The last two project (helm-project-operator and helm-locker) are not intended or supported for standalone use.
 
-For more info on _Helm Project Operator_, see the [dedicated README file](README-helm-project-operator.md).  
-For more info on _Helm Locker_, see the [dedicated README file](README-helm-locker.md).
+For more info on _Helm Project Operator_, see the [dedicated README file](cmd/helm-project-operator/README.md).  
+For more info on _Helm Locker_, see the [dedicated README file](cmd/helm-locker/README.md).
 
 ## Getting Started
 
@@ -20,18 +21,20 @@ For more information, see the [Getting Started guide](docs/prometheus-federator/
 ### Branches and Releases
 This is the current branch strategy for `rancher/prometheus-federator`, it may change in the future.
 
-| Branch         | Tag      | Rancher                |
-|----------------|----------|------------------------|
-| `main`         | `head`   | `main` branch (`head`) |
-| `release/v0.0` | `v0.x.x` | `v2.9.x`, `v2.8.x`     |
+| Branch         | Tag              | Rancher                |
+|----------------|------------------|------------------------|
+| `main` (v3.x)  | `head`, `v3.x.x` | `main` branch (`head`) |
+| `release/v1.x` | `v1.x.x`         | `v2.10.x`, `v2.9.x`    |
+| `release/v0.x` | `v0.x.x`         | Legacy Branch          |
 
 > [!NOTE]
-> We are starting our new Branch strategy officially in 2.10, the prior Rancher versions will receive updates to their new versions once cleared for backporting.
+> We are still adopting our new Branch strategy. Soon all Rancher Minors will have a branch targeting them.
+> When a Branch for v2.x is created 2.10 will be updated to use that rather than v1.x.
 
 
 ## More Info
 
-Prometheus Federator is an operator (powered by [`rancher/helm-project-operator`](README-helm-project-operator.md) and [`rancher/charts-build-scripts`](README-helm-locker.md)) that manages deploying one or more Project Monitoring Stacks composed of the following set of resources that are scoped to project namespaces:
+Prometheus Federator is an operator (powered by [`rancher/helm-project-operator`](cmd/helm-project-operator/README.md) and [`rancher/charts-build-scripts`](cmd/helm-locker/README.md)) that manages deploying one or more Project Monitoring Stacks composed of the following set of resources that are scoped to project namespaces:
 - [Prometheus](https://prometheus.io/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator))
 - [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) (managed externally by [Prometheus Operator](https://github.com/prometheus-operator/prometheus-operator))
 - [Grafana](https://github.com/helm/charts/tree/master/stable/grafana) (deployed via an embedded Helm chart)
@@ -47,12 +50,22 @@ For more information on ProjectHelmCharts and how to configure the underlying op
 For more information on how to configure the underlying Project Monitoring Stack, please read the [`README.md` of the underlying chart](packages/rancher-project-monitoring/charts/README.md) (`rancher-project-monitoring`).
 
 ## Developing
+For more information, see the [Developing guide](docs/prometheus-federator/developing.md).
 
 ### Which branch do I make changes on?
 
-Prometheus Federator is built and released off the contents of the `main` branch. To make a contribution, open up a PR to the `main` branch.
+This depends on the component of Prometheus Federator you're seeing to modify.
+Here's a good guide:
 
-For more information, see the [Developing guide](docs/prometheus-federator/developing.md).
+- Prometheus Federator directly: Target the `main` branch by default, unless change is specific to a Rancher Minor.
+- Rancher Project Monitoring:
+  1. Use the [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo `main` branch,
+  2. After chart updated in `ob-team-charts`, update `build.yaml` version on your target branch (likely main, then backport)
+
+### How do I know what version of Rancher Project Monitoring is used?
+There are a few options depending on where you're working.
+For compiled binaries, you can use the `debug-chart` command to dump the static chart.
+Or, you can check `build.yaml` on the target branch/tag you're curious about.
 
 ## Building
 

README-helm-locker.md → cmd/helm-locker/README.md

@@ -11,7 +11,11 @@ Once created, the Helm Locker controllers will watch all resources tracked by th
 
 ## Getting Started
 
-For more information, see the [Getting Started guide](docs/gettingstarted.md).
+For more information, see the [Getting Started guide](../../docs/helm-locker/gettingstarted.md).
+
+> [!WARN]
+> These directions are intended for development workflows/debugging.
+> They are not meant for standalone usage and come with no support.
 
 ## Who needs Helm Locker?
 

README-helm-project-operator.md → cmd/helm-project-operator/README.md

@@ -8,29 +8,34 @@ This repo contains a set of two interlinked projects:
 
 **Note: These project are not intended for standalone use.** 
 
-For more info on _Helm Locker_, see the [dedicated README file](README-helm-locker.md).
+For more info on _Helm Locker_, see the [dedicated README file](../helm-locker/README.md).
 
 Helm Project Operator is intended to be implemented by a Project Operator (e.g. [`rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator)) but provides a common definition for all Project Operators to use in order to support deploy specific, pre-bundled Helm charts (tied to a unique registered `spec.helmApiVersion` associated with the operator) across all project namespaces detected by this operator.
 
 ## Getting Started
 
-For more information, see the [Getting Started guide](docs/helm-project-operator/gettingstarted.md).
+For more information, see the [Getting Started guide](../../docs/helm-project-operator/gettingstarted.md).
+
+> [!WARN]
+> These directions are intended for development workflows/debugging.
+> They are not meant for standalone usage and come with no support.
+
 
 ## Developing
 
 ### Which branch do I make changes on?
 
 Helm Project Operator is built and released off the contents of the `main` branch. To make a contribution, open up a PR to the `main` branch.
 
-For more information, see the [Developing guide](docs/helm-project-operator/developing.md).
+For more information, see the [Developing guide](../../docs/helm-project-operator/developing.md).
 
 ## Design
 
-Helm Project Operator is built on top of [k3s-io/helm-controller](https://github.com/k3s-io/helm-controller) and [rancher/helm-locker](https://github.com/rancher/helm-locker). For more information on the design of the underlying components, please see the `README.md` on their respective repositories.
+Helm Project Operator is built on top of [k3s-io/helm-controller](https://github.com/k3s-io/helm-controller) and [rancher/helm-locker](https://github.com/rancher/prometheus-federator/tree/main/internal/helm-locker). For more information on the design of the underlying components, please see the `README.md` on their respective repositories.
 
 For an example of how Helm Project Operator can be implemented, please see [`rancher/prometheus-federator`](https://github.com/rancher/prometheus-federator).
 
-For more information in general, please see [docs/design.md](docs/helm-project-operator/design.md).
+For more information in general, please see [docs/design.md](../../docs/helm-project-operator/design.md).
 
 ## Building
 

docs/prometheus-federator/developing.md

@@ -1,68 +1,59 @@
 # Developing Prometheus Federator
 
-The Prometheus Federator repository is primarily comprised of just two things:
-- A simple `main.go` that implements [Helm Project Operator](https://github.com/rancher/helm-project-operator) for the [`rancher-project-monitoring` chart](charts/rancher-project-monitoring)
-- A `packages/` directory that corresponds to a [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) repository
+The Prometheus Federator project is primarily composed of two components:
+- The golang code that implements a [Helm Project Operator](../../cmd/helm-project-operator/README.md), and
+- The charts used for `rancher-project-monitoring` which are ultimately based on `rancher-monitoring`
+  - This component heavily relies on [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) and mimics a smaller `rancher/charts` for O&B team.
 
-In **most** circumstances, you will only ever have to make changes to the `packages/` directory; if you need to make changes to the underlying code of the operator that is deployed, it is likely that you intend to make this change in [rancher/helm-project-operator](https://github.com/rancher/helm-project-operator) instead.
+The golang half can be found here in this repo and the Charts half in our [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo.
 
-## Repository Structure
-
-```bash
-## This directory is a [`rancher/charts-build-scripts`](https://github.com/rancher/charts-build-scripts) packages directory. See below for more details.
-packages/
+In **most** circumstances, you will primarily make changes to the charts half and work in [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo first.
+Then, after that bump versions here in `build.yaml` and create your RC/alpha release after that. Finally, you can land that change in `rancher/charts`.
 
-## This directory contains **auto-generated** Helm chart archives that can be used to deploy Prometheus Federator in a Kubernetes cluster in 
-## the cattle-monitoring-system namespace, which deploys rancher-project-monitoring (located under charts/rancher-project-monitoring) 
-## on seeing a ProjectHelmChart with spec.helmApiVersion: monitoring.cattle.io/v1alpha1.
-##
-## IMPORTANT: You should never modify the contents of this directory directly; you should always modify `packages` since that will 
-## overwrite the changes that are observed in this directory on running a `make charts`.
-##
-assets/
+When you want to make changes to Prometheus Federator directly you do not need to interact with [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo.
 
-## This file is an **auto-generated** Helm index.yaml identifying this repository as a valid Helm repository that contains Helm charts.
-##
-## IMPORTANT: You should never modify the contents of this file directly; you should always modify `packages` since that will 
-## overwrite the changes that are observed in this directory on running a `make charts` or `make index`.
-##
-index.yaml
+## Repository Structure
 
-## This directory contains **auto-generated** Helm charts that can be used to deploy Prometheus Federator in a Kubernetes cluster in 
-## the cattle-monitoring-system namespace, which deploys rancher-project-monitoring (located under charts/rancher-project-monitoring) 
-## on seeing a ProjectHelmChart with spec.helmApiVersion: monitoring.cattle.io/v1alpha1.
+```bash
+## This directory contains the source chart for the Prometheus Federator chart.
 ##
-## IMPORTANT: You should never modify the contents of this directory directly; you should always modify `packages` since that will 
-## overwrite the changes that are observed in this directory on running a `make charts`.
-charts/
-
-  ## The main chart that deploys Prometheus Federator in the cluster.
-  prometheus-federator/*
-
-  ## A chart based on https://github.com/prometheus-community/helm-charts/tree/main/charts/kube-prometheus-stack that deploys a Project
-  ## Monitoring Stack onto the cluster on seeing a valid ProjectHelmChart (which means that it is contained within a Project Registration Namespace
-  ## with spec.helmApiVersion set to monitoring.cattle.io/v1alpha1)
-  ##
-  ## This chart is not expected to ever be deployed standalone; it is embedded into the Prometheus Federator binary itself.
-  rancher-project-monitoring/*
-
-## This directory will contain additional docs to assist users in getting started with using Helm Project Operator.
+## At build time it is used as a template to generate a 1:1 release chart to the image tag.
+## If you modify the Prometheus Federator chart you should consider if it needs to be back ported from `main` to other release branches.
+charts/prometheus-federator
+
+## This directory contains all CLI entry points of the Prometheus Federator (and internal projects)
+cmd/
+  ## The directory contains the helm-locker cli entrypoint used by devs.
+  helm-locker
+  ## The directory contains the helm-project-operator cli entrypoint used by devs.
+  helm-project-operator
+  ## The directory contains the prometheus-federator cli entrypoint
+  prometheus-federator
+
+## This directory will contain additional docs to assist users in getting started with using Prometheus Federator.
 docs/
 
 ## This directory contains an example ProjectHelmChart that can be deployed to create an example Project Monitoring Stack
 ## Note: the namespace needs to be modified to be a valid Project Registration Namespace, depending on how you deployed the operator.
 examples/
 
-## This directory contains the image that is used to build rancher/helm-project-operator, which is hosted on hub.docker.com.
+## This directory contains all the internal code used by Prometheus Federator
+internal/
+  ## The directory contains the helm-locker internal project code.
+  helm-locker
+  ## The directory contains the helm-project-operator internal project code.
+  helm-project-operator
+
+## This directory contains Dockerfile* to produce images for Prod and Dev
 package/
-  Dockerfile
+  Dockerfile-helm-locker
+  Dockerfile-helm-project-operator
+  Dockerfile-prometheus-federator
+```
 
-## The main entrypoint into Prometheus Federator that implements Helm Project Operator.
-main.go
+---
 
-## The Dockerfile used to run CI and other scripts executed by make in a Docker container (powered by https://github.com/rancher/dapper)
-Dockerfile.dapper
-```
+> TODO: Migrate the following content to [rancher/ob-team-charts](https://github.com/rancher/ob-team-charts) repo.
 
 ## Making changes to the Helm Charts (`packages/`)