diff options
Diffstat (limited to 'doc/developer')
| -rw-r--r-- | doc/developer/frr-release-procedure.rst | 181 | ||||
| -rw-r--r-- | doc/developer/maintainer-release-build.rst | 89 | ||||
| -rw-r--r-- | doc/developer/packaging.rst | 8 | ||||
| -rw-r--r-- | doc/developer/release-announcement-template.md | 40 | ||||
| -rw-r--r-- | doc/developer/subdir.am | 3 | ||||
| -rw-r--r-- | doc/developer/workflow.rst | 3 |
6 files changed, 230 insertions, 94 deletions
diff --git a/doc/developer/frr-release-procedure.rst b/doc/developer/frr-release-procedure.rst new file mode 100644 index 0000000000..a3ead93d72 --- /dev/null +++ b/doc/developer/frr-release-procedure.rst @@ -0,0 +1,181 @@ +.. _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:: shell + + git checkout dev/<version> + +2. Create and push a new branch called ``stable/<version>`` based on the + ``dev/<version>`` branch. + + .. code-block:: shell + + git checkout -b stable/<version> + git push origin stable/<version>:refs/heads/stable/<version> + +3. 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. + +4. 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:: shell + + 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 + +5. Change main version number: + + - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command + to ``<version>`` + +6. Commit the changes, adding the changelog to the commit message. Follow all + existing commit guidelines. + +7. 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. + +8. Create a git tag for the version: + + .. code-block:: shell + + git tag -a frr-<version> -m "FRRouting Release <version>" + +9. Push the commit and new tag. + + .. code-block:: shell + + git push origin stable/<version>:refs/head/stable/<version> + git push origin frr-<version> + +10. 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. + +11. Kick off the Snapcraft build plan for the release. + +12. Acquire the release RPM binary packages from Martin Winter. + +13. 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. + +14. 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. + +15. Deploy Snapcraft release (after CI system finishes the tests for snapcraft + testplan). + +16. Update the Read The Docs instance to being publishing documentation built + off the ``stable/<version>`` branch. Contact Quentin Young for this step. + +17. Publish the GitHub release. + +18. Clone the ``frr-www`` repository: + + .. code-block:: shell + + git clone https://github.com/FRRouting/frr-www.git + +19. Add a new release announcement, using a previous announcement as template: + + .. code-block:: shell + + 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. + +20. Deploy the updated ``frr-www`` on the frrouting.org web server and verify + that the announcement text is visible. + +21. Send an email to ``announce@lists.frrouting.org``. The text of this email + should include the text from the GitHub release. diff --git a/doc/developer/maintainer-release-build.rst b/doc/developer/maintainer-release-build.rst deleted file mode 100644 index 7792173034..0000000000 --- a/doc/developer/maintainer-release-build.rst +++ /dev/null @@ -1,89 +0,0 @@ -Release Build Procedure for FRR Maintainers -=========================================== - -1. Rename branch (if needed) - -.. code-block:: shell - - git clone git@github.com:FRRouting/frr.git - cd frr - git checkout dev/5.0 - git push origin :refs/heads/dev/5.0 - git push origin dev/5.0:refs/heads/stable/5.0 - -2. Checkout the new stable branch: - -.. code-block:: shell - - git checkout stable/5.0 - -3. Update Changelog for RedHat Package: - - Edit :file:`redhat/frr.spec.in` and look for the ``%changelog`` section: - - - Change last (top of list) entry from ``%{version}`` to previous fixed - version number, i.e.:: - - * Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - %{version} - - to:: - - * Tue Nov 7 2017 Martin Winter <mwinter@opensourcerouting.org> - 3.0.2 - - - Add new entry to the top of the list with ``%{version}`` tag and changelog - for version. - 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. - -4. Update Changelog for Debian Packages: - - Edit :file:`debian/changelog-auto.in`: - - - Change last (top of list) entry from ``@VERSION@`` to previous fixed - version number, i.e.:: - - frr (@VERSION@) RELEASED; urgency=medium - - to:: - - frr (3.0.2) RELEASED; urgency=medium - - - Add a new entry to the top of the list with a ``@VERSION@`` tag and - changelog for version. - -5. Change main version number: - - - Edit :file:`configure.ac` and change version in the ``AC_INIT`` command - - Create a new entry with the version as ``%{version}`` tag - -6. Test building at least a Red Hat and Ubuntu package (or create a PR to have - the CI system test them) - -7. Commit the changes, adding the changelog to the commit message - -8. Create a git tag for the version: - - .. code-block:: shell - - git tag -a frr-5.0 -m "FRRouting Release 5.0" - -9. Push the commit and tag(s) and watch for errors on CI: - - .. code-block:: shell - - git push - git push --tags - -10. Kick off the Release build plan on the CI system for the correct release - -11. Send a Release Announcement with changes to - ``announce@lists.frrouting.org`` - -12. Kick off the Snapcraft build plan for the correct release - -13. After CI plans succeed, release on GitHub by going to - https://github.com/FRRouting/frr/releases and selecting "Draft a new - release". - -14. Deploy Snapcraft release (after CI system finishes the tests for snapcraft - testplan) diff --git a/doc/developer/packaging.rst b/doc/developer/packaging.rst index b174a9660c..0c072e4d16 100644 --- a/doc/developer/packaging.rst +++ b/doc/developer/packaging.rst @@ -1,10 +1,10 @@ -********* -Packaging -********* +******************** +Releases & Packaging +******************** .. toctree:: :maxdepth: 2 - maintainer-release-build + frr-release-procedure packaging-debian packaging-redhat diff --git a/doc/developer/release-announcement-template.md b/doc/developer/release-announcement-template.md new file mode 100644 index 0000000000..658b87eada --- /dev/null +++ b/doc/developer/release-announcement-template.md @@ -0,0 +1,40 @@ +<!--- +name: release-announcement-template +about: Template to use when drafing a new release announcement. DELETE THIS + BLOCK BEFORE PUBLISHING. +---> + +We are pleased to announce FRR <version>. + +<!-- Add a brief summary of major changes here --> + +Thank you to all contributors! + +Changelog +--------- + +<!-- List **only** user-visible changes in this section. When listing changes to individual daemons, alphabetize the list by daemon name. --> + +**All daemons:** +- <!-- List changes to all daemons --> + +<!-- If a new daemon was added, list it at the top here --> +**New daemon: <new>** +- Adds support for <protocol/feature> + +**daemon 1** +- <!-- List changes --> + +**daemon 2** +- <!-- List changes --> + +**daemon N** +- <!-- List changes --> + +### Internal improvements + +- <!-- List **only** user-invisible changes here --> + +### Packaging changes + +- <!-- List any new or removed packages here --> diff --git a/doc/developer/subdir.am b/doc/developer/subdir.am index 557a41c51f..2c49d6b875 100644 --- a/doc/developer/subdir.am +++ b/doc/developer/subdir.am @@ -26,6 +26,7 @@ dev_RSTFILES = \ doc/developer/building.rst \ doc/developer/cli.rst \ doc/developer/conf.py \ + doc/developer/frr-release-procedure.rst \ doc/developer/hooks.rst \ doc/developer/include-compile.rst \ doc/developer/index.rst \ @@ -33,7 +34,6 @@ dev_RSTFILES = \ doc/developer/lists.rst \ doc/developer/locking.rst \ doc/developer/logging.rst \ - doc/developer/maintainer-release-build.rst \ doc/developer/memtypes.rst \ doc/developer/modules.rst \ doc/developer/next-hop-tracking.rst \ @@ -55,6 +55,7 @@ EXTRA_DIST += \ $(dev_RSTFILES) \ doc/developer/draft-zebra-00.ms \ doc/developer/ldpd-basic-test-setup.md \ + doc/developer/release-announcement-template.md \ # end DEVBUILD = doc/developer/_build diff --git a/doc/developer/workflow.rst b/doc/developer/workflow.rst index 93d01bfbc1..c2e3724df2 100644 --- a/doc/developer/workflow.rst +++ b/doc/developer/workflow.rst @@ -113,6 +113,9 @@ Security fixes are backported to all releases less than or equal to at least one year old. Security fixes may also be backported to older releases depending on severity. +For detailed instructions on how to produce an FRR release, refer to +:ref:`frr-release-procedure`. + Long term support branches ( LTS ) ----------------------------------------- |