Porting across bloom documentation (#2375)

* Port across all of the bloom documentation from wiki.ros.org, updating it for ROS 2 in the process.

Signed-off-by: Kenji Brameld <[email protected]>
Co-authored-by: Chris Lalancette <[email protected]>

Author: ijnek

source/How-To-Guides.rst

@@ -34,7 +34,7 @@ If you are new and looking to learn the ropes, start with the :doc:`Tutorials <T
    How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback
    How-To-Guides/Working-with-multiple-RMW-implementations
    How-To-Guides/Cross-compilation
-   How-To-Guides/Releasing-a-ROS-2-package-with-bloom
+   How-To-Guides/Releasing/Releasing-a-Package
    How-To-Guides/Using-Python-Packages
    How-To-Guides/RQt-Port-Plugin-Windows
    How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers

source/How-To-Guides/Releasing-a-ROS-2-package-with-bloom.rst

@@ -0,0 +1,120 @@
+First Time Release
+==================
+
+This guide explains how to release ROS 2 packages that you have not released before.
+Due to numerous options available when releasing ROS packages, this guide intends to cover the most common scenario and does not cover every corner-case.
+
+.. contents:: Table of Contents
+   :depth: 1
+   :local:
+
+Be part of a release team
+-------------------------
+
+You must be part of a :ref:`release team <what-is-a-release-team>`.
+If you are not part of a release team yet, follow either:
+
+* :ref:`Join a release team <join-a-release-team>`
+* :ref:`Start a new release team <start-a-new-release-team>`
+
+Create a new release repository
+-------------------------------
+
+You need a :ref:`release repository <what-is-a-release-repository>` to release a package.
+Follow :ref:`Create a new release repository <create-a-new-release-repository>`.
+
+Install dependencies
+--------------------
+
+.. include:: _Install-Dependencies.rst
+
+Set Up a Personal Access Token
+------------------------------
+
+.. include:: _Personal-Access-Token.rst
+
+Ensure repositories are up-to-date
+----------------------------------
+
+.. include:: _Ensure-Repositories-Are-Up-To-Date.rst
+
+Generate Changelog
+------------------
+
+Generate a ``CHANGELOG.rst`` file per package in your repo using the following command:
+
+.. code-block:: bash
+
+   catkin_generate_changelog --all
+
+.. include:: _Clean-Up-Changelog.rst
+
+Bump the package version
+------------------------
+
+.. include:: _Bump-Package-Version.rst
+
+Bloom Release
+-------------
+
+Run the following command, replacing ``my_repo`` with the name of your repository:
+
+.. code-block:: bash
+
+  bloom-release --new-track --rosdistro {DISTRO} --track {DISTRO} my_repo
+
+.. tip::
+
+   * ``--new-track`` tells bloom to create a new :ref:`track <what-is-a-track>` and configure it.
+   * ``--rosdistro {DISTRO}`` indicates that this release is for the ``{DISTRO}`` distro
+   * ``--track {DISTRO}`` indicates that you want the track name to be ``{DISTRO}``
+
+
+You will be prompted to enter information to configure a new track.
+In a common scenario such as:
+
+* Your packages are in a repository called ``my_repo``
+* You are releasing a branch called ``main``
+* The repository is hosted on GitHub at ``https://github.com/my_organization/my_repo.git``
+* Your release repository is at ``https://github.com/ros2-gbp/my_repo-release.git``
+
+You should respond to the prompts as following:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 1 2
+
+   * - Configuration
+     - Value
+   * - :ref:`Release Repository url <release-repository-url>`
+     - ``https://github.com/ros2-gbp/my_repo-release.git``
+   * - :ref:`Repository Name <repository-name>`
+     - ``my_repo``
+   * - :ref:`Upstream Repository URI <upstream-repository-uri>`
+     - ``https://github.com/my_organization/my_repo.git``
+   * - :ref:`Upstream VCS Type <upstream-vcs-type>`
+     -
+   * - :ref:`Version <version>`
+     -
+   * - :ref:`Release Tag <release-tag>`
+     -
+   * - :ref:`Upstream Devel Branch <upstream-devel-branch>`
+     - ``main``
+   * - :ref:`ROS Distro <ros-distro>`
+     -
+   * - :ref:`Patches Directory <patches-directory>`
+     -
+   * - :ref:`Release Repository Push URL <release-repository-push-url>`
+     -
+
+.. note::
+
+  An empty cell in the table indicates that the default value should be used.
+  Simply respond to the prompt by pressing Enter.
+
+Bloom will automatically create a pull request for you against `rosdistro <https://github.com/ros/rosdistro>`_.
+
+Next Steps
+----------
+
+.. include:: _Next-Steps.rst

source/How-To-Guides/Releasing/First-Time-Release.rst

@@ -0,0 +1,80 @@
+Release Team / Repository
+=========================
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+This page explains the recommended method of hosting your release repositories on `ros2-gbp <https://github.com/ros2-gbp>`_.
+
+What is ROS 2 GBP?
+------------------
+
+`ros2-gbp <https://github.com/ros2-gbp>`_ is a GitHub organization that hosts the release repositories for ROS packages.
+It also maintains a list of release teams, the list of members per release team and the list of release repositories maintained by the release teams in https://github.com/ros2-gbp/ros2-gbp-github-org.
+Interactions with ros2-gbp-github-org are done through raising GitHub issues.
+It is recommended that you request to join a release team and set up a release repository early as it can take some time for the ros2-gbp maintainers to respond to your requests.
+
+.. _what-is-a-release-team:
+
+What is a release team?
+-----------------------
+
+A release team is a `GitHub team <https://docs.github.com/en/organizations/organizing-members-into-teams/about-teams>`_ that consists of a group of people who are responsible for the release process of one or more repositories.
+Release teams are often made up of an organization, a working group, or even an individual, and are named after the team or group that they represent.
+The list of release teams and their associated release repositories are maintained at `ros2-gbp-github-org <https://github.com/ros2-gbp/ros2-gbp-github-org>`_.
+
+**You must be a part of the release team that you are planning on releasing the project for.**
+If you intend to release the repository under an existing team, follow :ref:`Join a release team <join-a-release-team>`.
+If you intend to start a new team, follow :ref:`Start a new release team <start-a-new-release-team>`.
+
+.. _join-a-release-team:
+
+Join a release team
+^^^^^^^^^^^^^^^^^^^
+
+Fill the `Update Release Team Membership issue <https://github.com/ros2-gbp/ros2-gbp-github-org/issues/new?assignees=&labels=&template=update_release_team_membership.md&title=Update+release+team+membership>`_ issue template
+if a release team already exists for your project but you are not part of it.
+
+.. _start-a-new-release-team:
+
+Start a new release team
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill the `New Release Team issue <https://github.com/ros2-gbp/ros2-gbp-github-org/issues/new?assignees=&labels=&template=new_release_team.md&title=Add+release+team>`_ issue template
+if no release team exists for your project yet, request for a new release team to be created.
+
+.. _what-is-a-release-repository:
+
+What is a release repository?
+-----------------------------
+
+A release repository is a repository that
+
+* stores files generated from the release process, for the ROS buildfarm to use
+* caches configurations from the release process to simplify subsequent releases of the repository in the future
+
+Having a release repository separate from your source code repository is a requirement for making a release in ROS 2.
+
+.. _create-a-new-release-repository:
+
+Create a new release repository
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Fill the `Add New Release Repositories issue <https://github.com/ros2-gbp/ros2-gbp-github-org/issues/new?assignees=&labels=&template=new_release_repository.md&title=Add+new+release+repositories>`_ issue template
+if you don't have a release repo for your project yet.
+
+What if my existing release repo isn't on ros2-gbp?
+---------------------------------------------------
+
+Packages released before ros2-gbp existed may have their release repositories hosted elsewhere.
+It is now strongly recommended for release repositories to live in this dedicated GitHub organization.
+If you are porting a ROS 1 package to ROS 2 and planning on releasing your packages into ROS 2 for the first time, follow standard procedure to request for a new release repository for your ROS 2 releases.
+If you have previously released your packages for ROS 2, when raising the `Add New Release Repositories issue <https://github.com/ros2-gbp/ros2-gbp-github-org/issues/new?assignees=&labels=&template=new_release_repository.md&title=Add+new+release+repositories>`_, **specify your current release repository url**, and follow standard procedure for the rest.
+
+.. note::
+
+   Release repositories hosted elsewhere are still supported for stable distributions if you are not planning to release the repository into Rolling.
+   Since stable distributions created from Rolling will start with release repositories in the ros2-gbp organization it is recommend that you use the ros2-gbp release repositories for all ROS 2 distributions to avoid fragmenting the release information.
+
+   A ros2-gbp release repository may become a hard requirement in the future and maintaining a single release repository for all ROS 2 distributions simplifies the maintenance of releases for both the Rolling distribution maintainers and package maintainers.