Update/improve release guide (#770)

* Update CONTRIBUTING.md

Improve release instructions.

Signed-off-by: Pedro Ferreira <[email protected]>

* Update CONTRIBUTING.md

Signed-off-by: Pedro Ferreira <[email protected]>

* Update CONTRIBUTING.md

Signed-off-by: Pedro Ferreira <[email protected]>

* Update CONTRIBUTING.md

Signed-off-by: Pedro Ferreira <[email protected]>

* Run prettier

Signed-off-by: Pedro Ferreira <[email protected]>

CONTRIBUTING.md

@@ -70,33 +70,39 @@ If you would like to hack on MUI Toolpad or want to run the latest version, you
 
 ## Release process
 
-1. Generate a new version using
+1. Generate a new version using:
 
    ```sh
    yarn release:version
    ```
 
-1. Generate changelog using
+   This command will bump the version in every package of the project.
+
+1. Generate the changelog using:
 
    ```sh
    yarn release:changelog
    ```
 
-1. Clean the generated changelog, add highlights, use the new version number as title
+   Running this command requires a [Github personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with the `public_repo` scope.
+
+1. Copy the generated changelog from the console, clean it up, add a short summary of the release highlights and use the new version number as the title.
 
-1. prepend the changelog to [`CHANGELOG.md`](./CHANGELOG.md)
+1. Prepend the changelog to [`CHANGELOG.md`](./CHANGELOG.md).
 
-1. Open a PR with the proposed changes
+1. Open a PR with the proposed changes.
 
-1. Review/merge PR
+1. Review/merge the PR — once the PR is merged to `master` a Docker image is built for the commit, tagged with the commit SHA and then pushed to Docker Hub, just like for any other commit in `master`.
 
-1. Wait for the docker build to finish.
+1. Wait for the Docker build to finish.
 
-1. Release the docker image using:
+1. Release the Docker image using:
 
    ```sh
    # add --prerelease if necessary
    yarn release:docker
    ```
 
-1. Create a new github release, use `<version number>` as the tag and `<commit of merged PR>` as the target. Use the cleaned changelog as the body and the `<version number>` as the title. Mark as prerelease if necessary.
+   This command runs a Github action that retags the Docker image of the release commit in `master` to the version being released and also to "latest", and pushes those new tags. During the release, no new Docker images are created.
+
+1. [Create a new Github release](https://docs.github.com/en/repositories/releasing-projects-on-github). Use `<version number>` as the tag and `<commit of merged PR>` as the target. Use the cleaned changelog as the body and the `<version number>` as the title. Mark as prerelease if necessary.