docs: Document upgrading. Fixes argoproj#6076 (argoproj#6081)

docs/releasing.md

@@ -39,7 +39,7 @@ release branch. There should be a single release branch per minor release (e.g.
 
 ### 3. Prepare the Release
 
-#### NOTE: Releasing for `v2`
+> v2
 
 `v2` releases still depend on the previous repository name (`github.com/argoproj/argo`). To release for `v2`,
 make a local clone of the repository under the name `argo`:
@@ -56,6 +56,8 @@ Then follow all the normal steps. You should delete the `argo` folder once the r
 
 #### Preparing the release
 
+> Before v3.1
+
 1. Releasing requires a clean tree state, so back-up any untracked files in your Git directory.
 
  **Only once your files are backed up**, run:
@@ -83,8 +85,21 @@ Then follow all the normal steps. You should delete the `argo` folder once the r
 
 5. Wait 1h to 2h.
 
+> v3.1 and after
+
+Create and push a release tag:
+
+```
+git tag v3.1.0
+git push origin v3.1.0
+```
+
+The release will then be done automatically by a Github action.
+
 ### 4. Ensure the Release Succeeded
 
+> Before v3.1
+
 1. Check the images were pushed successfully. Ensure the `GitTreeState` is `Clean`.
  ```sh
  $ docker run argoproj/argoexec:v3.0.3 version
@@ -98,23 +113,33 @@ Then follow all the normal steps. You should delete the `argo` folder once the r
  $ ./dist/argo-darwin-amd64 version
  ```
 
-**Only in v3.0 and before**:
-
 1. Check the manifests contain the correct tags (search for `v3.0.3`): [https://raw.githubusercontent.com/argoproj/argo-workflows/v3.0.3/manifests/install.yaml](https://raw.githubusercontent.com/argoproj/argo-workflows/v3.0.3/manifests/install.yaml) 
 
 1. Check the manifests apply: `kubectl -n argo apply -f https://raw.githubusercontent.com/argoproj/argo-workflows/v3.0.3/manifests/install.yaml`
 
-### 5. Release Notes
+> v3.1 and after
 
-The change log is automatically generated.
+No action needed.
 
-The release title should be the version number (e.g. `v3.0.3`) and nothing else.
+### 5. Release Notes
 
-Release notes checklist:
+In [upgrading](upgrading.md), detail:
 
 * All breaking changes are listed with migration steps
 * The release notes identify every publicly known vulnerability with a CVE assignment
 
+The change log is automatically generated by a Github action.
+
+> Before v3.1
+
+The release title should be the version number (e.g. `v3.0.3`) and nothing else.
+
+Use hack/release-notes.md as the template for your new release notes.
+
+> v3.1 and after
+
+This is done automatically by a Github action.
+
 ### 6. Upload Binaries and SHA256 Sums To GitHub
 
 > Before v3.1
@@ -129,8 +154,14 @@ $ open dist
 
 Upload only the zipped binaries (`.gz` suffix) and SHA256 sums (`.sha256` suffix) to GitHub. There should be 12 uploaded files in total.
 
+> v3.1 and after
+
+This is done automatically by a Github action.
+
 ### 7. Update Stable Tag
 
+> Before v3.1
+
 If this is GA:
 
 Update the `stable` tag
@@ -142,6 +173,15 @@ git push -f origin stable
 
 Check the manifests contain the correct tags: [https://raw.githubusercontent.com/argoproj/argo-workflows/stable/manifests/install.yaml](https://raw.githubusercontent.com/argoproj/argo-workflows/stable/manifests/install.yaml)
 
+> v3.1 and after
+
+Delete the `stable` tag.
+
+```
+git tag -D stable
+git push origin :stable
+```
+
 ### 8. Update Homebrew
 
 If this is GA:
@@ -176,4 +216,10 @@ Check package published: [https://github.com/argoproj-labs/argo-client-java/pack
 
 ### 10. Publish Release
 
+> Before v3.1
+
 Finally, press publish on the GitHub release. Congrats, you're done!
+
+> v3.1 and after
+
+This is done automatically by a Github action. 

docs/upgrading.md

@@ -0,0 +1,50 @@
+# Upgrading
+
+Breaking changes typically (sometimes we don't realise they are breaking) have "!" in the commit message, as per
+the [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
+
+## Upgrading to v3.1
+
+### [3fff791e4](https://github.com/argoproj/argo-workflows/commit/3fff791e4ef5b7e1de82ccb36cae327e8eb726f6) build!: Automatically add manifests to `v*` tags (#5880)
+
+The manifests in the repository on the tag will longer contain the image tag, instead they contain `:latest`.
+
+* You must not get your manifests from the Git repository, you must get them from the release notes.
+* You must not use the `stable` tag. This is defunct, and will be removed in v3.1.
+
+## Upgrading to v3.0
+
+### [defbd600e](https://github.com/argoproj/argo-workflows/commit/defbd600e37258c8cdf30f64d4da9f4563eb7901) fix: Default ARGO_SECURE=true. Fixes #5607 (#5626)
+
+The server now starts with TLS enabled by default if a key is available. This can be disabled using `--secure=false`.
+
+If you have an ingress, you may need to add the appropriate annotations:(varies by ingress):
+
+```yaml
+alb.ingress.kubernetes.io/backend-protocol: HTTPS
+nginx.ingress.kubernetes.io/backend-protocol: HTTPS
+```
+
+### [01d310235](https://github.com/argoproj/argo-workflows/commit/01d310235a9349e6d552c758964cc2250a9e9616) chore(server)!: Required authentication by default. Resolves #5206 (#5211)
+
+To login to the user interface, you must provide a login token. This can be disabled with `--auth-mode=server`.
+
+### [f31e0c6f9](https://github.com/argoproj/argo-workflows/commit/f31e0c6f92ec5e383d2f32f57a822a518cbbef86) chore!: Remove deprecated fields (#5035)
+
+Some fields that were deprecated in early 2020 have been removed. 
+
+| Field | Action |
+|---|---|
+| template.template and template.templateRef | The workflow spec must be changed to use steps or DAG, otherwise the workflow will error. |
+| spec.ttlSecondsAfterFinished | change to `spec.ttlStrategy.secondsAfterCompletion`, otherwise the workflow will not be garbage collected as expected. |
+
+To find impacted workflows:
+
+```bash
+kubectl get wf --all-namespaces -o yaml | grep templateRef
+kubectl get wf --all-namespaces -o yaml | grep ttlSecondsAfterFinished
+```
+
+### [c8215f972](https://github.com/argoproj/argo-workflows/commit/c8215f972502435e6bc5b232823ecb6df919f952) feat(controller)!: Key-only artifacts. Fixes #3184 (#4618)
+
+This change is not breaking per-se, but many users do not appear to aware of [artifact repository ref](artifact-repository-ref.md).

hack/release-notes.md

@@ -4,6 +4,10 @@
 
 Find out on [our blog](https://blog.argoproj.io).
 
+## Breaking Changes and Known Issues
+
+See [upgrading](https://github.com/argoproj/argo-workflows/blob/master/docs/upgrading.md).
+
 ## Argo CLI
 
 ### Mac

mkdocs.yml

@@ -124,6 +124,7 @@ nav:
  - argo watch: cli/argo_watch.md
  - Operator Manual:
  - installation.md
+ - upgrading.md
  - releases.md
  - Configuration:
  - managed-namespace.md