spack/lib/spack/docs
Harmen Stoppels c3eaf4d6cf
Support for prereleases (#43140)
This adds support for prereleases. Alpha, beta and release candidate
suffixes are ordered in the intuitive way:

```
1.2.0-alpha < 1.2.0-alpha.1 < 1.2.0-beta.2 < 1.2.0-rc.3 < 1.2.0 < 1.2.0-xyz
```

Alpha, beta and rc prereleases are defined as follows: split the version
string into components like before (on delimiters and string boundaries).
If there's a string component `alpha`, `beta` or `rc` followed by an optional
numeric component at the end, then the version is prerelease.

So `1.2.0-alpha.1 == 1.2.0alpha1 == 1.2.0.alpha1` are all the same, as usual.

The strings `alpha`, `beta` and `rc` are chosen because they match semver,
they are sufficiently long to be unambiguous, and and all contain at least
one non-hex character so distinguish them from shasum/digest type suffixes.

The comparison key is now stored as `(release_tuple, prerelease_tuple)`, so in
the above example:

```
((1,2,0),(ALPHA,)) < ((1,2,0),(ALPHA,1)) < ((1,2,0),(BETA,2)) < ((1,2,0),(RC,3)) < ((1,2,0),(FINAL,)) < ((1,2,0,"xyz"), (FINAL,))
```

The version ranges `@1.2.0:` and `@:1.1` do *not* include prereleases of
`1.2.0`.

So for packaging, if the `1.2.0alpha` and `1.2.0` versions have the same constraints on
dependencies, it's best to write

```python
depends_on("x@1:", when="@1.2.0alpha:")
```

However, `@1.2:` does include `1.2.0alpha`. This is because Spack considers
`1.2 < 1.2.0` as distinct versions, with `1.2 < 1.2.0alpha < 1.2.0` as a consequence.

Alternatively, the above `depends_on` statement can thus be written

```python
depends_on("x@1:", when="@1.2:")
```

which can be useful too. A short-hand to include prereleases, but you
can still be explicit to exclude the prerelease by specifying the patch version
number.

### Concretization

Concretization uses a different version order than `<`. Prereleases are ordered
between final releases and develop versions. That way, users should not
have to set `preferred=True` on every final release if they add just one
prerelease to a package. The concretizer is unlikely to pick a prerelease when
final releases are possible.

### Limitations

1. You can't express a range that includes all alpha release but excludes all beta
   releases. Only alternative is good old repeated nines: `@:1.2.0alpha99`.

2. The Python ecosystem defaults to `a`, `b`, `rc` strings, so translation of Python versions to
   Spack versions requires expansion to `alpha`, `beta`, `rc`. It's mildly annoying, because
   this means we may need to compute URLs differently (not done in this commit).

### Hash

Care is taken not to break hashes of versions that do not have a prerelease
suffix.
2024-03-22 23:30:32 +01:00
..
_gh_pages_redirect Use https for links (#19244) 2020-10-09 11:24:09 -05:00
_pygments Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
_static make empty _static directory "exist" to git 2014-01-09 14:03:32 +01:00
build_systems Fix CMake generator documentation (#43232) 2024-03-18 10:02:33 +01:00
example_files Implement an optional compiler bootstrapping phase 2019-09-13 22:57:15 -07:00
images Cherry-picking virtual dependencies (#35322) 2023-11-01 23:35:23 -07:00
tables AutotoolsPackage / MakefilePackage: add gmake build dependency (#40380) 2023-10-18 19:56:54 +02:00
.gitignore docs: Replace package list with packages.spack.io (#40251) 2023-10-01 05:36:22 +02:00
basic_usage.rst Support for prereleases (#43140) 2024-03-22 23:30:32 +01:00
binary_caches.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
bootstrapping.rst Fix spack find bootstrapping docs (#43074) 2024-03-07 14:13:32 +01:00
build_settings.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
build_systems.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
chain.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
command_index.in Rework command reference in docs, add spack commands command 2018-02-12 20:25:17 -08:00
conf.py compression.py: refactor + bug fix (#42367) 2024-01-31 07:59:07 +01:00
config_yaml.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
configuration.rst Allow loading extensions through python entry-points (#42370) 2024-03-06 11:18:49 +01:00
containers.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
contribution_guide.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
developer_guide.rst hooks: remove 7 unused hooks (#42575) 2024-02-09 20:52:09 +01:00
environments.rst Document new environment variable expansion in projections (#42963) 2024-03-04 12:17:08 -07:00
extensions.rst Allow loading extensions through python entry-points (#42370) 2024-03-06 11:18:49 +01:00
features.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
frequently_asked_questions.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
getting_started.rst Allow compilers to be configured in packages.yaml (#42016) 2024-03-15 11:01:49 +01:00
gpu_configuration.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
index.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
Makefile API Docs: fix broken reference targets 2021-07-16 08:30:56 -07:00
mirrors.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
module_file_generation.svg SC17: reworked module file tutorial section (#5657) 2017-11-12 00:27:20 -08:00
module_file_support.rst modules: allow autoload: run, like in environment views (#42743) 2024-03-04 08:49:45 +01:00
packages_yaml.rst develop: Add -b/--build-directory option to set build_directory package attribute (#39606) 2024-02-16 06:30:58 +00:00
packaging_guide.rst Support for prereleases (#43140) 2024-03-22 23:30:32 +01:00
pipelines.rst docs: git version section title + highlight issues (#42398) 2024-02-01 09:46:17 +01:00
replace_conda_homebrew.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
repositories.rst docs: fix typo (#42688) 2024-02-15 11:21:51 +01:00
requirements.txt build(deps): bump black from 24.2.0 to 24.3.0 in /lib/spack/docs (#43228) 2024-03-15 17:24:44 -06:00
signing.rst Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00
spack.yaml Update copyright year to 2024 (#41919) 2024-01-02 09:21:30 +01:00