[mirror_frr.git] / doc / developer / frr-release-procedure.rst

.. _frr-release-procedure:

FRR Release Procedure
=====================

``<version>`` - version to be released, e.g. 7.3
``origin`` - FRR upstream repository

1. Checkout ``dev/<version>``.

   .. code-block:: console

      git checkout dev/<version>

2. Create and push a new branch called ``stable/<version>`` based on the
   ``dev/<version>`` branch.

   .. code-block:: console

      git checkout -b stable/<version>
      git push origin stable/<version>:refs/heads/stable/<version>

3. Remove the development branch called ``dev/<version>``

   .. code-block:: console

      git push origin --delete dev/<version>

4. Update Changelog for Red Hat Packages:

   Edit :file:`redhat/frr.spec.in` and look for the ``%changelog`` section:

   - Change last (top of list) entry from ``%{version}`` to the **last**
     released version number. For example, if ``<version>`` is ``7.3`` and the
     last public release was ``7.2``, you would use ``7.2``, changing the file
     like so::

        * Tue Nov  7 2017 Martin Winter <mwinter@opensourcerouting.org> - %{version}

     to::

        * Tue Nov  7 2017 Martin Winter <mwinter@opensourcerouting.org> - 7.2

   - Add new entry to the top of the list with ``%{version}`` tag.  Make sure
     to watch the format, i.e. the day is always 2 characters, with the 1st
     character being a space if the day is one digit.

   - Add the changelog text below this entry.

5. Update Changelog for Debian Packages:

   Edit :file:`changelog-auto.in`:

   - Change last (top of list) entry from ``@VERSION@`` to the **last**
     released version number. For example, if ``<version>`` is ``7.3`` and the
     last public release was ``7.2``, you would use ``7.2``, changing the file
     like so::

        frr (@VERSION@) RELEASED; urgency=medium

     to::

        frr (7.2) RELEASED; urgency=medium

   - Add a new entry to the top of the list with a ``@VERSION@`` tag. Make sure
     to watch the format.

   - Add the changelog text below this entry.

   - Verify the changelog format using ``dpkg-parsechangelog``. In the
     repository root:

     .. code-block:: console

        dpkg-parsechangelog

     You should see output like this::

        vagrant@local ~/frr> dpkg-parsechangelog
        Source: frr
        Version: 7.3-dev-0
        Distribution: UNRELEASED
        Urgency: medium
        Maintainer: FRRouting-Dev <dev@lists.frrouting.org>
        Timestamp: 1540478210
        Date: Thu, 25 Oct 2018 16:36:50 +0200
        Changes:
         frr (7.3-dev-0) RELEASED; urgency=medium
         .
           * Your Changes Here

6. Change main version number:

    - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command
      to ``<version>``

7. Commit the changes, adding the changelog to the commit message. Follow all
   existing commit guidelines.

8. Create and submit a GitHub pull request, with the ``HEAD`` set to
   ``stable/<version>`` and the base set to the upstream ``master`` branch.
   Allow NetDef CI to complete its run and verify that all package builds were
   successful.

9. Create a git tag for the version:

   .. code-block:: console

      git tag -a frr-<version> -m "FRRouting Release <version>"

10. Push the commit and new tag.

   .. code-block:: console

      git push origin stable/<version>:refs/head/stable/<version>
      git push origin frr-<version>

11. Kick off the Release build plan on the CI system for the correct release.
    Contact Martin Winter for this step. Ensure all release packages build
    successfully.

12. Kick off the Snapcraft build plan for the release.

13. Acquire the release RPM binary packages from Martin Winter.

14. On GitHub, go to the <https://github.com/FRRouting/frr/releases>_ and click
    "Draft a new release". Write a release announcement. The release
    announcement should follow the template in
    ``release-announcement-template.md``, located next to this document. Check
    for spelling errors, and optionally (but preferably) have other maintainers
    proofread the announcement text.

    Attach **only** the binary RPM packages to the GitHub release using
    GitHub's attachment functionality. Do not attach Debian packages. Do not
    attach source tarballs - these will be generated and attached by GitHub
    automatically. Do not publish the release yet.

15. Contact the current Debian maintainer for FRR to get new Debian packages
    built and published on our APT repository at https://deb.frrouting.net/.
    Ensure the webpage text is updated. Verify that new packages install
    successfully on a vanilla Debian installation using the instructions on the
    webpage.

16. Deploy Snapcraft release (after CI system finishes the tests for snapcraft
    testplan).

17. Update the Read The Docs instance to being publishing documentation built
    off the ``stable/<version>`` branch. Contact Quentin Young for this step.

18. Publish the GitHub release.

19. Clone the ``frr-www`` repository:

    .. code-block:: console

       git clone https://github.com/FRRouting/frr-www.git

20. Add a new release announcement, using a previous announcement as template:

    .. code-block:: console

       cp <old-version>-launch.md <version>-launch.md

    Paste the GitHub release announcement text into this document, and **remove
    line breaks**. In other words, this::

       This is one continuous
       sentence that should be
       rendered on one line

    Needs to be changed to this::

       This is one continuous sentence that should be rendered on one line

    This is very important otherwise the announcement will be unreadable on the
    website.

    Make sure to add a link to the GitHub releases page at the top.

    Once finished, manually add a new entry into ``index.html`` to link to this
    new announcement. Look at past commits to see how to do this.

21. Deploy the updated ``frr-www`` on the frrouting.org web server and verify
    that the announcement text is visible.

22. Send an email to ``announce@lists.frrouting.org``. The text of this email
    should include the text from the GitHub release.

23. Update masters version of the changelog-auto.in

    Take the change data and cut-n-paste the changes into the master version below
    the @VERSION@-0 lines.  So we have the history of the previous release.
Commit	Line	Data
f4bcc72f QY	1	.. _frr-release-procedure:
	2
	3	FRR Release Procedure
	4	=====================
	5
	6	``<version>`` - version to be released, e.g. 7.3
	7	``origin`` - FRR upstream repository
	8
	9	1. Checkout ``dev/<version>``.
	10
972d7521 QY	11	.. code-block:: console
972d7521 QY	12
f4bcc72f QY	13	git checkout dev/<version>
	14
	15	2. Create and push a new branch called ``stable/<version>`` based on the
	16	``dev/<version>`` branch.
	17
972d7521	18	.. code-block:: console
f4bcc72f QY	19
	20	git checkout -b stable/<version>
	21	git push origin stable/<version>:refs/heads/stable/<version>
	22
7188145f DS	23	3. Remove the development branch called ``dev/<version>``
	24
	25	.. code-block:: console
	26
	27	git push origin --delete dev/<version>
	28
	29	4. Update Changelog for Red Hat Packages:
f4bcc72f QY	30
	31	Edit :file:`redhat/frr.spec.in` and look for the ``%changelog`` section:
	32
	33	- Change last (top of list) entry from ``%{version}`` to the last
	34	released version number. For example, if ``<version>`` is ``7.3`` and the
	35	last public release was ``7.2``, you would use ``7.2``, changing the file
	36	like so::
	37
	38	* Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - %{version}
	39
	40	to::
	41
	42	* Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - 7.2
	43
	44	- Add new entry to the top of the list with ``%{version}`` tag. Make sure
	45	to watch the format, i.e. the day is always 2 characters, with the 1st
	46	character being a space if the day is one digit.
	47
	48	- Add the changelog text below this entry.
	49
7188145f	50	5. Update Changelog for Debian Packages:
f4bcc72f	51
439be082	52	Edit :file:`changelog-auto.in`:
f4bcc72f	53
439be082 QY	54	- Change last (top of list) entry from ``@VERSION@`` to the last
	55	released version number. For example, if ``<version>`` is ``7.3`` and the
	56	last public release was ``7.2``, you would use ``7.2``, changing the file
	57	like so::
f4bcc72f	58
439be082 QY	59	frr (@VERSION@) RELEASED; urgency=medium
	60
	61	to::
	62
	63	frr (7.2) RELEASED; urgency=medium
	64
	65	- Add a new entry to the top of the list with a ``@VERSION@`` tag. Make sure
	66	to watch the format.
	67
	68	- Add the changelog text below this entry.
f4bcc72f QY	69
	70	- Verify the changelog format using ``dpkg-parsechangelog``. In the
	71	repository root:
	72
972d7521	73	.. code-block:: console
f4bcc72f QY	74
	75	dpkg-parsechangelog
	76
	77	You should see output like this::
	78
	79	vagrant@local ~/frr> dpkg-parsechangelog
	80	Source: frr
	81	Version: 7.3-dev-0
	82	Distribution: UNRELEASED
	83	Urgency: medium
	84	Maintainer: FRRouting-Dev <dev@lists.frrouting.org>
	85	Timestamp: 1540478210
	86	Date: Thu, 25 Oct 2018 16:36:50 +0200
	87	Changes:
	88	frr (7.3-dev-0) RELEASED; urgency=medium
	89	.
972d7521	90	* Your Changes Here
f4bcc72f	91
7188145f	92	6. Change main version number:
f4bcc72f QY	93
	94	- Edit :file:`configure.ac` and change version in the ``AC_INIT`` command
	95	to ``<version>``
	96
7188145f	97	7. Commit the changes, adding the changelog to the commit message. Follow all
f4bcc72f QY	98	existing commit guidelines.
f4bcc72f QY	99
7188145f	100	8. Create and submit a GitHub pull request, with the ``HEAD`` set to
f4bcc72f QY	101	``stable/<version>`` and the base set to the upstream ``master`` branch.
	102	Allow NetDef CI to complete its run and verify that all package builds were
	103	successful.
	104
7188145f	105	9. Create a git tag for the version:
f4bcc72f	106
972d7521	107	.. code-block:: console
f4bcc72f QY	108
	109	git tag -a frr-<version> -m "FRRouting Release <version>"
	110
7188145f	111	10. Push the commit and new tag.
f4bcc72f	112
972d7521	113	.. code-block:: console
f4bcc72f QY	114
	115	git push origin stable/<version>:refs/head/stable/<version>
	116	git push origin frr-<version>
	117
7188145f	118	11. Kick off the Release build plan on the CI system for the correct release.
f4bcc72f QY	119	Contact Martin Winter for this step. Ensure all release packages build
	120	successfully.
	121
7188145f	122	12. Kick off the Snapcraft build plan for the release.
f4bcc72f	123
7188145f	124	13. Acquire the release RPM binary packages from Martin Winter.
f4bcc72f	125
7188145f	126	14. On GitHub, go to the <https://github.com/FRRouting/frr/releases>_ and click
f4bcc72f QY	127	"Draft a new release". Write a release announcement. The release
	128	announcement should follow the template in
	129	``release-announcement-template.md``, located next to this document. Check
	130	for spelling errors, and optionally (but preferably) have other maintainers
	131	proofread the announcement text.
	132
	133	Attach only the binary RPM packages to the GitHub release using
	134	GitHub's attachment functionality. Do not attach Debian packages. Do not
	135	attach source tarballs - these will be generated and attached by GitHub
	136	automatically. Do not publish the release yet.
	137
7188145f	138	15. Contact the current Debian maintainer for FRR to get new Debian packages
f4bcc72f QY	139	built and published on our APT repository at https://deb.frrouting.net/.
	140	Ensure the webpage text is updated. Verify that new packages install
	141	successfully on a vanilla Debian installation using the instructions on the
	142	webpage.
	143
7188145f	144	16. Deploy Snapcraft release (after CI system finishes the tests for snapcraft
f4bcc72f QY	145	testplan).
f4bcc72f QY	146
7188145f	147	17. Update the Read The Docs instance to being publishing documentation built
f4bcc72f QY	148	off the ``stable/<version>`` branch. Contact Quentin Young for this step.
f4bcc72f QY	149
7188145f	150	18. Publish the GitHub release.
f4bcc72f	151
7188145f	152	19. Clone the ``frr-www`` repository:
f4bcc72f	153
972d7521	154	.. code-block:: console
f4bcc72f QY	155
	156	git clone https://github.com/FRRouting/frr-www.git
	157
7188145f	158	20. Add a new release announcement, using a previous announcement as template:
f4bcc72f	159
972d7521	160	.. code-block:: console
f4bcc72f QY	161
	162	cp <old-version>-launch.md <version>-launch.md
	163
	164	Paste the GitHub release announcement text into this document, and **remove
	165	line breaks**. In other words, this::
972d7521	166
f4bcc72f QY	167	This is one continuous
	168	sentence that should be
	169	rendered on one line
972d7521	170
f4bcc72f	171	Needs to be changed to this::
972d7521	172
f4bcc72f	173	This is one continuous sentence that should be rendered on one line
972d7521	174
f4bcc72f QY	175	This is very important otherwise the announcement will be unreadable on the
	176	website.
	177
	178	Make sure to add a link to the GitHub releases page at the top.
	179
	180	Once finished, manually add a new entry into ``index.html`` to link to this
	181	new announcement. Look at past commits to see how to do this.
	182
7188145f	183	21. Deploy the updated ``frr-www`` on the frrouting.org web server and verify
f4bcc72f QY	184	that the announcement text is visible.
f4bcc72f QY	185
7188145f	186	22. Send an email to ``announce@lists.frrouting.org``. The text of this email
f4bcc72f	187	should include the text from the GitHub release.
7188145f DS	188
	189	23. Update masters version of the changelog-auto.in
	190
	191	Take the change data and cut-n-paste the changes into the master version below
	192	the @VERSION@-0 lines. So we have the history of the previous release.