[pitivi] Update release instructions

[Alexandru Băluț <alexbalut src gnome org>]

commit e7a8d4c7f50ae41eec82fb94adb677920d1ad8f4
Author: Alexandru Băluț <alexandru balut gmail com>
Date:   Sat Jul 1 11:23:09 2017 +0200

    Update release instructions
    
    Reviewers: thiblahute
    
    Maniphest Tasks: T7757
    
    Differential Revision: https://phabricator.freedesktop.org/D1765

 docs/release.md |   66 +++++++++++++++++++++++++++++++++++-------------------
 1 files changed, 43 insertions(+), 23 deletions(-)
---
diff --git a/docs/release.md b/docs/release.md
index bcb35b6..e97d4e9 100644
--- a/docs/release.md
+++ b/docs/release.md
@@ -1,15 +1,13 @@
----
-title: Releasing
-short_description: How to make a release
-...
-
 # How to make a release
 
-See also https://live.gnome.org/MaintainersCorner/Releasing
+Ideally these instructions are in line with the [GNOME releasing 
process](https://live.gnome.org/MaintainersCorner/Releasing).
+
+We make two types of releases:
+- regular releases, when we have new features or improvements, and
+- "smaller" bug-fix releases, when a regular relese needs patching.
 
-Besides the regular releases, you can also make smaller bug-fix releases.
 The regular releases have the version number X.YY, and the bug-fix
-releases have the version number X.YY.Z, where Z is a relatively small
+releases have the version number X.YY.Z, where Z is hopefully a relatively small
 number (1, 2, 3...).
 
 Most of the steps below should be done in the [development environment](HACKING.md): `$ source 
bin/pitivi-env` -> `(ptv-flatpak) $`
@@ -24,18 +22,22 @@ Most of the steps below should be done in the [development environment](HACKING.
    * See our current requirement for Gst at the bottom in [check.py](../pitivi/check.py)
    * If they are different, update the files which contain the old version, for example: `$ git grep 
"1\.8\.2"` and `$ git commit -a -m "Use GStreamer <gstreamer-version>"`
 
- 3. Check your local repository
+ 3. Check your local repository:
    * Make sure your sandbox is using the latest GStreamer release: `$ ptvenv --update 
--gst-version=<gst-version>`
-   * `$ git status` does not show any change
-   * `$ configure` is all green
+   * Install git-archive-all in your sandbox to be able to create the archive to be distributed: `$ 
build/flatpak/py-configure --module=git-archive-all && make install`
+   * Check `$ git status` does not show any change
+   * Check `$ ptvenv ./configure` is all green
 
- 4. Make sure the tests pass
-   * `$ ninja test`
-   <!-- * `$ make validate` FIXME! -->
+ 4. Make sure the tests pass:
+  ```
+  $ ninja -C mesonbuild/ test
+  ```
+ <!-- * `$ make validate` FIXME! -->
 
  5. Update the following files:
    * [meson.build](../meson.build):
-Only if doing a regular release. Bump YY up and remove the micro from
+If doing a bugfix release, add or increase the micro.
+If doing a regular release, bump YY up and remove the micro from
 the version number, for example: 0.97.1 -> 0.98. Normally this is the
 same as the name of the Phabricator milestone you just archived.
    * [RELEASE](../RELEASE):
@@ -49,16 +51,34 @@ If there are new maintainers.
 
  6. Commit the changes: `$ git commit -a -m "Release <version-number>"`
 
- 7. Create the distribution archive
-   * `$ cd mesonbuild && ninja dist && cd .. && ls *.tar.gz`
-   * Install it on your favorite system, check that it works.
-
- 8. Create a tag: `$ git tag -a <version-number> -m "Release <version-number>"`
- 9. Push the tag to the official repository: `$ git push origin <version-number>`
+ 7. Create the distribution archive, install it on your favorite system and check that it works:
+   * `$ ninja -C mesonbuild/ dist && ls *.tar.gz`
+   * For Archlinux try:
+ ```
+ $ cd /tmp
+ $ asp checkout pitivi
+ $ cd /tmp/pitivi/repos/community-x86_64/
+ $ rm -rf .git  # Without this, ./configure is confused re version number.
+ $ cp .../pitivi-X.YY.Z.tar.gz .
+ $ vim PKGBUILD
+ ... Update "pkgver",
+ ... Make sure "source" ends in .tar.gz
+ ... Update "sha256sums"
+ $ makepkg
+ $ makepkg -i
+ $ pitivi
+ ```
+
+ 8. Create a tag and push it to the official repository. The TAG must always include the micro. This means 
when doing a regular release with version number X.YY, the TAG is X.YY.0. When doing a bug-fix release, the 
version number already includes a micro, so it's all fine.
+   ```
+   $ git tag -a <TAG> -m "Release <version-number>"
+   $ git push origin <TAG>
+   ```
+   We use tag X.YY.0 instead of X.YY because we want to have the option of later creating the X.YY branch to 
the official repository, since it's not possible to have both a tag and a branch with the same name. This 
branch would be used to gather backported fixes and be the official branch for doing a X.YY.Z bug-fix release.
 
  10. Publish the archive
-   * `$ scp pitivi-X.YY.ZZ.tar.gz master.gnome.org:`
-   * On master.gnome.org, run `$ ftpadmin install pitivi-X.YY.ZZ.tar.gz`
+   * `$ scp pitivi-X.YY.Z.tar.gz USER master gnome org:`
+   * On master.gnome.org, run `$ ftpadmin install pitivi-X.YY.Z.tar.gz`
      The tarball will appear as `.tar.xz` on https://download.gnome.org/sources/pitivi/X.YY/ (also visible 
on http://ftp.gnome.org/pub/gnome/sources/pitivi/X.YY/)
 
  11. Send out an announcement mail to: