213 lines
4.8 KiB
Markdown
213 lines
4.8 KiB
Markdown
# TRACES Quick Reference Guide
|
|
|
|
## What are TRACES?
|
|
|
|
TRACES are requirement identifiers embedded in code comments to track which requirements are implemented where.
|
|
|
|
Format: `// TRACES: UR-001, UR-002 | DR-003`
|
|
|
|
## Quick Examples
|
|
|
|
### TypeScript
|
|
```typescript
|
|
// TRACES: UR-005, UR-026 | DR-029
|
|
export function handlePlayback() { }
|
|
|
|
/**
|
|
* Resume playback from saved position
|
|
* TRACES: UR-019 | DR-022
|
|
*/
|
|
export async function resumePlayback(itemId: string) { }
|
|
```
|
|
|
|
### Svelte
|
|
```svelte
|
|
<!-- TRACES: UR-007, UR-008 | DR-007 -->
|
|
<script>
|
|
export let items = [];
|
|
</script>
|
|
```
|
|
|
|
### Rust
|
|
```rust
|
|
/// TRACES: UR-005 | DR-001
|
|
pub enum PlayerState { ... }
|
|
|
|
#[test]
|
|
fn test_queue_next() {
|
|
// TRACES: UR-005 | DR-005 | UT-003
|
|
}
|
|
```
|
|
|
|
## Requirement Types
|
|
|
|
| Type | Meaning | Example |
|
|
|------|---------|---------|
|
|
| **UR** | User Requirement | UR-005: Control media playback |
|
|
| **IR** | Integration Requirement | IR-003: LibMPV integration |
|
|
| **DR** | Development Requirement | DR-001: Player state machine |
|
|
| **JA** | Jellyfin API Requirement | JA-007: Get playback info |
|
|
| **UT** | Unit Test | UT-001: Player state transitions |
|
|
| **IT** | Integration Test | IT-003: Audio playback via libmpv |
|
|
|
|
## Where to Find Requirements
|
|
|
|
1. **User Requirements (UR):** [README.md](README.md#1-user-requirements)
|
|
2. **Integration Requirements (IR):** [README.md](README.md#21-integration-requirements)
|
|
3. **Development Requirements (DR):** [README.md](README.md#23-development-requirements)
|
|
4. **Jellyfin API (JA):** [README.md](README.md#22-jellyfin-api-requirements)
|
|
|
|
## How to Add TRACES
|
|
|
|
### Step 1: Find the Requirement
|
|
Look up the requirement in README.md or the traceability matrix.
|
|
|
|
Example: `UR-005: Control media playback (pause, play, skip, scrub)`
|
|
|
|
### Step 2: Add Comment
|
|
Add TRACES comment at the top of the function/type/module:
|
|
|
|
```typescript
|
|
// TRACES: UR-005
|
|
export async function playMedia(itemId: string) {
|
|
// Implementation
|
|
}
|
|
```
|
|
|
|
### Step 3: Run Extraction
|
|
Verify the trace is captured:
|
|
|
|
```bash
|
|
bun run traces:json | jq '.requirements | keys | grep "UR-005"'
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Single Requirement
|
|
```typescript
|
|
// TRACES: UR-005
|
|
function handlePlay() { }
|
|
```
|
|
|
|
### Multiple Requirements, Same Type
|
|
```typescript
|
|
// TRACES: UR-005, UR-026, UR-019
|
|
function handlePlaybackState() { }
|
|
```
|
|
|
|
### Multiple Types
|
|
```typescript
|
|
// TRACES: UR-005, UR-026 | DR-029
|
|
function autoplayNextEpisode() { }
|
|
```
|
|
|
|
### Test Coverage
|
|
```typescript
|
|
// TRACES: UR-005 | UT-001
|
|
#[test]
|
|
fn test_player_state_transition() { }
|
|
```
|
|
|
|
### Modules/Files
|
|
```typescript
|
|
/**
|
|
* Player event handling
|
|
* TRACES: UR-005, UR-019, UR-023 | DR-001, DR-028
|
|
*/
|
|
```
|
|
|
|
## Validation
|
|
|
|
### Check Your Changes
|
|
```bash
|
|
# View current coverage
|
|
bun run traces:json | jq '.byType'
|
|
|
|
# Generate full report
|
|
bun run traces:markdown
|
|
|
|
# Check specific requirement
|
|
bun run traces:json | jq '.requirements."UR-005"'
|
|
```
|
|
|
|
### Before Committing
|
|
1. Ensure all new code has TRACES
|
|
2. Format is correct: `// TRACES: ...`
|
|
3. Requirements exist in README.md
|
|
4. No typos in requirement IDs
|
|
|
|
## CI/CD Validation
|
|
|
|
The workflow automatically checks:
|
|
- ✅ Coverage stays >= 50%
|
|
- ✅ New files have TRACES
|
|
- ✅ JSON format is valid
|
|
- ✅ Reports are generated
|
|
|
|
See [TRACEABILITY_CI.md](docs/TRACEABILITY_CI.md) for details.
|
|
|
|
## Tips & Tricks
|
|
|
|
### Find Related Code
|
|
```bash
|
|
# Find all code tracing to UR-005
|
|
bun run traces:json | jq '.requirements."UR-005"'
|
|
|
|
# List all tests
|
|
bun run traces:json | jq '.requirements | keys | map(select(startswith("UT")))'
|
|
```
|
|
|
|
### Update Your Editor
|
|
|
|
**VS Code:**
|
|
```json
|
|
{
|
|
"editor.wordBasedSuggestions": false,
|
|
"editor.suggest.custom": [
|
|
{
|
|
"name": "TRACES Format",
|
|
"insertText": "// TRACES: $1",
|
|
"insertTextRules": "InsertAsSnippet"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### Find Untraced Code
|
|
```bash
|
|
# Files modified without TRACES
|
|
git diff --name-only | xargs grep -L "TRACES:" | head -10
|
|
```
|
|
|
|
## FAQ
|
|
|
|
**Q: Do I need TRACES on every function?**
|
|
A: Only for code that implements requirements. Internal helpers don't need TRACES.
|
|
|
|
**Q: Can I use TRACES on multiple related functions?**
|
|
A: Yes! Add at the file/module level or on individual functions.
|
|
|
|
**Q: What if code doesn't relate to any requirement?**
|
|
A: Leave it untraced. TRACES are for requirement-driven development.
|
|
|
|
**Q: How often should I regenerate reports?**
|
|
A: Automatically on push (CI/CD). Manually after changes: `bun run traces:markdown`
|
|
|
|
**Q: Can I trace to requirements that aren't implemented yet?**
|
|
A: Yes! TRACES show your implementation plan.
|
|
|
|
## See Also
|
|
|
|
- [Full Traceability Matrix](docs/TRACEABILITY.md)
|
|
- [CI/CD Pipeline Guide](docs/TRACEABILITY_CI.md)
|
|
- [Requirements Specification](README.md)
|
|
- [Extraction Script](scripts/README.md#extract-tracests)
|
|
|
|
---
|
|
|
|
**Quick Start:**
|
|
1. Add `// TRACES: UR-XXX` to new code
|
|
2. Run `bun run traces:markdown`
|
|
3. Check `docs/TRACEABILITY.md`
|
|
4. Submit PR - workflow validates automatically!
|