Skip to content

Commit c33f926

Browse files
ppkarwaszppkarwasz
committed
fix: Improve release examples
Signed-off-by: Piotr P. Karwasz <[email protected]>
1 parent 7fc30f6 commit c33f926

File tree

1 file changed

+201
-29
lines changed

1 file changed

+201
-29
lines changed

‎tea-collection/tea-collection.md‎

Lines changed: 201 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
## The TEA Component Release object (TRO)
44

55
A TEA Component Release object represents a specific version of a component,
6-
identified by a unique release identifier and associated metadata.
6+
identified by a unique version number and associated metadata.
77
Each release may include multiple distributions,
88
which capture variations such as architecture, packaging, or localization.
99

@@ -49,55 +49,227 @@ A TEA Component Release object contains the following fields:
4949

5050
### Examples
5151

52-
A TEA Component Release object of the binary distribution of Apache Tomcat 11.0.6 will look like:
52+
#### Single distribution
5353

54-
```json
55-
{
56-
"uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
57-
"version": "11.0.6",
58-
"releaseDate": "2025-04-01T15:43:00Z",
59-
"identifiers": [
60-
{
61-
"idType": "purl",
62-
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
63-
}
64-
]
65-
}
66-
```
54+
This example shows a TEA Component Release for Apache Log4j Core, which is distributed as a single JAR file.
55+
Even though there is only one distribution,
56+
the `distributions` attribute is included to enable searching for the release by the SHA-256 checksum of the JAR.
57+
This structure also allows for future extensibility if additional distributions are introduced.
6758

68-
Different versions of Apache Tomcat should have separate TEA Component Release objects:
59+
<details>
60+
<summary>Example of simple release</summary>
6961

7062
```json
7163
{
72-
"uuid": "da89e38e-95e7-44ca-aa7d-f3b6b34c7fab",
73-
"version": "10.1.4",
74-
"releaseDate": "2025-04-01T18:20:00Z",
64+
"uuid": "b1e2c3d4-5678-49ab-9cde-123456789abc",
65+
"version": "2.24.3",
66+
"createdDate": "2024-12-10T10:51:00Z",
67+
"releaseDate": "2024-12-13T12:52:29Z",
7568
"identifiers": [
7669
{
77-
"idType": "purl",
78-
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
70+
"idType": "PURL",
71+
"idValue": "pkg:maven/org.apache.logging.log4j/[email protected]"
72+
}
73+
],
74+
"distributions": [
75+
{
76+
"distributionType": "jar",
77+
"description": "Binary distribution",
78+
"identifiers": [
79+
{
80+
"idType": "PURL",
81+
"idValue": "pkg:maven/org.apache.logging.log4j/[email protected]?type=jar"
82+
}
83+
],
84+
"checksums": [
85+
{
86+
"algType": "SHA-256",
87+
"algValue": "b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890b1e2c3d4f5a67890"
88+
}
89+
],
90+
"url": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar",
91+
"signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/logging/log4j/log4j-core/2.24.3/log4j-core-2.24.3.jar.asc"
7992
}
8093
]
8194
}
8295
```
96+
</details>
97+
98+
#### Multiple distributions
8399

84-
The pre-release flag is used to mark versions not production ready
85-
and does not require users to know the version naming scheme adopted by the project.
100+
This is an example of a TEA Component Release for Apache Tomcat 11.0.7 binary distributions.
101+
The example defines four distinct `distributionType`s,
102+
which is essential not only for associating the correct SBOMs with each distribution,
103+
but also for accurately tracking and reporting vulnerabilities that may affect only specific distributions.
104+
For instance:
105+
106+
- The `zip` and `tar.gz` distributions contain only Java JARs.
107+
- The `windows-x64.zip` distribution additionally includes the
108+
[Apache Procrun](https://commons.apache.org/proper/commons-daemon/procrun.html) binary,
109+
which is specific to Windows and may introduce unique vulnerabilities.
110+
- The `windows-x64.exe` distribution contains the same data as `windows-x64.zip`,
111+
but is packaged as a self-extracting installer
112+
created by the [Nullsoft Scriptable Install System](https://nsis.sourceforge.io/Main_Page).
113+
114+
By defining separate `distributionType`s,
115+
it becomes possible to precisely associate artifacts and vulnerability disclosures with the affected distributions,
116+
ensuring accurate risk assessment and remediation.
117+
118+
<details>
119+
<summary>Example of four different binary distributions in the same release</summary>
86120

87121
```json
88122
{
89-
"uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
90-
"version": "11.0.0-M26",
91-
"releaseDate": "2024-09-13T17:49:00Z",
92-
"preRelease": true,
123+
"uuid": "605d0ecb-1057-40e4-9abf-c400b10f0345",
124+
"version": "11.0.7",
125+
"createdDate": "2025-05-07T18:08:00Z",
126+
"releaseDate": "2025-05-12T18:08:00Z",
93127
"identifiers": [
94128
{
95-
"idType": "purl",
96-
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
129+
"idType": "PURL",
130+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
131+
}
132+
],
133+
"distributions": [
134+
{
135+
"distributionType": "zip",
136+
"description": "Core binary distribution, zip archive",
137+
"identifiers": [
138+
{
139+
"idType": "PURL",
140+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]?type=zip"
141+
}
142+
],
143+
"checksums": [
144+
{
145+
"algType": "SHA_256",
146+
"algValue": "9da736a1cdd27231e70187cbc67398d29ca0b714f885e7032da9f1fb247693c1"
147+
}
148+
],
149+
"url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip",
150+
"signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc"
151+
},
152+
{
153+
"distributionType": "tar.gz",
154+
"description": "Core binary distribution, tar.gz archive",
155+
"identifiers": [
156+
{
157+
"idType": "PURL",
158+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]?type=tar.gz"
159+
}
160+
],
161+
"checksums": [
162+
{
163+
"algType": "SHA_256",
164+
"algValue": "2fcece641c62ba1f28e1d7b257493151fc44f161fb391015ee6a95fa71632fb9"
165+
}
166+
],
167+
"url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz",
168+
"signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.tar.gz.asc"
169+
},
170+
{
171+
"distributionType": "windows-x64.zip",
172+
"description": "Core binary distribution, Windows x64 zip archive",
173+
"identifiers": [
174+
{
175+
"idType": "PURL",
176+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]?classifier=windows-x64&type=zip"
177+
}
178+
],
179+
"checksums": [
180+
{
181+
"algType": "SHA_256",
182+
"algValue": "62a5c358d87a8ef21d7ec1b3b63c9bbb577453dda9c00cbb522b16cee6c23fc4"
183+
}
184+
],
185+
"url": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6-windows-x64.zip",
186+
"signatureUrl": "https://repo.maven.apache.org/maven2/org/apache/tomcat/tomcat/11.0.7/tomcat-11.0.6.zip.asc"
187+
},
188+
{
189+
"distributionType": "windows-x64.exe",
190+
"description": "Core binary distribution, Windows Service Installer (MSI)",
191+
"checksums": [
192+
{
193+
"algType": "SHA_512",
194+
"algValue": "1d3824e7643c8aba455ab0bd9e67b14a60f2aaa6aa7775116bce40eb0579e8ced162a4f828051d3b867e96ee2858ec5da0cc654e83a83ba30823cbea0df4ff96"
195+
}
196+
],
197+
"url": "https://dlcdn.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe",
198+
"signatureUrl": "https://downloads.apache.org/tomcat/tomcat-11/v11.0.7/bin/apache-tomcat-11.0.7.exe.asc"
97199
}
98200
]
99201
}
100202
```
203+
</details>
204+
205+
#### Pre-release flag usage
206+
207+
The `preRelease` flag is used to indicate that a release is not production ready,
208+
regardless of the version naming scheme.
209+
This helps consumers identify non-production releases without relying on conventions like `-beta`,
210+
`-rc`, or `-M` in the version string.
211+
212+
There are two main scenarios for using the `preRelease` flag:
213+
214+
- **Pending release:** The distribution is still undergoing quality assurance or review and is not yet officially released.
215+
These typically lack a `releaseDate` attribute.
216+
Once the release is approved, the `preRelease` flag is set to `false` and the `releaseDate` is added.
217+
- **Permanent pre-release:** The distribution is intentionally marked as a pre-release
218+
(e.g., beta, milestone, or release candidate) and will never be considered production ready,
219+
even after all checks are complete.
220+
These may have a `releaseDate`, but `preRelease` remains `true`.
221+
222+
<details>
223+
<summary>Examples of non-production ready distributions</summary>
224+
225+
- **Pending release (no `releaseDate`):**
226+
```json
227+
{
228+
"uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
229+
"version": "11.0.0",
230+
"createdDate": "2025-09-01T00:00:00Z",
231+
"preRelease": true,
232+
"identifiers": [
233+
{
234+
"idType": "purl",
235+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]?repository_url=https:%2F%2Frepository.apache.org%2Fcontent%2Fgroups%2Fstaging%2F"
236+
}
237+
]
238+
}
239+
```
240+
- **Transition to production-ready (`preRelease` flag turned off, `releaseDate` added)**:
241+
```json
242+
{
243+
"uuid": "e2a1c7b4-3f2d-4e8a-9c1a-7b2e4d5f6a8b",
244+
"version": "11.0.0",
245+
"createdDate": "2025-09-01T00:00:00Z",
246+
"releaseDate": "2025-09-10T12:00:00Z",
247+
"preRelease": false,
248+
"identifiers": [
249+
{
250+
"idType": "purl",
251+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
252+
}
253+
]
254+
}
255+
```
256+
- **Beta version (has `releaseDate`, but not production ready)**:
257+
```json
258+
{
259+
"uuid": "95f481df-f760-47f4-b2f2-f8b76d858450",
260+
"version": "11.0.0-M26",
261+
"createdDate": "2024-09-13T17:49:00Z",
262+
"releaseDate": "2024-09-16T17:49:00Z",
263+
"preRelease": true,
264+
"identifiers": [
265+
{
266+
"idType": "purl",
267+
"idValue": "pkg:maven/org.apache.tomcat/[email protected]"
268+
}
269+
]
270+
}
271+
```
272+
</details>
101273

102274
## The TEA Collection object (TCO)
103275

0 commit comments

Comments
 (0)