Skip to content

Commit 3f5f1a6

Browse files
committed
docs(feature-planning): modify virtual tracks structure and release workfow
1 parent 00fd84b commit 3f5f1a6

File tree

4 files changed

+733
-315
lines changed

4 files changed

+733
-315
lines changed

docs/COLLECTIONS_V2/02_TERMINOLOGY.md

Lines changed: 62 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -158,9 +158,13 @@ The **tagging operation** marks an existing snapshot as a tagged release by assi
158158

159159
### Object Membership Tiers
160160

161-
Every snapshot (draft or tagged) contains objects which can be classified into any of three categories:
161+
The tier system differs between **standard release tracks** and **virtual release tracks**.
162162

163-
#### 1. Candidate Objects
163+
#### Standard Release Tracks: Three-Tier System
164+
165+
Standard release tracks use three tiers to manage the object lifecycle from development to release:
166+
167+
##### 1. Candidate Objects
164168

165169
**Location:** `workspace.candidates`
166170

@@ -173,12 +177,17 @@ Every snapshot (draft or tagged) contains objects which can be classified into a
173177
- Objects in this tier are NOT included in published STIX bundles by default
174178
- Automatically promoted to staged tier when status reaches the candidacy threshold
175179

180+
**Duplicate Rules:**
181+
- Cannot contain exact duplicates (same `object_ref` + `object_modified` pair)
182+
- **CAN** contain multiple versions of the same object (same `object_ref`, different `object_modified` timestamps)
183+
- Example: Can have `attack-pattern--T1234, modified: 2024-01-15` AND `attack-pattern--T1234, modified: 2024-02-20` simultaneously
184+
176185
**Examples:**
177186
- "Add these 10 techniques as candidate objects"
178187
- "There are 47 candidate objects in work-in-progress status"
179188
- "Transition candidate objects from awaiting-review to reviewed"
180189

181-
#### 2. Staged Objects
190+
##### 2. Staged Objects
182191

183192
**Location:** `workspace.staged`
184193

@@ -191,12 +200,17 @@ Every snapshot (draft or tagged) contains objects which can be classified into a
191200
- Moved to member objects tier (`x_mitre_contents`) when the snapshot is tagged
192201
- NOT included in published STIX bundles until the snapshot is tagged
193202

203+
**Duplicate Rules:**
204+
- Cannot contain exact duplicates (same `object_ref` + `object_modified` pair)
205+
- **CANNOT** contain multiple versions of the same object
206+
- If a promotion would create a duplicate (different version of same object already in staged), conflict resolution policy applies
207+
194208
**Examples:**
195209
- "There are 12 staged objects ready for the next release"
196210
- "Promote all reviewed candidates to staged"
197211
- "Preview which staged objects will be included in the next tagged release"
198212

199-
#### 3. Member Objects
213+
##### 3. Member Objects
200214

201215
**Location:** `stix.x_mitre_contents`
202216

@@ -209,11 +223,55 @@ Every snapshot (draft or tagged) contains objects which can be classified into a
209223
- Represents the production-ready, published content
210224
- Only updated when a snapshot is tagged (staged objects are promoted to members)
211225

226+
**Duplicate Rules:**
227+
- Cannot contain exact duplicates (same `object_ref` + `object_modified` pair)
228+
- **CANNOT** contain multiple versions of the same object
229+
- If a promotion would create a duplicate (different version of same object already in members), conflict resolution policy applies
230+
212231
**Examples:**
213232
- "The Enterprise release track has 3,247 member objects"
214233
- "Export all member objects as a STIX bundle"
215234
- "Which version of Technique T1234 is in the member objects?"
216235

236+
#### Virtual Release Tracks: Two-Tier System
237+
238+
Virtual release tracks use a simplified two-tier system since they aggregate already-released content:
239+
240+
##### 1. Member Objects
241+
242+
**Location:** `stix.x_mitre_contents`
243+
244+
**Definition:** Successfully synced objects from component tracks.
245+
246+
**Characteristics:**
247+
- Contains objects synced from component tracks' `members` tiers
248+
- Objects that were automatically resolved using the deduplication strategy
249+
- OR objects manually promoted from quarantine
250+
- These objects are included in published STIX bundles
251+
- No workflow states (no work-in-progress, awaiting-review, reviewed)
252+
253+
**Duplicate Rules:**
254+
- Cannot contain exact duplicates (same `object_ref` + `object_modified` pair)
255+
- **CANNOT** contain multiple versions of the same object
256+
- Deduplication strategy determines which version to keep when conflicts occur
257+
258+
##### 2. Quarantine
259+
260+
**Location:** `workspace.quarantine`
261+
262+
**Definition:** Conflicting objects that require manual resolution.
263+
264+
**Characteristics:**
265+
- Only populated when using `quarantine` deduplication strategy
266+
- Contains objects that couldn't be automatically resolved due to conflicts
267+
- NOT included in published STIX bundles
268+
- Requires manual intervention to promote one version to members
269+
270+
**Duplicate Rules:**
271+
- Cannot contain exact duplicates (same `object_ref` + `object_modified` pair)
272+
- **CAN** contain multiple versions of the same object (different versions from different component tracks)
273+
- Example: Can have `attack-pattern--T1234, modified: 2024-01-15` (from Track A) AND `attack-pattern--T1234, modified: 2024-02-20` (from Track B) simultaneously
274+
217275
---
218276

219277
### Virtual Release Track

0 commit comments

Comments
 (0)