Add RELEASING.md docs (#3981)

Co-authored-by: Francisco Giordano <[email protected]>

Author: ernestognw

.github/workflows/release-cycle.yml

@@ -1,3 +1,15 @@
+#  D: Manual Dispatch
+#  M: Merge release PR
+#  C: Commit
+#  ┌───────────┐     ┌─────────────┐     ┌────────────────┐
+#  │Development├──D──►RC-Unreleased│  ┌──►Final-Unreleased│
+#  └───────────┘     └─┬─────────▲─┘  │  └─┬────────────▲─┘
+#                      │         │    │    │            │
+#                      M         C    D    M            C
+#                      │         │    │    │            │
+#                     ┌▼─────────┴┐   │   ┌▼────────────┴┐
+#                     │RC-Released├───┘   │Final-Released│
+#                     └───────────┘       └──────────────┘
 name: Release Cycle
 
 on:

CONTRIBUTING.md

@@ -29,6 +29,8 @@ Any non-trivial code contribution must be first discussed with the maintainers i
 
 Make sure to read and follow the [engineering guidelines](./GUIDELINES.md). Run linter and tests to make sure your pull request is good before submitting it.
 
+Changelog entries should be added to each pull request by using [Changesets](https://github.com/changesets/changesets/).
+
 When opening the pull request you will be presented with a template and a series of instructions. Read through it carefully and follow all the steps. Expect a review and feedback from the maintainers afterwards.
 
 If you're looking for a good place to start, look for issues labelled ["good first issue"](https://github.com/OpenZeppelin/openzeppelin-contracts/labels/good%20first%20issue)!

RELEASING.md

@@ -1,36 +1,47 @@
 # Releasing
 
-> Visit the documentation for [details about release schedule].
+> Visit the documentation for [details about release schedule](https://docs.openzeppelin.com/contracts/releases-stability).
 
-Start on an up-to-date `master` branch.
+OpenZeppelin Contracts uses a fully automated release process that takes care of compiling, packaging, and publishing the library, all of which is carried out in a clean CI environment (GitHub Actions), implemented in the ([`release-cycle`](.github/workflows/release-cycle.yml)) workflow. This helps to reduce the potential for human error and inconsistencies, and ensures that the release process is ongoing and reliable.
 
-Create the release branch with `npm run release start minor`.
+## Changesets
 
-Publish a release candidate with `npm run release rc`.
+[Changesets](https://github.com/changesets/changesets/) is used as part of our release process for `CHANGELOG.md` management. Each change that is relevant for the codebase is expected to include a changeset.
 
-Publish the final release with `npm run release final`.
+## Branching model
 
-Follow the general [OpenZeppelin Contracts release checklist].
+The release cycle happens on release branches called `release-vX.Y`. Each of these branches starts as a release candidate (rc) and is eventually promoted to final.
 
-[details about release schedule]: https://docs.openzeppelin.com/contracts/releases-stability
-[OpenZeppelin Contracts release checklist]: https://github.com/OpenZeppelin/code-style/blob/master/RELEASE_CHECKLIST.md
+A release branch can be updated with cherry-picked patches from `master`, or may sometimes be committed to directly in the case of old releases. These commits will lead to a new release candidate or a patch increment depending on the state of the release branch.
 
+```mermaid
+  %%{init: {'gitGraph': {'mainBranchName': 'master'}} }%%
+  gitGraph
+    commit id: "Feature A"
+    commit id: "Feature B"
+    branch release-vX.Y
+    commit id: "Start release"
+    commit id: "Release vX.Y.0-rc.0"
 
-## Merging the release branch
+    checkout master
+    commit id: "Feature C"
+    commit id: "Fix A"
 
-After the final release, the release branch should be merged back into `master`. This merge must not be squashed because it would lose the tagged release commit. Since the GitHub repo is set up to only allow squashed merges, the merge should be done locally and pushed.
+    checkout release-vX.Y
+    cherry-pick id: "Fix A" tag: ""
+    commit id: "Release vX.Y.0-rc.1"
+    commit id: "Release vX.Y.0"
 
-Make sure to have the latest changes from `upstream` in your local release branch.
+    checkout master
+    merge release-vX.Y
+    commit id: "Feature D"
+    commit id: "Patch B"
 
+    checkout release-vX.Y
+    cherry-pick id: "Patch B" tag: ""
+    commit id: "Release vX.Y.1"
+    
+    checkout master
+    merge release-vX.Y
+    commit id: "Feature E"
 ```
-git checkout release-vX.Y.Z
-git pull upstream
-```
-
-```
-git checkout master
-git merge --no-ff release-vX.Y.Z
-git push upstream master
-```
-
-The release branch can then be deleted on GitHub.