docs: README updates (#162)

* docs: README updates

Signed-off-by: Michael Crenshaw <[email protected]>

* period

Signed-off-by: Michael Crenshaw <[email protected]>

* conventions matter

Signed-off-by: Michael Crenshaw <[email protected]>

* conventions matter

Signed-off-by: Michael Crenshaw <[email protected]>

---------

Signed-off-by: Michael Crenshaw <[email protected]>

Author: crenshaw-dev

README.md

@@ -15,7 +15,32 @@ The main ideas behind the project are explained in ["Space Age GitOps: The Rise
 
 A live demo is presented in ["Space Age GitOps: Lifting off with Argo Promotions"](https://www.youtube.com/watch?v=2JmLCqM1nTM).
 
+## Example
+
+```yaml
+apiVersion: promoter.argoproj.io/v1alpha1
+kind: PromotionStrategy
+metadata:
+  name: example-promotion-strategy
+spec:
+  gitRepositoryRef:
+    name: example-git-repo
+  activeCommitStatuses:
+    - key: argocd-app-health
+  proposedCommitStatuses:
+    - key: security-scan
+  environments:
+    - branch: environment/dev
+    - branch: environment/test
+    - branch: environment/prod
+      autoMerge: false
+      activeCommitStatuses:
+      - key: performance-test
+      proposedCommitStatuses:
+      - key: deployment-freeze
+```
+
 ## Getting Started
 
-The project does not have an initial release yet. Peruse [Makefile](Makefile) to get started tinkering and testing. To
-understand more about how the project works, check out [the documentation](https://argo-gitops-promoter.readthedocs.io/en/latest/).
+The project is currently experimental, please use with caution. See the 
+[docs site](https://argo-gitops-promoter.readthedocs.io/en/latest/getting-started/) for setup instructions.

docs/example-resources/ChangeTransferPolicy.yaml

@@ -5,8 +5,8 @@ metadata:
 spec:
   gitRepositoryRef:
     name: example-git-repository
-  proposedBranch: env/dev-next
-  activeBranch: env/dev
+  proposedBranch: environment/dev-next
+  activeBranch: environment/dev
   activeCommitStatuses:
   - key: argocd-app-health
   proposedCommitStatuses:

docs/example-resources/PromotionStrategy.yaml

@@ -10,17 +10,17 @@ spec:
   proposedCommitStatuses:
     - key: security-scan
   environments:
-    - branch: env/dev
-    - branch: env/test
-    - branch: env/prod
+    - branch: environment/dev
+    - branch: environment/test
+    - branch: environment/prod
       autoMerge: false
       activeCommitStatuses:
       - key: performance-test
       proposedCommitStatuses:
       - key: deployment-freeze
 status:
   environments:
-  - branch: env/dev
+  - branch: environment/dev
     active:
       dry:
         sha:
@@ -36,7 +36,7 @@ status:
     lastHealthyDryShas:
     - sha:
       time:
-  - branch: env/test
+  - branch: environment/test
     # same fields as dev
-  - branch: env/prod
+  - branch: environment/prod
     # same fields as dev

docs/gating-promotions.md

@@ -24,29 +24,29 @@ spec:
   activeCommitStatuses:
     - key: healthy
   environments:
-    - branch: env/dev
-    - branch: env/stg
-    - branch: env/prd
+    - branch: environment/dev
+    - branch: environment/test
+    - branch: environment/prod
       proposedCommitStatuses:
         - key: deployment-freeze
 ```
 
-In this example, the PromotionStrategy has three environments: `env/dev`, `env/stg`, and `env/prd`. All environments
-have a `healthy` active commit status check. The `env/prd` environment has an additional `deployment-freeze` proposed
+In this example, the PromotionStrategy has three environments: `environment/dev`, `environment/test`, and `environment/prod`. All environments
+have a `healthy` active commit status check. The `environment/prod` environment has an additional `deployment-freeze` proposed
 commit status check.
 
 Suppose the environment branches have been hydrated from the `main` branch and that the branches have the following
 commit SHAs:
 
-| Branch         | SHA      |
-|----------------|----------|
-| `main`         | `b5d8f7` |
-| `env/dev`      | `a1b2c3` |
-| `env/dev-next` | `d4e5f6` |
-| `env/stg`      | `a7b8c9` |
-| `env/stg-next` | `d0e1f2` |
-| `env/prd`      | `a3b4c5` |
-| `env/prd-next` | `d6e7f8` |
+| Branch                  | SHA      |
+|-------------------------|----------|
+| `main`                  | `b5d8f7` |
+| `environment/dev`       | `a1b2c3` |
+| `environment/dev-next`  | `d4e5f6` |
+| `environment/test`      | `a7b8c9` |
+| `environment/test-next` | `d0e1f2` |
+| `environment/prod`      | `a3b4c5` |
+| `environment/prod-next` | `d6e7f8` |
 
 For a change to be promoted through all environments, the following CommitStatuses must exist:
 
@@ -56,31 +56,31 @@ metadata:
   labels:
     promoter.argoproj.io/commit-status: healthy
 spec:
-  sha: a1b2c3  # env/dev
+  sha: a1b2c3  # environment/dev
   phase: success
 ---
 kind: CommitStatus
 metadata:
   labels:
     promoter.argoproj.io/commit-status: healthy
 spec:
-  sha: a7b8c9  # env/stg
+  sha: a7b8c9  # environment/test
   phase: success
 ---
 kind: CommitStatus
 metadata:
   labels:
     promoter.argoproj.io/commit-status: healthy
 spec:
-  sha: a3b4c5  # env/prd
+  sha: a3b4c5  # environment/prod
   phase: success
 ---
 kind: CommitStatus
 metadata:
   labels:
     promoter.argoproj.io/commit-status: deployment-freeze
 spec:
-  sha: d6e7f8  # env/prd-next
+  sha: d6e7f8  # environment/prod-next
   phase: success
 ```
 
@@ -106,8 +106,8 @@ So for the above example, the stg environment's ChangeTransferPolicy CR will loo
 ```yaml
 kind: ChangeTransferPolicy
 spec:
-  sourceBranch: env/stg-next
-  targetBranch: env/stg
+  sourceBranch: environment/test-next
+  targetBranch: environment/test
   activeCommitStatuses:
     # The controller will monitor this CommitStatus for the active commit SHA, but it will not enforce it. The status 
     # will be stored on the 
@@ -117,7 +117,7 @@ spec:
     - key: promoter-previous-environment
 ```
 
-Assuming the `env/dev` environment has a `healthy` active commit status check, the `promoter-previous-environment`
+Assuming the `environment/dev` environment has a `healthy` active commit status check, the `promoter-previous-environment`
 CommitStatus will look like this:
 
 ```yaml
@@ -126,10 +126,10 @@ metadata:
   labels:
     promoter.argoproj.io/commit-status: promoter-previous-environment
 spec:
-  sha: d0e1f2  # env/stg-next
+  sha: d0e1f2  # environment/test-next
   phase: success
 ```
 
-Even though the CommitStatus is "about" the `env/dev` branch, the SHA is the SHA of the `env/stg-next` branch. This is
+Even though the CommitStatus is "about" the `environment/dev` branch, the SHA is the SHA of the `environment/test-next` branch. This is
 how the PromotionStrategy controller expresses its opinion of the proposed commit on the stg environment, i.e. that it
 is acceptable because the previous environment is healthy.