Skip to content

Commit 1657ff7

Browse files
yeoldegroveyeoldegrove
authored
Merge pull request #13 from gardenlinux/feat/bump_python_gardenlinux_lib
 refactor to work with gardenlinux 0.10.24
2 parents 19cdb3a + da8d811 commit 1657ff7

45 files changed

Lines changed: 5057 additions & 3122 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.coverage‎

-52 KB
Binary file not shown.

‎.gitignore‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
*.egg-info
22
**/__pycache__
3-
.artifacts_cache.json
4-
.artifacts_index.json
53
.envrc
64
.venv
75
_build
86
dist/
7+
glrd/artifacts-cache.json
98
shell.nix
109
releases.json
1110
releases.yaml

‎Containerfile‎

Lines changed: 1 addition & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -12,18 +12,10 @@ ENV POETRY_HOME=/opt/poetry
1212
ENV DEBIAN_FRONTEND noninteractive
1313
ENV PATH=${POETRY_HOME}/bin:/app/.venv/bin:$PATH
1414

15-
# install runtime dependencies and GitHub CLI
15+
# install runtime dependencies
1616
RUN apt-get update \
1717
&& apt-get install -y --no-install-recommends \
1818
${PYTHON}-venv \
19-
git \
20-
curl \
21-
&& mkdir -p -m 755 /etc/apt/keyrings \
22-
&& curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
23-
&& chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
24-
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
25-
&& apt-get update \
26-
&& apt-get install -y --no-install-recommends gh \
2719
&& apt-get clean && rm -rf /var/lib/apt/lists/*
2820

2921
# Install poetry

‎docs/explanation/.gitkeep‎

Whitespace-only changes.

‎docs/explanation/release-lifecycle.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: "GLRD Release Lifecycle"
3+
description: "Explains lifecycle dependencies between major and minor releases, default date calculations, nightly and dev date rules, and the GLRD versioning scheme."
4+
github_org: gardenlinux
5+
github_repo: glrd
6+
github_source_path: docs/explanation/release-lifecycle.md
7+
github_target_path: docs/explanation/glrd-release-lifecycle.md
8+
related_topics:
9+
- /reference/supporting_tools/glrd/
10+
- /reference/supporting_tools/glrd/cli.md
11+
- /reference/supporting_tools/glrd/schema.md
12+
- /how-to/releases/glrd/
13+
- /how-to/releases/glrd/run-glrd.md
14+
- /how-to/releases/glrd/query-releases.md
15+
- /how-to/releases/glrd/manage-releases.md
16+
- /explanation/glrd-release-lifecycle.md
17+
---
18+
19+
# GLRD Release Lifecycle
20+
21+
This page explains the lifecycle model used by the Garden Linux Release Database (GLRD): why lifecycle phases are structured the way they are, how dates are calculated by default, and how the versioning scheme works.
22+
23+
## Lifecycle phases
24+
25+
Every release in GLRD has a `lifecycle` object. The phases present depend on the release type:
26+
27+
| Phase | Present for types | Meaning |
28+
| ---------- | ------------------------ | ------------------------------------------------------------------ |
29+
| `released` | all | The date the release was published. |
30+
| `extended` | `major`, `next` | The date extended maintenance begins (after standard maintenance). |
31+
| `eol` | `major`, `next`, `minor` | The date support ends entirely. |
32+
33+
`nightly` and `dev` releases do not have `extended` or `eol` phases because they are not supported beyond their immediate build date.
34+
35+
## Default major dates
36+
37+
When you create a major release without explicitly setting `extended` or `eol` dates, GLRD calculates defaults based on the [Garden Linux Release Plan](/reference/releases/release-lifecycle.md):
38+
39+
- **`extended`** = `released` date + 6 months
40+
- **`eol`** = `released` date + 9 months
41+
42+
**Example — `major-1443`:**
43+
44+
| Phase | Date |
45+
| ---------- | ----------------------- |
46+
| `released` | 2024-03-13 |
47+
| `extended` | 2024-09-13 (+ 6 months) |
48+
| `eol` | 2025-01-13 (+ 9 months) |
49+
50+
You can always override the calculated defaults by passing `--lifecycle-extended-isodatetime` and `--lifecycle-eol-isodatetime` to `glrd-manage --create`.
51+
52+
## Major and minor release dependencies
53+
54+
There is a dependency between the `lifecycle.eol` fields of major and minor releases within the same major version:
55+
56+
- **Intermediate minor releases**: The `eol` of each minor release is set to the `released` date of the next minor release in the same major series. This means support for a given minor ends when the next patch is available.
57+
- **Latest minor release**: The `eol` of the most recent minor release always matches the `eol` of the parent major release. This ensures the final patch remains supported until the major version reaches end-of-life.
58+
- **Major release `eol`**: Marks the end of support for the entire major version, including all its minor releases.
59+
60+
When you create a new minor release with `glrd-manage --create minor`, the previous minor release's `eol` is automatically updated to the new minor release's `released` date.
61+
62+
:::info Note on the extended phase
63+
The `extended` lifecycle field applies to major releases only. It has no direct technical effect on minor releases and is an administrative date that tracks when extended maintenance begins for the parent major version.
64+
:::
65+
66+
**Example — `major-1312` series:**
67+
68+
| Release | `released` | `eol` | Reason |
69+
| -------------- | ---------- | ---------- | ------------------------------- |
70+
| `major-1312` | 2023-11-16 | 2024-08-03 | Major EOL |
71+
| `minor-1312.1` | 2023-11-23 | 2024-01-15 | Next minor release date |
72+
| `minor-1312.2` | 2024-01-15 | 2024-02-14 | Next minor release date |
73+
| `minor-1312.7` | 2024-07-03 | 2024-08-03 | Inherits major EOL (last minor) |
74+
75+
## Nightly and development release dates
76+
77+
`nightly` and `dev` releases only carry a `released` date. They have no `extended` or `eol` phase because:
78+
79+
- Nightly builds are ephemeral: each nightly is superseded by the next nightly run.
80+
- Development releases are manual snapshots for testing; they are not formally supported.
81+
82+
## Versioning scheme
83+
84+
Garden Linux [introduced semantic versioning](https://github.com/gardenlinux/gardenlinux/issues/3069) starting at major version `2017`. GLRD stores both pre- and post-threshold releases and selects the correct schema automatically:
85+
86+
| Scheme | Applies to | Version format | Example |
87+
| ------ | ------------ | ------------------- | ---------------------- |
88+
| v1 | major < 2017 | `major.minor` | `1592.6`, `27.0` |
89+
| v2 | major ≥ 2017 | `major.minor.patch` | `2017.0.0`, `2222.1.5` |
90+
91+
The threshold is defined as `V2_SCHEMA_THRESHOLD = 2017` in the GLRD codebase (`glrd/util.py`). Any release with a `version.major` value of 2017 or higher uses the v2 schema and requires the `patch` field in `version` objects for `minor`, `nightly`, and `dev` releases.
92+
93+
For `major` and `next` releases, the version only ever stores `major`; the distinction between v1 and v2 does not affect their schema shape.
94+
95+
<RelatedTopics />

‎docs/how-to/.gitkeep‎

Whitespace-only changes.

‎docs/how-to/index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: "Garden Linux Release Database (GLRD)"
3+
description: "How-to guides for running, querying, and managing Garden Linux Release Database (GLRD) entries."
4+
order: 4
5+
github_org: gardenlinux
6+
github_repo: glrd
7+
github_source_path: docs/how-to/index.md
8+
github_target_path: docs/how-to/releases/glrd/index.md
9+
related_topics:
10+
- /how-to/releases/glrd/
11+
- /how-to/releases/glrd/run-glrd.md
12+
- /how-to/releases/glrd/query-releases.md
13+
- /how-to/releases/glrd/manage-releases.md
14+
- /reference/supporting_tools/glrd/
15+
- /reference/supporting_tools/glrd/cli.md
16+
- /reference/supporting_tools/glrd/schema.md
17+
- /explanation/glrd-release-lifecycle.md
18+
---
19+
20+
# GLRD How-To Guides
21+
22+
These guides cover the day-to-day tasks for working with the Garden Linux Release Database (GLRD). GLRD stores and provides release information for the Garden Linux distribution, accessed and managed through two command-line tools: `glrd` (query) and `glrd-manage` (create and update).
23+
24+
## Related topics
25+
26+
<RelatedTopics />

‎docs/how-to/manage-releases.md‎

Lines changed: 231 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,231 @@
1+
---
2+
title: "Manage GLRD entries"
3+
description: "Step-by-step examples for creating, updating, and deleting Garden Linux releases database entries using the glrd-manage CLI tool."
4+
order: 3
5+
github_org: gardenlinux
6+
github_repo: glrd
7+
github_source_path: docs/how-to/manage-releases.md
8+
github_target_path: docs/how-to/releases/glrd/manage-releases.md
9+
related_topics:
10+
- /how-to/releases/glrd/
11+
- /how-to/releases/glrd/run-glrd.md
12+
- /how-to/releases/glrd/query-releases.md
13+
- /how-to/releases/glrd/manage-releases.md
14+
- /reference/supporting_tools/glrd/
15+
- /reference/supporting_tools/glrd/cli.md
16+
- /reference/supporting_tools/glrd/schema.md
17+
- /explanation/glrd-release-lifecycle.md
18+
---
19+
20+
# Manage Garden Linux Releases
21+
22+
This guide shows how to use `glrd-manage` to create, update, and delete releases in the Garden Linux Release Database (GLRD).
23+
24+
## Prerequisites
25+
26+
- `glrd-manage` installed. See [Run GLRD](/how-to/releases/glrd/run-glrd.md).
27+
- AWS credentials with write access to the S3 bucket when you intend to push changes with `--s3-update`. See [AWS authentication](/how-to/releases/glrd/run-glrd.md#aws-authentication-for-glrd-manage).
28+
29+
:::warning Safe testing
30+
All examples on this page omit `--s3-update`. Without that flag, `glrd-manage` writes output files to the current directory and makes no changes to S3. Add `--s3-update` only when you are ready to publish.
31+
:::
32+
33+
## Test locally
34+
35+
By default, `glrd-manage` writes release files (for example, `releases-minor.json`) to the current working directory and does not touch S3. You can inspect the generated files to verify the output before running with `--s3-update`.
36+
37+
## Generate initial release data
38+
39+
:::info GITHUB_TOKEN required
40+
`--create-initial-releases` fetches release history from the GitHub API via
41+
[python-gardenlinux-lib](https://github.com/gardenlinux/python-gardenlinux-lib).
42+
Set the `GITHUB_TOKEN` environment variable before running this command. The
43+
token needs no special scopes for the public Garden Linux repository.
44+
45+
```bash
46+
export GITHUB_TOKEN=<your-token>
47+
# Or, if you have the GitHub CLI installed:
48+
export GITHUB_TOKEN=$(gh auth token)
49+
```
50+
51+
:::
52+
53+
Use `--create-initial-releases` to fetch the full release history from GitHub and generate all initial release files. Pass the types you want to populate as a comma-separated list:
54+
55+
```bash
56+
glrd-manage --create-initial-releases major,minor,nightly --input
57+
```
58+
59+
This generates `releases-major.json`, `releases-minor.json`, `releases-nightly.json`, and processes any manual lifecycle entries from `releases-input.yaml`.
60+
61+
## Create a major release
62+
63+
When you create a major release, GLRD automatically calculates default `extended` and `eol` dates (released + 6 months and + 9 months respectively). See [Default major dates](/explanation/glrd-release-lifecycle.md#default-major-dates) for details.
64+
65+
```bash
66+
# Use default dates
67+
glrd-manage --create major --version 1312
68+
69+
# Override dates explicitly
70+
glrd-manage --create major --version 1312 \
71+
--lifecycle-released-isodatetime 2023-11-16T00:00:00 \
72+
--lifecycle-extended-isodatetime 2024-05-03T00:00:00 \
73+
--lifecycle-eol-isodatetime 2024-08-03T00:00:00
74+
```
75+
76+
## Create a minor release
77+
78+
When you create a new minor release, `glrd-manage` automatically sets the `eol` of the previous minor release to the new release's `released` date. See [Major and minor release dependencies](/explanation/glrd-release-lifecycle.md#major-and-minor-release-dependencies) for details.
79+
80+
```bash
81+
glrd-manage --create minor --version 1312.7
82+
```
83+
84+
## Create a nightly release
85+
86+
Without additional parameters, `glrd-manage` uses the current timestamp and the current git commit to create a nightly release. The next available minor version number is chosen automatically:
87+
88+
```bash
89+
glrd-manage --create nightly
90+
```
91+
92+
## Update an existing release
93+
94+
Use `--update` to modify lifecycle dates or the commit hash of an existing release. Specify the release by name and provide at least one modifier flag.
95+
96+
Supported modifiers:
97+
98+
- `--lifecycle-released-isodatetime`: Update the release date (all types).
99+
- `--lifecycle-extended-isodatetime`: Update the extended maintenance date (`major` and `next` only).
100+
- `--lifecycle-eol-isodatetime`: Update the end-of-life date (`next`, `major`, and `minor` only).
101+
- `--commit`: Update the git commit hash (`minor`, `nightly`, and `dev` only).
102+
103+
```bash
104+
# Update the EOL date on a major release
105+
glrd-manage --update major-1592 \
106+
--lifecycle-eol-isodatetime 2026-02-27T00:00:00 \
107+
--input-stdin < releases.json
108+
109+
# Update the extended maintenance date on a major release
110+
glrd-manage --update major-1592 \
111+
--lifecycle-extended-isodatetime 2025-06-15T00:00:00 \
112+
--input-stdin < releases.json
113+
114+
# Update the commit hash on a minor release
115+
glrd-manage --update minor-1592.6 \
116+
--commit deadbeef1234567890abcdef1234567890abcdef \
117+
--input-stdin < releases.json
118+
119+
# Update multiple fields at once
120+
glrd-manage --update major-1592 \
121+
--lifecycle-eol-isodatetime 2026-02-27T00:00:00 \
122+
--lifecycle-extended-isodatetime 2025-06-15T00:00:00 \
123+
--input-stdin < releases.json
124+
```
125+
126+
:::info
127+
The `--update` action requires existing release data to be provided via `--input-stdin` (as in the examples above) or loaded from the default query source. It cannot be combined with `--no-query`.
128+
:::
129+
130+
## Create or update a release from JSON (stdin)
131+
132+
You can provide release data directly from standard input in JSON format. This is useful for scripted workflows or when the release data is generated by another tool:
133+
134+
```bash
135+
echo '{
136+
"releases": [
137+
{
138+
"name": "minor-1592.1",
139+
"type": "minor",
140+
"version": {
141+
"major": 1592,
142+
"minor": 1
143+
},
144+
"lifecycle": {
145+
"released": {
146+
"isodate": "2024-08-22",
147+
"timestamp": 1724277600
148+
},
149+
"eol": {
150+
"isodate": "2025-08-12",
151+
"timestamp": 1754949600
152+
}
153+
},
154+
"git": {
155+
"commit": "ec945aa995d0f08d64303ff6045b313b40b665fb",
156+
"commit_short": "ec945aa"
157+
},
158+
"github": {
159+
"release": "https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1"
160+
},
161+
"flavors": [
162+
"ali-gardener_prod",
163+
"azure-gardener_prod",
164+
"aws-gardener_prod",
165+
"gcp-gardener_prod"
166+
],
167+
"attributes": {
168+
"source_repo": false
169+
}
170+
}
171+
]
172+
}' | glrd-manage --input-stdin
173+
```
174+
175+
## Create or update a release from a YAML file
176+
177+
Write the release data to a YAML input file and pass it with `--input` and `--input-file`:
178+
179+
```yaml
180+
# releases-input.yaml
181+
releases:
182+
- name: minor-1592.1
183+
type: minor
184+
version:
185+
major: 1592
186+
minor: 1
187+
lifecycle:
188+
released:
189+
isodate: "2024-08-22"
190+
timestamp: 1724277600
191+
eol:
192+
isodate: "2025-08-27"
193+
timestamp: 1754949600
194+
git:
195+
commit: ec945aa995d0f08d64303ff6045b313b40b66fff
196+
commit_short: ec945aa
197+
github:
198+
release: https://github.com/gardenlinux/gardenlinux/releases/tag/1592.1
199+
flavors:
200+
- ali-gardener_prod
201+
- azure-gardener_prod
202+
- aws-gardener_prod
203+
- gcp-gardener_prod
204+
attributes:
205+
source_repo: false
206+
```
207+
208+
```bash
209+
glrd-manage --input --input-file releases-input.yaml
210+
```
211+
212+
## Run fully offline
213+
214+
To run `glrd-manage` without any network access, combine `--input-type file` with `--no-flavors`:
215+
216+
```bash
217+
glrd-manage --create nightly \
218+
--input-type file \
219+
--no-flavors \
220+
--no-query
221+
```
222+
223+
- `--input-type file` reads existing releases from local files instead of the S3 endpoint.
224+
- `--no-flavors` skips the Git clone and S3 lookup for flavor resolution.
225+
- `--no-query` skips the initial query for existing releases entirely. Use with care — without the existing data, `glrd-manage` may overwrite releases.
226+
227+
You can also set `GLRD_SKIP_FLAVORS=1` in the environment as an alternative to `--no-flavors`.
228+
229+
## Related topics
230+
231+
<RelatedTopics />

0 commit comments

Comments
 (0)