You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add comprehensive clickable links for all Docker image tags in release notes
6
+
7
+
Updated release notes generation to include 4 structured tables with clickable links for every Docker image tag (multi-arch, amd64, arm64) on both Docker Hub and GitHub Container Registry.
# Case Study: Issue #39 - Multi-arch Docker Image Tags in Release Notes
2
+
3
+
## Summary
4
+
5
+
This case study documents the investigation and resolution of GitHub issue #39, which identified incomplete documentation of Docker image tags in release notes. The release notes were not providing clickable links for all architecture-specific tags, making it difficult for users to find and pull specific architecture images from both Docker Hub and GitHub Container Registry (GHCR).
6
+
7
+
## Timeline
8
+
9
+
| Date | Event |
10
+
|------|-------|
11
+
| 2026-02-01 | v1.3.0 released with limited architecture-specific tag documentation |
12
+
| 2026-02-13 | v1.3.2 released with improved but still incomplete tag documentation |
13
+
| 2026-02-15 | Issue #39 opened identifying the documentation gap |
The release notes at [v1.3.0](https://github.com/link-foundation/sandbox/releases/tag/v1.3.0) did not include:
21
+
- Architecture-specific tags (-amd64, -arm64) for language sandboxes
22
+
- Architecture-specific tags for essentials and JS sandboxes
23
+
- Separate GHCR listings with all architecture variants
24
+
25
+
### Partial Fix in v1.3.2
26
+
27
+
The [v1.3.2](https://github.com/link-foundation/sandbox/releases/tag/v1.3.2) release improved documentation by:
28
+
- Adding architecture tags for Full Sandbox, Essentials, and JS sandboxes
29
+
- Adding a table for language sandboxes with architecture columns
30
+
31
+
However, the table still had issues:
32
+
- Only the Multi-arch column had clickable links to Docker Hub
33
+
- AMD64 and ARM64 columns showed tag names without clickable links
34
+
- GHCR section only mentioned that images are "available" without clickable links for each variant
35
+
36
+
### User Requirement (from comment)
37
+
38
+
The user requested:
39
+
> "We need to have table for all images... for each tag we should have clickable link, and not only on Docker Hub, but also in GitHub Registry. So we should have at least 6 columns for each language version, or we can have 4 tables, so 2 of them are for language sandboxes, and 1 of these table will be dedicated to Docker Hub, and another for GitHub Registry, so in both table we will have 3 columns with clickable links."
40
+
41
+
## Root Cause
42
+
43
+
The release notes generation in `.github/workflows/release.yml` at the `create-release` job used a template that:
44
+
45
+
1. Created markdown tables without clickable links for architecture-specific tags
46
+
2. Only linked the multi-arch tag to Docker Hub for language sandboxes
47
+
3. Listed GHCR images in text format without individual clickable links for each architecture
48
+
49
+
## Solution
50
+
51
+
### Design Decision
52
+
53
+
After analyzing the options, we chose to use **4 separate tables** approach:
54
+
- 2 tables for Docker Hub (combo sandboxes + language sandboxes)
55
+
- 2 tables for GHCR (combo sandboxes + language sandboxes)
56
+
57
+
This provides better readability than cramming 6 columns into one table, especially on mobile devices.
58
+
59
+
### Implementation
60
+
61
+
Modified the release notes template in `.github/workflows/release.yml` to generate:
62
+
63
+
1.**Docker Hub Combo Sandboxes Table**: Full, Essentials, JS sandboxes with 3 clickable link columns
64
+
2.**Docker Hub Language Sandboxes Table**: All 11 languages with 3 clickable link columns
65
+
3.**GHCR Combo Sandboxes Table**: Full, Essentials, JS sandboxes with 3 clickable link columns
66
+
4.**GHCR Language Sandboxes Table**: All 11 languages with 3 clickable link columns
1.**User Experience**: Release notes should make it easy for users to directly access what they need. Clickable links are more valuable than plain text tags.
75
+
76
+
2.**Multi-registry Support**: Modern container distributions often publish to multiple registries (Docker Hub + GHCR). Documentation should equally serve users of both registries.
77
+
78
+
3.**Architecture Awareness**: With ARM64 adoption increasing (Apple Silicon, Raspberry Pi, AWS Graviton), architecture-specific documentation is increasingly important.
79
+
80
+
## Files Changed
81
+
82
+
-`.github/workflows/release.yml`: Updated `create-release` job to generate comprehensive tables with clickable links
83
+
84
+
## Testing
85
+
86
+
The release notes format can be validated by:
87
+
1. Running the workflow manually with `workflow_dispatch`
88
+
2. Checking that all generated links are valid and point to correct registry pages
0 commit comments