Skip to content

Commit 1d909df

Browse files
SteveMacenskiSteveMacenski
authored
Adding maintainer release docs (#693)
* Adding maitnainer release docs Signed-off-by: Steve Macenski <stevenmacenski@gmail.com> * Update distribution_release.rst Signed-off-by: Steve Macenski <stevenmacenski@gmail.com> --------- Signed-off-by: Steve Macenski <stevenmacenski@gmail.com>
1 parent f74cf92 commit 1d909df

3 files changed

Lines changed: 163 additions & 0 deletions

File tree

‎index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -204,3 +204,4 @@ IEEE/RSJ International Conference on Intelligent Robots and Systems (IROS), 2021
204204
commander_api/index.rst
205205
roadmap/roadmap.rst
206206
about/index.rst
207+
maintainer_docs/index.rst

‎maintainer_docs/distribution_release.rst‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
.. _distribution_release_docs:
2+
3+
ROS Distribution Release Process
4+
################################
5+
6+
This is the instructions for releasing a new Nav2 version for a ROS distribution release.
7+
8+
.. note::
9+
10+
We require ``osrf/ros:<distro>-desktop-full`` images to exist for a distribution before this process may be completed.
11+
This usually means we wait until the release date to perform Nav2's release and have it included in the first distribution sync.
12+
13+
14+
15+
0. Initial Freeze
16+
-----------------
17+
18+
Look at the ROS 2 timeline for release and decide on a date to freeze Nav2 new contributions.
19+
Mark any open tickets and/or pull requests with a new tag ``<distro>-release`` that we want to get in before the branch off.
20+
These are the actions items to focus on before the chosen release date which would block release on time.
21+
22+
These tickets or pull requests should represent major features, meaningful bug fixes, or ABI/API breaking changes that are necessary to be included before the branch off so that those feature(s) or API change(s) are represented in the new distribution.
23+
24+
1. Local Functional Testing
25+
---------------------------
26+
27+
Once pre-release images are available on `ros_oci_images <https://github.com/sloretz/ros_oci_images>`_, locally pull this docker image
28+
In a workspace root containing Nav2 and ``nav2_minimal_turtlebot_simulations``, run the following:
29+
30+
.. code:: bash
31+
32+
sudo docker pull ghcr.io/sloretz/ros-testing:<distro>-desktop-full
33+
34+
sudo docker run -it --net=host --privileged -v .:/root/jazzy_ws --volume="${XAUTHORITY}:/root/.Xauthority" --env="DISPLAY=$DISPLAY" -v="/tmp/.gazebo/:/root/.gazebo/" -v /tmp/.X11-unix:/tmp/.X11-unix:rw --shm-size=1000mb ghcr.io/sloretz/ros-testing:<distro>-desktop-full
35+
36+
apt update
37+
apt upgrade
38+
39+
source /opt/ros/<distro>/setup.bash
40+
rosdep init
41+
rosdep update
42+
43+
colcon build --parallel-workers 1
44+
colcon test --parallel-workers 1
45+
46+
This will obtain the testing docker image from ``ros_oci_images``, open a container, and make sure the system can build and pass unit and system-level testing.
47+
48+
Next, run each major Nav2 launch file and navigate the robot around.
49+
50+
* ``ros2 launch nav2_bringup tb3_simulation_launch.py``
51+
* ``ros2 launch nav2_bringup tb4_simulation_launch.py``
52+
* ``ros2 launch nav2_bringup tb3_loopback_sim_launch.py``
53+
* ``ros2 launch nav2_bringup tb4_loopback_sim_launch.py``
54+
55+
Ensure that you see all the data, costmap, footprint, path planning, control and other topics visible.
56+
Send Navigate To Pose, Navigate Through Poses goals and cancel goals periodically.
57+
Shutdown the Nav2 lifecycle nodes, hit Control+C, and ensure the stack shuts down cleanly.
58+
59+
This step may be performed early to catch and resolve issues before the release process.
60+
Once all testing passes, move onto the next steps.
61+
62+
2. Setup Nav2 Docker Images
63+
---------------------------
64+
65+
Next, we need to setup Nav2's Nightly and Release docker image jobs in `nav2_docker <https://github.com/ros-navigation/nav2_docker>`_.
66+
67+
Update ``.github/workflows/build_images.yaml`` to contain the new distribution in the ``ros_distro`` matrix.
68+
Remove any EOL distributions at this time.
69+
Within the ``strategy.matrix.version`` map, please a new entry for the distribution being added.
70+
The ``main_verison`` is ``1`` unless a new major version is set in Nav2's ``package.xml`` files.
71+
The ``distro_version`` should be bumped by one from the last distribution representing the release in the format ``1.4.X``.
72+
Remove any EOL distributions at this time.
73+
74+
Open the ``README.md`` and update the distributions to include this.
75+
76+
At this time, the build should fail because there is no ``distro`` branch on Nav2, which is our next step.
77+
78+
79+
2. Branch Off Distribution
80+
--------------------------
81+
82+
Now, we will setup the new branch and its CI system.
83+
84+
First, update ``.github/workflows/build_main_against_distros.yml`` by adding the new ``ros_distro`` to the matrix.
85+
While the ``nav2_docker`` nightly image does not yet exist, it will by the end of this step.
86+
Remove any EOL distributions at this time.
87+
88+
Next, bump the ``main`` branch's distribution number to the same set in Step 2 above (i.e. ``1.4.0``).
89+
Add the distribution branch to ``.github/workflows/update_ci_image.yaml`` so that future pushes will result in CI image updates.
90+
Remove any EOL distributions at this time.
91+
92+
Finally, create the new distribution branch from ``main`` and push to the server.
93+
Go into the GitHub Actions tab on ``nav2_docker`` and retrigger its build job.
94+
The nightly and release jobs should now exist for the new distribution and return successfully (validate this).
95+
96+
3. Setup Branch CI
97+
------------------
98+
99+
The final change to the branch is to setup CI so PRs targeting it can be successfully built.
100+
In the new distribution branch, update the files for CI (`Humble Example <https://github.com/ros-navigation/navigation2/commit/4eb4ee01967a3b881c05d962ffd856c668b2e4c0>`_).
101+
102+
* Update ``.circleci/config.yml`` to use the new distribution image (replace ``ghcr.io/ros-navigation/navigation2:main``).
103+
* Update ``.devcontainer/devcontainer.json`` to ``cacheFrom`` the new distribution image (replace ``ghcr.io/ros-navigation/navigation2:main``).
104+
* Update ``Dockerfile`` to use the new distribution's image rather than ``rolling``.
105+
* Update ``tools/distro.Dockerfile`` to use the new distribution's image rather than ``rolling`` in 3x places.
106+
107+
Then, retrigger the Update CI Image workflow in Nav2's GitHub Actions tab, it should now also be successful.
108+
Open a dummy PR against the new distribution branch and ensure that it builds successfully.
109+
110+
111+
4. Update Auxiliary Projects
112+
----------------------------
113+
114+
Nav2 has a number of auxiliary projects that also need to be updated for a new distribution.
115+
These include:
116+
117+
* ``nav2_minimal_turtlebot_simulation``
118+
* ``navigation2_tutorials``
119+
120+
For each:
121+
122+
* Update the package.xml for a new distribution version
123+
* Create a new branch from ``main`` for the distribution
124+
* Update CI on the new branch to use this new distribution image
125+
* Review and update the readme as needed
126+
127+
5. Run Bloom Release
128+
--------------------
129+
130+
Once the new branches, versions, and CI are setup and ready, we can run the bloom release process.
131+
Run the following command to create a new release for the distribution for each Nav2 repository (Nav2, Minimal Turtlebot Simulation, SLAM Toolbox, NPVL, STVL etc).
132+
133+
.. code:: bash
134+
135+
bloom-release navigation2 --rosdistro distro --track distro --new-track --edit
136+
137+
Be patient, this will take a while to run.
138+
139+
6. Announcements
140+
----------------
141+
142+
Finally, we can announce the updates!
143+
Create a new migration guide page on the Nav2 website for contributors to populate with notable changes in the next distribution cycle.
144+
Update the Roadmap page with a new table of projects and features to be added over the next distribution.
145+
146+
Make announcements on Slack, ROS Discourse, and LinkedIn to announce the new distribution and its major new features.
147+
Gifs, videos, and images are always welcome to be included in the announcements!
148+
149+
Identify tickets to address or PRs to merge for the next distribution.
150+
Make a call for contributions on the roadmap items, these strategic items, or other ``good-first-issues``.

‎maintainer_docs/index.rst‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
.. _maintainer_docs:
2+
3+
Maintainer Docs
4+
###############
5+
6+
This page is a set of maintainer procedures and documentation used for maintenance of Nav2.
7+
These are published publicly for visibility and as a resource for the maintainer community.
8+
9+
.. toctree::
10+
:maxdepth: 1
11+
12+
distribution_release.rst

0 commit comments

Comments
 (0)