Add end-of-life documentation + re-organize internal documentation (v…

…itessio#13401)

doc/internal/Overview.md → doc/internal/README.md

@@ -3,3 +3,5 @@
 The documents in this category document internal processes which are taken care of by the Vitess Team e.g. re-publishing the website [vitess.io](https://vitess.io) or creating a new release.
 
 We have put them here to increase transparency and make it easy for others to follow and improve processes.
+
+- [**Release Instructions**](./release/README.md)

doc/internal/release/README.md

@@ -0,0 +1,13 @@
+# Release Instructions
+
+This page describes the steps for cutting a new [open source release](https://github.com/vitessio/vitess/releases).
+
+### Summary
+
+- [Versioning](./versioning.md)
+- [Release Branches](./release-branches.md)
+- [Release Tags](./release-tags.md)
+- [Docker Images](./docker-images.md)
+- [Java Packages](./java-packages.md)
+- [Release Cutover](./release-cutover.md)
+- [End Of Life Process](./eol-process.md)

doc/internal/release/docker-images.md

@@ -0,0 +1,3 @@
+# Docker Images
+
+Docker images built automatically on DockerHub and can be found [here](https://hub.docker.com/repository/docker/vitess/lite/).

doc/internal/release/eol-process.md

@@ -0,0 +1,12 @@
+# End-of-Life Process
+
+The lifespan of a major version is one year long, after that time, the version has reached its end-of-life.
+To properly deprecate a major of Vitess follow the following steps:
+
+- **Update the website documentation**
+ > - In the ['Releases' documentation](https://vitess.io/docs/releases/), the EOL version must be moved under the ['Archived Releases' section](https://vitess.io/docs/releases/#archived-releases).
+ > - The sidebar of the website must be changed. We need to remove the EOL version from it. To do so, we move the version folder onto the `archive` folder.
+- **Delete the `Backport To: ...` label**
+ > - Delete the corresponding label for the EOL version, we do not want to motivate anymore backport to the EOL release branch.
+- **Make proper announcement on Slack**
+ > - Notify the community of this deprecation. 

doc/internal/release/java-packages.md

@@ -0,0 +1,27 @@
+# Java Packages
+
+We publish binary packages for our [JDBC driver and Java client on Maven Central](https://search.maven.org/#search|ga|1|g:"io.vitess").
+
+To do so, we use the http://oss.sonatype.org/ repository.
+New packages must be uploaded there ("deployed") and will be automatically published ("released").
+Once they are released there, they will be automatically synchronized with Maven Central.
+The synchronization takes only several minutes, but the update on http://search.maven.org may take up to two hours.
+
+## Access to oss.sonatype.org
+
+[Sign up here.](https://issues.sonatype.org/secure/Signup!default.jspa)
+Then you must be added as member to our `io.vitess` namespace.
+Therefore, file a JIRA ticket with Sonatype to get added ([example for a different namespace](https://issues.sonatype.org/browse/OSSRH-30604)).
+
+## One-time setup
+
+### Set up GPG
+
+Follow [Sonatype's GPG instructions](https://central.sonatype.org/pages/working-with-pgp-signatures.html).
+
+Install `gpg-agent` (needed below) e.g. on Ubuntu via: `sudo apt-get install gnupg-agent`.
+for Mac you need to install 'gnupg' via 'brew install gnupg'
+
+### Login configuration
+
+Create the `settings.xml` in the `$HOME/.m2/` directory as described in their [instructions](https://central.sonatype.org/pages/apache-maven.html).

doc/internal/release/release-branches.md

@@ -0,0 +1,17 @@
+# Release Branches
+
+Each major and minor releases (X.Y) should have a [release branch](https://github.com/vitessio/vitess/branches/all?query=release) named
+`release-X.Y`. This branch should diverge from `main` when the release
+is declared, after which point only bugfix PRs should be cherry-picked onto the branch.
+All other activity on `main` will go out with a subsequent major or minor release.
+
+```shell
+git checkout main
+git pull --ff-only upstream main
+
+git checkout -b release-X.Y
+git push upstream release-X.Y
+```
+
+The branches are named `release-X.Y` to distinguish them from point-in-time
+tags, which are named `vX.Y.Z`.

doc/internal/release/release-tags.md

@@ -0,0 +1,6 @@
+# Release Tags
+
+While the release branch is a moving target, release tags mark point-in-time
+snapshots of the repository. Essentially, a tag assigns a human-readable name to
+a specific Git commit hash. Although it's technically possible to reassign a tag
+name to a different hash, we must never do this.

doc/internal/release/versioning.md

@@ -0,0 +1,36 @@
+# Versioning
+
+Our versioning strategy is based on [VEP5](https://github.com/vitessio/enhancements/blob/main/veps/vep-5.md).
+
+## Major Release (vX)
+
+A new major release is needed when the public API changes in a
+backward-incompatible way -- for example, when removing deprecated interfaces.
+
+Our public API includes (but is not limited to):
+
+* The VTGate [RPC interfaces](https://github.com/vitessio/vitess/tree/main/proto).
+* The interfaces exposed by the VTGate client library in each language.
+
+Care must also be taken when changing the format of any data stored by a live
+system, such as topology data or Vitess-internal tables (used for sequences,
+distributed transactions, etc.). Although this data is considered as internal to
+Vitess, if any change breaks the upgrade path for a live system (for example,
+requiring that it be shut down and reinitialized from scratch), then it must be
+considered as a breaking change.
+
+## Minor Release (vX.Y)
+
+A new minor release indicates that functionality has been added or changed in a
+backward-compatible way. This should be the majority of normal releases.
+
+## Patch Release (vX.Y.Z)
+
+A patch release indicates that only a select set of bugfixes have been
+cherry-picked onto the associated minor release. The expectation is that
+upgrading by a patch release should be painless (not requiring any config
+changes) and safe (isolated from active development on `main`).
+
+## Pre-Release Labels (vX.Y.Z-labelN)
+
+Pre-release versions should be labeled with a suffix like `-beta2` or `-rc1`.