[libc++] Encode the version in the ReleaseNotes file

[ldionne]

Summary

This way, we don't need to remove the contents of the ReleaseNotes file
after the branch. This should make it much easier and natural to cherry-pick
changes onto the release branch. Typically, we need two patches for those.
First, we need the code changes against main, and then we need a patch
that updates the release notes on the just-created branch.

By versioning the release notes, it becomes easy to author a change
against main that targets a just-branched LLVM release by simply
adding it to the release notes for the right version. This has been
a pain point in previous releases.

[ldionne]

libcxx/docs/ReleaseProcedure.rst

19

This is open to bikeshedding, I'm happy to use a different scheme. We could do libcxx/docs/release-notes/<VERSION>.rst to avoid polluting libcxx/docs/.

[ldionne]

Update with suggested naming scheme.

[ldionne]

Poke CI

[Mordante]

LGTM, can you make sure the release managers are aware of these changes?

libcxx/docs/Helpers/ReleaseNotesTemplate.rst

54

Can you add a note that this should be copied from the last release?

[ldionne]

In D155024#4510863, @Mordante wrote:

LGTM, can you make sure the release managers are aware of these changes?

CC @thieta for awareness.

libcxx/docs/Helpers/ReleaseNotesTemplate.rst

54

I added this note:

NOTE: THIS SHOULD BE POPULATED FROM THE PREVIOUS RELEASE'S UPCOMING DEPRECATIONS AND REMOVALS FOR THE NEXT-NEXT RELEASE (IF ANY)

[thieta]

ACK. When I branch - do I need to do anything in main or just leave it? I wish we could employ this model everywhere I guess :)

[ldionne]

In D155024#4511754, @thieta wrote:

ACK. When I branch - do I need to do anything in main or just leave it? I wish we could employ this model everywhere I guess :)

Just leave the old 17.rst release notes in place. That way, if we have to cherry-pick something to the release/17.x branch, we can make the commit on main but add the release notes to 17.rst and it will cherry-pick like a charm on the release branch.

libcxx/docs/Helpers/ReleaseNotesTemplate.rst

+===========================================
+Libc++ XX.YY.ZZ (In-Progress) Release Notes
+===========================================
+
+.. contents::
+   :local:
+   :depth: 2
+
+Written by the `Libc++ Team <https://libcxx.llvm.org>`_
+
+.. warning::
+
+   These are in-progress notes for the upcoming libc++ XX.YY.ZZ release.
+   Release notes for previous releases can be found on
+   `the Download Page <https://releases.llvm.org/download.html>`_.
+
+Introduction
+============
+
+This document contains the release notes for the libc++ C++ Standard Library,
+part of the LLVM Compiler Infrastructure, release XX.YY.ZZ. Here we describe the
+status of libc++ in some detail, including major improvements from the previous
+release and new feature work. For the general LLVM release notes, see `the LLVM
+documentation <https://llvm.org/docs/ReleaseNotes.html>`_. All LLVM releases may
+be downloaded from the `LLVM releases web site <https://llvm.org/releases/>`_.
+
+For more information about libc++, please see the `Libc++ Web Site
+<https://libcxx.llvm.org>`_ or the `LLVM Web Site <https://llvm.org>`_.
+
+Note that if you are reading this file from a Git checkout or the
+main Libc++ web page, this document applies to the *next* release, not
+the current one. To see the release notes for a specific release, please
+see the `releases page <https://llvm.org/releases/>`_.
+
+What's New in Libc++ XX.YY.ZZ?
+==============================
+
+
+Implemented Papers
+------------------
+
+
+Improvements and New Features
+-----------------------------
+
+
+Deprecations and Removals
+-------------------------
+
+
+Upcoming Deprecations and Removals
+----------------------------------
+
+NOTE: THIS SHOULD BE POPULATED FROM THE PREVIOUS RELEASE'S UPCOMING DEPRECATIONS AND REMOVALS FOR THE NEXT-NEXT RELEASE (IF ANY)
+
+ABI Affecting Changes
+---------------------
+
+
+Build System Changes
+--------------------
+

libcxx/docs/ReleaseProcedure.rst

 Prepare the release
 ===================
 
 This is done by the libc++ developers.
 
 It should be finished before the Release managers start branching the new
 release:
 
-* Make sure the ``libcxx/docs/ReleaseNotes.rst`` is up to date. Typically
+* Make sure ``libcxx/docs/ReleaseNotes/<VERSION>.rst`` is up to date. Typically
   this file is updated when contributing patches. Still there might be some
   information added regarding the general improvements of larger projects.
 
 * Make sure the deprecated features on this page are up to date. Typically a
   new deprecated feature should be added to the release notes and this page.
   However this should be verified so removals won't get forgotten.
 
 * Make sure the latest Unicode version is used. The C++ Standard

 This is done by the LLVM Release managers.
 
 After branching for an LLVM release:
 
 1. Update ``_LIBCPP_VERSION`` in ``libcxx/include/__config``
 2. Update the version number in ``libcxx/docs/conf.py``
 3. Update ``_LIBCPPABI_VERSION`` in ``libcxxabi/include/cxxabi.h``
 4. Update ``_LIBUNWIND_VERSION`` in ``libunwind/include/__libunwind_config.h``
-5. Remove the in-progress warning from ``libcxx/docs/ReleaseNotes.rst``
+5. Create a release notes file for the next release from the template
+6. Point to the new release notes file from ``libcxx/docs/index.rst``
 
 Post branching
 ==============
 
 This is done by the libc++ developers.
 
 After branching it takes a couple of days before the new LLVM ToT version is
 available on `<https://apt.llvm.org>`_. Once it is available the pre-commit CI

libcxx/docs/index.rst

 
 
 Getting Started with libc++
 ===========================
 
 .. toctree::
    :maxdepth: 1
 
-   ReleaseNotes
+   ReleaseNotes/17
    UsingLibcxx
    BuildingLibcxx
    TestingLibcxx
    Contributing
    Modules
    HardenedMode
    ReleaseProcedure
    Status/Cxx14