Line data    Source code

       1           0 : \cond NEVER
       2             : Distributed under the MIT License.
       3             : See LICENSE.txt for details.
       4             : \endcond
       5             : 
       6             : # Versioning and releases {#versioning_and_releases}
       7             : 
       8             : \tableofcontents
       9             : 
      10             : # Version format
      11             : 
      12             : We employ a date-based versioning scheme with the format `YYYY.0M.0D[.TWEAK]`,
      13             : where `YYYY` is the year, `0M` the zero-padded month and `0D` the zero-padded
      14             : day of the month when the version is released. If additional versions are
      15             : released on a single day, the `TWEAK` component enumerates them. For example,
      16             : the first version released on May 4th, 2021 carries the name `2021.05.04`.
      17             : Additional versions released on May 4th, 2021 would carry the names
      18             : `2021.05.04.1`, `2021.05.04.2`, etc.
      19             : 
      20             : The reason we use a date-based versioning scheme over, for example, semantic
      21             : versioning is to avoid implying a notion of compatibility between releases (see
      22             : section below).
      23             : 
      24             : # Guarantees and non-guarantees of releases
      25             : 
      26             : Each release is **guaranteed** to pass all automated tests laid out in the
      27             : \ref github_actions_guide "guide on automated tests".
      28             : 
      29             : We provide **no guarantee** that releases satisfy any notion of "compatibility"
      30             : with each other. In particular, the interface of any C++ library, Python module
      31             : or executable may change between releases. When writing code for SpECTRE we
      32             : recommend regularly rebasing on the latest `develop` branch of the
      33             : [`sxs-collaboration/spectre`](https://github.com/sxs-collaboration/spectre)
      34             : repository and aiming to contribute your code upstream by following our \ref
      35             : contributing_to_spectre "contributing guide" in a timely manner. That said, we
      36             : make an effort to retain compatibility between releases for the following
      37             : aspects of the code:
      38             : 
      39             : - Simulation data: We try to ensure that data produced by a release remains
      40             :   compatible with future releases, in the sense that the data can be read,
      41             :   processed or converted to newer formats.
      42             : - Python bindings: We try to offer deprecation warnings when changing the Python
      43             :   interfaces so developers of external packages that use the Python bindings
      44             :   have time to update their packages.
      45             : 
      46             : We may establish guarantees for specific interfaces related to these aspects.
      47             : These guarantees will be defined in the documentation of the respective
      48             : interface.
      49             : 
      50             : We explicitly provide **no guarantee** that input files remain compatible with
      51             : executables built on different releases. Instead, we try to make input files as
      52             : explicit as possible by not supporting default values, so simulations don't
      53             : continue with subtly changed parameters part way through. We try to reflect
      54             : changes that would affect running simulations in the input files, so they can
      55             : (and often must) be reviewed before the simulation continues. Please note that
      56             : low-level changes or bugs may always alter results, so be advised to stick with
      57             : a particular compiled executable if a high level of reproducibility is crucial
      58             : for your project.
      59             : 
      60             : # Schedule
      61             : 
      62             : We typically publish a release at the beginning of each month, and may publish
      63             : additional releases irregularly. If a major bug is discovered and fixed we will
      64             : likely create an unscheduled release.
      65             : 
      66             : # How to find releases
      67             : 
      68             : You can find all releases on GitHub:
      69             : 
      70             : - [sxs-collaboration/spectre releases on GitHub](https://github.com/sxs-collaboration/spectre/releases)
      71             : 
      72             : Each release is tagged with the version name and prefixed `v` in the repository.
      73             : For example, this is how you can obtain the source code for the `2020.12.07`
      74             : release:
      75             : 
      76             : ```sh
      77             : git clone -b v2020.12.07 https://github.com/sxs-collaboration/spectre
      78             : ```
      79             : 
      80             : The latest release is always available on the `release` branch. This is how you
      81             : can obtain the source code for the latest release:
      82             : 
      83             : ```sh
      84             : git clone -b release https://github.com/sxs-collaboration/spectre
      85             : ```