Add releasing packages documentation

docs/README.md

@@ -1,6 +1,9 @@
 # Build instructions
 
-To build the docs you must use Python 3.11.
+To build the docs you must install the following requirements:
+
+- GNU Make (Linux + Mac only)
+- Python 3.11
 
 To create a build environment run the following commands:
 ```python
@@ -9,7 +12,7 @@ source .venv/bin/activate
 pip install -r docs/requirements.txt
 
 cd docs
-make html
+make html # .\make html on Windows
 ```
 
 # Example Headers

docs/source/index.rst

@@ -15,6 +15,7 @@ Welcome to rez's documentation!
    getting_started
    basic_concepts
    building_packages
+   releasing_packages
    context
    variants
    guides/index

docs/source/releasing_packages.rst

@@ -0,0 +1,27 @@
+==================
+Releasing packages
+==================
+
+Rez packages can be built and deployed to the :data:`release_packages_path`
+using the :ref:`rez-release` tool. This tool performs the following actions:
+
+* All :doc:`actions <building_packages>` that the ``rez-build`` tool performs.
+* Executes all configured :data:`release_hooks`.
+* Executes all configured :gh-rez:`src/rezplugins/release_vcs` plugins.
+
+When to release vs build
+============================
+Packages *can* be installed to the :data:`release_packages_path` manually
+by running :option:`rez-build -i --prefix /path/to/repo <rez-build --prefix>`, so why would you use
+``rez-release``?
+
+Well, here are a few benefits of ``rez-release``:
+
+* The package will automatically go to the configured :data:`release_packages_path`, whereas :ref:`rez-build` will go to the :data:`local_packages_path` by default.
+* Tests being run by with the :ref:`rez-test` tool can run specifically prior to release, ensuring that releases pass any configured tests first.
+* Automatic sanity checks to ensure local repo is ready for release.
+* Automatic VCS tagging.
+* Many :ref:`helpful package attributes <release-package-attributes>` are automatically added to the released package definition file.
+
+If you're working locally, it these additional steps and checks may slow you
+down, so it may be better to stick with :ref:`rez-build`.

src/rez/rezconfig.py

@@ -824,7 +824,7 @@
 # a plugin listed here is not present, a warning message is printed. Note that a
 # release hook plugin being loaded does not mean it will run. It needs to be
 # listed here as well. Several built-in release hooks are available, see
-# rezplugins/release_hook.
+# :gh-rez:`src/rezplugins/release_hook`.
 release_hooks = []
 
 # Prompt for release message using an editor. If set to False, there will be