Add RELEASING.md to document our release procedures (#3564)

Adapted from the similar document I wrote for OSL.

This serves both as a checklist for me to make sure I don't miss any
steps during a release, but also so that other people could take over
release procedures if necessary or desired.

I also rearranged the order of some lines in CMakeLists.txt for
clarity (but did not change the logic).

CMakeLists.txt

@@ -4,18 +4,20 @@
 
 cmake_minimum_required (VERSION 3.12)
 set (OpenImageIO_VERSION "2.4.5.0" CACHE STRING "Version")
+set (PROJECT_VERSION_RELEASE_TYPE "" CACHE STRING
+    "Build type, for example: dev, beta2, RC1 (empty string for normal release)")
+option (${PROJECT_NAME}_SUPPORTED_RELEASE
+        "Set ON for supported release branch, OFF for master" ON)
+
 project (OpenImageIO VERSION ${OpenImageIO_VERSION}
-\         HOMEPAGE_URL "https://openimageio.org"
+         HOMEPAGE_URL "https://openimageio.org"
          LANGUAGES CXX C)
+
 set (PROJ_NAME OIIO)    # short name, caps
 string (TOLOWER ${PROJ_NAME} PROJ_NAME_LOWER)  # short name lower case
 string (TOUPPER ${PROJ_NAME} PROJ_NAME_UPPER)  # short name upper case
-set (PROJECT_VERSION_RELEASE_TYPE "" CACHE STRING
-    "Build type, for example: dev, beta2, RC1 (empty string for normal release)")
 set (${PROJECT_NAME}_VERSION_RELEASE_TYPE ${PROJECT_VERSION_RELEASE_TYPE})
 set (PROJECT_AUTHORS "Contributors to the OpenImageIO project")
-option (${PROJECT_NAME}_SUPPORTED_RELEASE
-       "Set ON for supported release branch, OFF for master" ON)
 if (${PROJECT_NAME}_SUPPORTED_RELEASE)
     set (${PROJECT_NAME}_DEV_RELEASE OFF)
 else ()

RELEASING.md

@@ -0,0 +1,344 @@
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+<!-- Copyright Contributors to the OpenImageIO Project. -->
+
+# Release Procedures for OpenImageIO
+
+## Version nomenclature and release cadence
+
+### The meaning of the version parts
+
+Our release numbers are of the form `MAJOR.MINOR.PATCH.TWEAK`, and we follow
+an almost-semantic-versioning scheme.
+
+MAJOR changes are those that break backward-compatibility of the public APIs,
+requiring existing application code to change their source code where it calls
+OIIO API functions in order to compile and work correctly.
+
+MINOR changes guarantee API backward-compatibility with prior releases that
+have the same major number, but can introduce ABI or link incompatibilities.
+Applications using OIIO need to be recompiled to move to a new minor release,
+but should not need to change their source code. Minor releases are allowed
+to drop support for sufficiently old compilers and dependencies.
+
+PATCH changes guarantee both API and ABI/link backward-compatibility with
+prior releases that have the same minor number. Features and new public API
+calls may be added (thus deviating from strict semantic versioning), but only
+if they preserve ABI/link compatibility. This means that standalone functions
+or static methods may be added, but existing functions will not change their
+parameters, and no new virtual methods or struct data layouts change for patch
+releases (for classes in public header files). Application code can be
+re-linked to a new patch release without needing to be recompiled. We also
+guarantee that any compilers or dependencies supported for the first release
+of a minor series will continue to be supported for all patches to that minor
+series.
+
+TWEAK changes are restricted to critical bug fixes or build breaks that do
+not alter public APIs in any way.
+
+### Cadence of releases
+
+Major (arbitrarily incompatible) releases happen rarely, usually with multiple
+years between them.
+
+Minor (API backward-compatible) releases are scheduled annually, targeted at
+late summer (SIGGRAPH time) to be in beta, and early autumn for a full
+release.
+
+Patch (API and ABI backward-compatible) releases are scheduled monthly,
+usually aiming for the first day of each month.
+
+Tweak (fully forward and backward compatible) releases are not regularly
+scheduled, and only happen sporadically, when a critical fix is needed in
+between scheduled patch releases.
+
+### Things are different in "master"
+
+The "master" branch is where ongoing development occurs without any
+compatibility guarantees. We don't always know if the next year's release from
+master will turn out to be major (API breaking) or minor (only ABI breaking).
+
+Some studios or products need the most up-to-date enhancements, and thus tend
+to build OIIO from the "master" branch rather than using tagged releases. For
+these users, we try to set version numbers and occasionally tag in master, to
+send a signal about which points in master seem safe to rely on various
+compatibility levels. However, the rules are slightly different than we use
+for releases.
+
+In the "master" branch:
+
+- TWEAK changes within "master" only guarantee ABI back-compatibility, but may
+  have additions or non-bug-fix behavior changes (akin to patch releases
+  within a release branch).
+- PATCH changes within "master" are allowed to break ABI or API (changes that
+  would require minor or major releases, if they were not in "master").
+- Beware of unmarked breaks in compatibility of commits in master that are
+  in between developer preview tags.
+
+
+---
+
+## Branch and tag names
+
+**Branches** are places where commits containing new development may be added
+(and thus the branch markers will move over time). Branch names obey the
+following conventions:
+
+- `master` is the area for arbitrary changes intended for the next year's
+  major or minor release.
+- `dev-1.2` are the areas for staging additions to the next month's patch
+  release for the designated minor version series.
+- `release` is a special branch marker that is always set to the latest tag of
+  the currently supported, stable release family. People can count on
+  "release" always being the latest stable release, whatever that may be at
+  the time.
+
+**Tags** indicate releases or developer previews, and once a commit is
+tagged, it is permanent and will never be moved. Tag names obey the following
+conventions:
+
+- `v1.2.3.4` is a specific public stable release, corresponding to official
+  major, minor, public, or tweak releases.
+- `v1.2.3.4-alpha`, `v1.2.3.4-beta`, or `v1.2.3.4-RC1` are pre-releases for an
+  upcoming public stable release, at the alpha, beta, or release candidate
+  stages, respectively.
+- `v1.2.3.4-dev` is a "developer preview" within "master." It is not an official
+  supported release, and while the numbering may indicate compatibility versus
+  other recent developer previews, they should not be assumed to be compatible
+  with any prior official stable releases.
+
+*Very* occasionally, other branch or tag names (with custom suffixes or
+different naming schemes) may be used for special purposes by particular
+developers or users, but should not be considered reliable or permanent, and
+in general should be ignored by anyone who didn't make the tag or branch.
+
+---
+
+## Release Procedures
+
+### Soft freeze for monthly tweak releases:
+
+We freely backport *safe*, non-ABI-breaking changes by cherry-picking them
+from master to the supported branch continually throughout most of the month.
+
+In the seven days before the new month, we do a "soft freeze" where only
+important bug fixes are backported. Hold on to any other patches you wish to
+backport until after the monthly patch release (i.e., save them for the next
+month's release so you never have a release that contains changes that are
+only a few days old, and therefore not as well tested). You may, of course,
+continue to backport fixes to documentation or other non-code parts of the
+project during this soft freeze.
+
+### Branching for annual major/minor releases
+
+By mid-June (about 1-2 months before the beta of a new annual big release),
+you should branch and mark it as an alpha.
+
+At the tip of "master", create a new branch named `dev-MAJOR.MINOR` that will
+be the staging area for the next release.
+
+Customarily, at that point we add a commit to master (but not to the new
+dev-MAJ.MIN branch) that bumps master's version to the next minor level, to
+avoid any confusion between builds from master versus what will be the next
+release branch. This starts the divergence between master and the release
+branch, and henceforth, any big or compatibility-breaking changes will only be
+committed to master and not backported to the release branch. (Though we are
+loose about this rule during the alpha period and allow continued breaking
+changes in the alpha, but by the time we call it beta, we allow no more
+breaking changes.) Also at this stage, the master branch's CHANGES.md should
+have a heading added at the top for the *next* version.
+
+
+### Prior to a release
+
+1. Update CI dependencies: Ensure that the "latest" CI test specifies the
+   current releases of the dependencies and compilers (check their home
+   pages), and that the [INSTALL.md](../INSTALL.md) file correctly documents
+   the version ranges that we expect to work and that we actively test.
+
+2. Release notes: [CHANGES.md](../CHANGES.md) should be updated to reflect
+   all the new features and fixes. Looking at the notes from older releases
+   should provide a good example of what we're aiming for.
+
+   - Patch and tweak releases can be brief one-line descriptions (often the
+     first line of the commit messages involved), presented in a single
+     section in either chronological or any other order that seems right.
+   - Minor or major releases have a much more extensive, prose-based
+     description of all changes since the last minor release, broken into
+     sections (dependency changes, major new features, enhancements and fixes,
+     internals and developer goodies, testing/CI/ports, etc.) and ordered for
+     readability and relevance.
+
+3. Ensure docs are up to date:
+
+   - Actually read the [README.md](README.md), [INSTALL.md](INSTALL.md),
+     and other repository docs and make sure all the information is up to
+     date. Check the [CREDITS.md](CREDITS.md) against the recent repo history
+     to be sure new contributors are listed.
+   - Skim the primary user documentation to look for any obvious errors,
+     especially the parts that describe new features.
+   - If we are using any online docs (like readthedocs), make sure it is
+     building and looks correct on the web site.
+
+4. Make sure the the top-level CMakeLists.txt file is updated:
+
+   - The `OpenImageIO_VERSION` should be correct.
+   - The `PROJECT_VERSION_RELEASE_TYPE` variable should be set to "alpha" or
+     "beta" if appropriate, "RC" for release candidate, or empty string `""`
+     for most supported releases, and "dev" only for the master branch or
+     developer previews.
+   - The `${PROJECT_NAME}_SUPPORTED_RELEASE` variable should be `ON` for any
+     release branch, `OFF` for master.
+
+5. Make sure everything passes the usual CI workflow. Also check the daily or
+   weekly "analysis" workflows to make sure there aren't any important
+   warnings that should be fixed.
+
+
+### Staging alpha / beta / release candidate (annual minor/major releases only)
+
+For monthly patch releases, we don't have any formal alpha/beta/RC stages.
+
+For the annual minor or major releases we have a staged release:
+
+- `alpha` is everything after we have branched, in which we think all the big
+  new features have been added, and while we will make continued changes and
+  fixes, we are aiming for increased stability and to minimize additional
+  breaking changes prior to the release.
+- `beta` should be about one month prior to the final release date. We create
+  a tag `v1.2.3.4-beta` and announce the beta (see below "Making the
+  release"). Once we tag a beta, we try very hard not to allow any further
+  changes that change the API or are not ABI-compatible (i.e., safe fixes
+  only).
+- `RC` or release candidates around one week prior to the final release date.
+  This is a trial run, hopefully identical to the final release (except for
+  removing the RC label and making a new tag). The only changes allowed after
+  RC are fixes to the most critical bugs or build breaks that would be bad for
+  users to encounter. If critical problems are found with RC1, they should be
+  fixed and immediately re-tagged as RC2, etc. All other fixes should be
+  postponed until the next month's patch release.
+
+### Making the release
+
+A final release is made on the scheduled date, provided the latest RC has
+survived for at least a few days of testing without finding any critical
+problems. Don't make the release final until you are sure there are no
+truly critical bugs or build breaks that users will encounter.
+
+The following are the steps for making the release:
+
+1. Edit the top-level CMakeLists.txt to remove any RC designation
+   (i.e., `PROJECT_VERSION_RELEASE_TYPE` should be set to `""`).
+
+2. Edit CHANGES.md to reflect the correct date of the release and ensure it
+   includes any last-minute changes that were made during beta or release
+   candidate stages.
+
+3. Push it to **your** GitHub, make sure it passes CI.
+
+4. Tag the release: `git tag v1.2.3.4` (no more beta, RC, or dev suffix).
+
+5. If this will now be the recommended stable release, move the `release`
+   branch marker to the same position.
+
+6. Push it to GitHub: `git push OpenImageIO release --tags`
+
+   (This example assumes "OpenImageIO" is the name of the remote for the
+   GitHub `OpenImageIO/oiio` repo.)
+
+7. Draft a release on GitHub: On https://github.com/OpenImageIO/oiio/releases
+   select "Draft a new release." Choose the new tag you just pushed. Make the
+   release title "OpenImageIO v1.2.3.4" (and beta, etc., designation
+   if applicable). In the description, paste the release notes for this
+   release (from CHANGES.md). If this is a beta or release candidate, check
+   "this is a pre-release" box at the bottom.
+
+8. Announce the release on the [oiio-dev mail list](http://lists.openimageio.org/listinfo.cgi/oiio-dev-openimageio.org)
+   with the subject "Release: OpenImageIO v1.2.3.4" and using one of these
+   templates for the body of the email.
+
+   For a monthly patch release:
+
+    > We have tagged v1.2.3.4 as the latest production release and moved the
+    > "release" branch marker to that point.  This is guaranteed to be API,
+    > ABI, and link back-compatible with prior 1.2 releases. Release notes
+    > are below.
+    >
+    > (Paste the full set of 1.2 changes here, just copy the appropriate
+    > part of CHANGES.md)
+
+   For an annual major/minor release:
+
+    > OpenImageIO version 1.2 has been released! Officially tagged as
+    > "v1.2.3.4", we have also moved the "release" branch tag to this
+    > position. Henceforth, 1.2 is the supported production release family.
+    > The API is now frozen -- we promise that subsequent 1.2.x releases
+    > (which should happen monthly) will not break back-compatibility of API,
+    > ABI, or linkage, compared to this release. Please note that this release
+    > is *not* ABI or link compatible with 1.1 or older releases.
+    > 
+    > Release notes for 1.2 outlining all the changes since last year's
+    > release are below.
+    > 
+    > Please note that a few of the build and runtime dependencies have
+    > changed their minimum supported versions. (List here any important
+    > changes to dependencies, compilers, or C++ standard that users should be
+    > aware of.)
+    > 
+    > (List here anything else that people should know about this release
+    > family that may be surprising if they haven't followed the last year of
+    > development closely, or that they must know even if they are too lazy to
+    > read the release notes. If this is a major release that is not
+    > backward-compatible with prior versions, warn about that here.)
+    > 
+    > Enjoy, and please report any problems. We will continue to make patch
+    > releases to the 1.2 family roughly monthly, which will contain bug fixes
+    > and non-breaking enhancements.
+    > 
+    > The older 1.1 series of releases is now considered obsolete. We will
+    > continue for now to make 1.1 patch releases, but over time, these will
+    > become less frequent and be reserved for only the most critical bug
+    > fixes.
+    > 
+    > The "master" branch is now progressing toward an eventual 1.3 release next
+    > summer. As usual, you are welcome to use master for real work, but we do
+    > not make any compatibility guarantees and don't guarantee continuing API
+    > compatibility in master.
+    >
+    > (Paste the full set of 1.2 changes here, just copy the appropriate
+    > part of CHANGES.md)
+
+   For a beta leading up to the annual major/minor release:
+
+    > OpenImageIO version 1.2 is now in beta, tagged as "v1.2.3.4-beta". We
+    > will try very hard not to make any further API or ABI changes between
+    > now and the final release (unless it is absolutely necessary to fix
+    > an important problem identified during beta testing). The final 1.2
+    > release is scheduled for [DATE GOES HERE], so please try building and
+    > testing the beta so we are sure to find any problems.
+    > 
+    > Release notes for 1.2 outlining all the changes since last year's
+    > release are below.
+    > 
+    > (Paste the full set of 1.2 changes here, just copy the appropriate
+    > part of CHANGES.md)
+
+
+### After the release
+
+Odds and ends to do after the tag is pushed and the announcements are sent:
+
+- Re-read RELEASING.md and ensure that the instructions match what you
+  have done. Update as necessary.
+
+- Go to readthedocs.org, and ensure that the new release is built and visible.
+  I tend to keep the latest patch of each minor release available for
+  reference indefinitely, but hide the docs for earlier patch releases within
+  that minor release series.
+
+- Edit the top-level CMakeList.txt to update the version to the *next*
+  anticipated release on the branch, in order to ensure that anybody building
+  from subsequent patches won't get a release number that advertises itself
+  incorrectly as a prior tagged release. Also edit CHANGES.md to add a new
+  (blank) heading for the next patch or release.
+
+