docs: Updates docs for CII. See argoproj#2641 (argoproj#2643)

alexec · web-flow · commit cf277eb5114c · 2020-04-10T14:46:19.000-07:00
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -55,7 +55,7 @@ kubectl logs -n argo $(kubectl get pods -l app=workflow-controller -n argo -o na
 ```
 
 ---
-<!-- Issue Author: Don't delete this message to ecourage other users to support your issue! -->
+<!-- Issue Author: Don't delete this message to encourage other users to support your issue! -->
 **Message from the maintainers**:
 
 If you are impacted by this bug please add a 👍 reaction to this issue! We often sort issues this way to know what to prioritize.
diff --git a/.github/ISSUE_TEMPLATE/enhancement_proposal.md b/.github/ISSUE_TEMPLATE/enhancement_proposal.md
@@ -18,7 +18,7 @@ Please give examples of your use case, e.g. when would you use this.
 How do you think this should be implemented?
 
 ---
-<!-- Issue Author: Don't delete this message to ecourage other users to support your issue! -->
+<!-- Issue Author: Don't delete this message to encourage other users to support your issue! -->
 **Message from the maintainers**:
 
 If you wish to see this enhancement implemented please add a 👍 reaction to this issue! We often sort issues this way to know what to prioritize.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -2,6 +2,7 @@ Checklist:
 
 * [ ] Either (a) I've created an [enhancement proposal](https://github.com/argoproj/argo/issues/new/choose) and discussed it with the community, (b) this is a bug fix, or (c) this is a chore.
 * [ ] The title of the PR is (a) [conventional](https://www.conventionalcommits.org/en/v1.0.0/), (b) states what changed, and (c) suffixes the related issues number. E.g. `"fix(controller): Updates such and such. Fixes #1234"`.  
-* [ ] I have written unit and/or e2e tests for my change. PRs without these are unlike to be merged.
-* [ ] Optional. I've added My organization is added to the USERS.md.
-* [ ] I've signed the CLA and required builds are green. 
+* [ ] I've signed the CLA.
+* [ ] I have written unit and/or e2e tests for my change. PRs without these are unlikely to be merged.
+* [ ] My builds are green. Try syncing with master if they are not. 
+* [ ] My organization is added to USERS.md.
diff --git a/README.md b/README.md
@@ -1,4 +1,7 @@
 [![slack](https://img.shields.io/badge/slack-argoproj-brightgreen.svg?logo=slack)](https://argoproj.github.io/community/join-slack)
+[![CircleCI](https://circleci.com/gh/argoproj/argo.svg?style=svg)](https://circleci.com/gh/argoproj/argo)
+[![codecov](https://codecov.io/gh/argoproj/argo/branch/master/graph/badge.svg)](https://codecov.io/gh/argoproj/argo)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=argoproj_argo&metric=alert_status)](https://sonarcloud.io/dashboard?id=argoproj_argo)
 
 # Argoproj - Get stuff done with Kubernetes
 
diff --git a/SECURITY.md b/SECURITY.md
@@ -0,0 +1,17 @@
+# Security 
+
+## Reporting Vulnerabilities
+
+Please report security vulnerabilities by e-mailing:
+
+* [Jesse_Suen@intuit.com](mailto:Jesse_Suen@intuit.com)
+* [Alex_Collins@intuit.com](mailto:Alex_Collins@intuit.com)
+* [Edward_Lee@intuit.com](mailto:Edward_Lee@intuit.com)
+
+## Public Disclosure
+
+Security vulnerabilities will be disclosed via [release notes](docs/releasing.md).
+
+## Vulnerability Scanning
+
+See [static code analysis](static-code-analysis.md).
diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -1,85 +1,25 @@
-# How to setup your dev environment
-## Pre-requisites:
+# Contributing
 
-* Dep. `brew install dep`
-* Golang
-* Yarn. `brew install yarn`
-* Docker
-* [Kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md)
-* [protoc](http://google.github.io/proto-lens/installing-protoc.html) `brew install protoc`
-* `jq`
-* [Swagger codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/) `brew install swagger-codegen`
-* Kubernetes Cluster (we recommend Docker for Desktop + K3D, as this will allow you to test RBAC set-up, and is also fast)
+## How To Provide Feedback
 
-Useful:
+Please [raise an issue in Github](https://github.com/argoproj/argo/issues).
 
-* For a PS1 prompt showing your current kube context: kube-ps1 to help.  `brew install kube-ps1`
-* For tailing logs: Stern. `brew install stern`
+## Code of Conduct
 
-K3D tip: You can set-up K3D to be part of your default kube config as follows
+See [code of conduct](../CODE_OF_CONDUCT.md).
 
-    cp ~/.kube/config ~/.kube/config.bak
-    cat $(k3d get-kubeconfig --name='k3s-default') >> ~/.kube/config
+## How To Contribute
 
-To install into the “argo” namespace of your cluster: Argo, MinIO (for saving artifacts and logs) and Postgres (for offloading or archiving):
+We're always looking for contributors. 
 
-    make start 
+* Documentation - something missing or unclear? Please submit a pull request!
+* Code contribution - investigate a [help wanted issue](https://github.com/argoproj/argo/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+label%3A%22good+first+issue%22), or anything labelled with "good first issue"?
+* Join the #argo-devs channel on [our Slack](https://argoproj.github.io/community/join-slack).
 
-If you prefer MySQL:
+### Running Locally
 
-	make start DB=mysql
+To run Argo Workflows locally for development: [running locally](running-locally.md).
 
-To expose the services port forwards:
+### Test Policy
 
-	make pf
-
-You’ll now have
-
-* Argo on http://localhost:2746 (see below)
-* MinIO  http://localhost:9000 (use admin/password)
-
-Either:
-
-* Postgres on  http://localhost:5432, run `make postgres-cli` to access.
-* MySQL on  http://localhost:3306, run `make mysql-cli` to access.
-
-You need the token to access the CLI or UI:
-
-    eval $(make env)
-
-    ./dist/argo auth token
-
-At this point you’ll have everything you need to use the CLI and UI.
-
-Tip: If you want to make UI changes without a time-consuming build:
-
-    cd ui
-    yarn install
-    yarn start
-
-The UI will start up on http://localhost:8080.
-
-If you want to run controller or argo-server in your IDE (e.g. so you can debug it):
-
-Add to /etc/hosts:
-
-    127.0.0.1 postgres
-    127.0.0.1 mysql
-
-Scale down the services you want to debug:
-
-    kubectl -n argo scale deploy/workflow-controller --replicas 0
-    kubectl -n argo scale deploy/argo-server --replicas 0
-
-Restart the port forwarding:
-
-    make pf
-
-To find the command arguments you need to use, you’ll have to look at dist/postgres.yaml (or dist/mysql.yaml for MySQL aficionados).
-
-## Clean
-
-To clean-up everything:
-
-    kubectl delete ns argo
-    make clean
+Changes without either unit or e2e tests are unlikely to be accepted. See [the pull request template](../.github/pull_request_template.md.)
diff --git a/docs/argo-server.md b/docs/argo-server.md
@@ -1,6 +1,6 @@
 # Argo Server
 
-![alpha](assets/alpha.svg)
+![GA](assets/ga.svg)
 
 > v2.5 and after
 
diff --git a/docs/cli.md b/docs/cli.md
@@ -8,7 +8,7 @@ argo --help
 
 # Argo Server
 
-![alpha](assets/alpha.svg)
+![GA](assets/ga.svg)
 
 > v2.5 and after
 
diff --git a/docs/cron-workflows.md b/docs/cron-workflows.md
@@ -1,6 +1,6 @@
 # Cron Workflows
 
-![alpha](assets/alpha.svg)
+![GA](assets/ga.svg)
 
 > v2.5 and after
 
diff --git a/docs/managed-namespace.md b/docs/managed-namespace.md
@@ -1,6 +1,6 @@
 # Managed Namespace
 
-![alpha](assets/alpha.svg)
+![GA](assets/ga.svg)
 
 > v2.5 and after
 
diff --git a/docs/public-api.md b/docs/public-api.md
@@ -0,0 +1,10 @@
+# Public API
+
+Argo Workflows public API is defined by the following:
+
+* The file `api/openapi-spec/swagger.json`
+* The schema of the table `argo_archived_workflows`.
+
+See:
+
+* [Versioning](versioning.md)
diff --git a/docs/releasing.md b/docs/releasing.md
@@ -6,44 +6,29 @@ Allow 1h to do a release.
 
 Cherry-pick your changes from master onto the release branch.
 
-Mandatory: the release branch must be green [in CircleCI](https://app.circleci.com/github/argoproj/argo/pipelines).
-
-It is a very good idea to clean up before you start:
-
-    make clean
-    kubectl delete ns argo
+The release branch should be green [in CircleCI](https://app.circleci.com/github/argoproj/argo/pipelines) before you start.
 
 ## Release
 
 To generate new manifests and perform basic checks:
 
-    make prepare-release VERSION=v2.5.0-rc6
-
-Next, build everything:
-
-    make build
+    make prepare-release VERSION=v2.7.2
 
 Publish the images and local Git changes:
 
     make publish-release
 
 Create [the release](https://github.com/argoproj/argo/releases) in Github. You can get some text for this using [Github Toolkit](https://github.com/alexec/github-toolkit):
 
-    ght relnote v2.5.0-rc5..v2.5.0-rc6
-
-    
-## Validation
-
-K3D tip: you'll need to import the images:
-
-    k3d import-images argoproj/argocli:v2.5.0-rc6 argoproj/argoexec:v2.5.0-rc6 argoproj/workflow-controller:v2.5.0-rc6
+    ght relnote v2.7.1..v2.7.2
 
-Install Argo locally:
+Release notes checklist:
 
-    kubectl create ns argo
-    kubectl apply -n argo -f https://raw.githubusercontent.com/argoproj/argo/v2.5.0-rc6/manifests/quick-start-postgres.yaml
-    make pf-bg 
+* [ ] All breaking changes are listed with migration steps
+* [ ] The release notes identify every publicly known vulnerability with a CVE assignment 
 
-Maybe run e2e tests?
+If this is GA:
 
-    make test-e2e
+* [ ] Update the `stable` tag
+* [ ] Update the [Homebrew tap](https://github.com/argoproj/homebrew-tap).
+ 
diff --git a/docs/resource-duration.md b/docs/resource-duration.md
@@ -2,6 +2,8 @@
 
 ![alpha](assets/alpha.svg)
 
+> v2.7 and after
+
 Argo Workflows provides an indication of how much resource your workflow has used and saves this 
 information. This is intended to be an **indicative but not accurate** value.
 
diff --git a/docs/rest-api.md b/docs/rest-api.md
@@ -2,7 +2,7 @@
 
 ## Argo Server API
 
-![alpha](assets/alpha.svg)
+![GA](assets/ga.svg)
 
 > v2.5 and after
 
diff --git a/docs/running-locally.md b/docs/running-locally.md
@@ -0,0 +1,85 @@
+# How to setup your dev environment
+## Pre-requisites:
+
+* Dep. `brew install dep`
+* Golang
+* Yarn. `brew install yarn`
+* Docker
+* [Kustomize](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md)
+* [protoc](http://google.github.io/proto-lens/installing-protoc.html) `brew install protoc`
+* `jq`
+* [Swagger codegen](https://swagger.io/docs/open-source-tools/swagger-codegen/) `brew install swagger-codegen`
+* Kubernetes Cluster (we recommend Docker for Desktop + K3D, as this will allow you to test RBAC set-up, and is also fast)
+
+Useful:
+
+* For a PS1 prompt showing your current kube context: kube-ps1 to help.  `brew install kube-ps1`
+* For tailing logs: Stern. `brew install stern`
+
+K3D tip: You can set-up K3D to be part of your default kube config as follows
+
+    cp ~/.kube/config ~/.kube/config.bak
+    cat $(k3d get-kubeconfig --name='k3s-default') >> ~/.kube/config
+
+To install into the “argo” namespace of your cluster: Argo, MinIO (for saving artifacts and logs) and Postgres (for offloading or archiving):
+
+    make start 
+
+If you prefer MySQL:
+
+	make start DB=mysql
+
+To expose the services port forwards:
+
+	make pf
+
+You’ll now have
+
+* Argo on http://localhost:2746 (see below)
+* MinIO  http://localhost:9000 (use admin/password)
+
+Either:
+
+* Postgres on  http://localhost:5432, run `make postgres-cli` to access.
+* MySQL on  http://localhost:3306, run `make mysql-cli` to access.
+
+You need the token to access the CLI or UI:
+
+    eval $(make env)
+
+    ./dist/argo auth token
+
+At this point you’ll have everything you need to use the CLI and UI.
+
+Tip: If you want to make UI changes without a time-consuming build:
+
+    cd ui
+    yarn install
+    yarn start
+
+The UI will start up on http://localhost:8080.
+
+If you want to run controller or argo-server in your IDE (e.g. so you can debug it):
+
+Add to /etc/hosts:
+
+    127.0.0.1 postgres
+    127.0.0.1 mysql
+
+Scale down the services you want to debug:
+
+    kubectl -n argo scale deploy/workflow-controller --replicas 0
+    kubectl -n argo scale deploy/argo-server --replicas 0
+
+Restart the port forwarding:
+
+    make pf
+
+To find the command arguments you need to use, you’ll have to look at dist/postgres.yaml (or dist/mysql.yaml for MySQL aficionados).
+
+## Clean
+
+To clean-up everything:
+
+    kubectl delete ns argo
+    make clean
diff --git a/docs/static-code-analysis.md b/docs/static-code-analysis.md
@@ -0,0 +1,10 @@
+# Static Code Analysis
+
+We use the following static code analysis tools:
+
+* golangci-lint and tslint for compile time linting
+* [codecov.io](https://codecov.io/gh/argoproj/argo) - for code coverage
+* [snyk.io](https://app.snyk.io/org/argoproj/projects) - for image scanning
+* [sonarcloud.io](https://sonarcloud.io/organizations/argoproj/projects) - for code scans and security alerts
+
+These are at least run daily or on each pull request.
diff --git a/docs/versioning.md b/docs/versioning.md
@@ -0,0 +1,9 @@
+# Versioning
+
+Argo Workflows does not use Semantic Versioning, even though we have not introduced any breaking changes since v2.
+
+Breaking changes will be communicated in the release notes.
+
+See:
+
+* [Public API](public-api.md)
diff --git a/docs/workflow-archive.md b/docs/workflow-archive.md
@@ -1,6 +1,6 @@
 # Workflow Archive
 
-![alpha](assets/alpha.svg)
+![beta](assets/beta.svg)
 
 > v2.5 and after
 
