Creating Roadmap Issues

This guide explains how to create and document issues from the project roadmap (docs/roadmap.md). It covers the complete workflow from selecting a roadmap task to creating GitHub issues with proper documentation.

📋 Overview

The roadmap implementation process involves:

Issue Documentation - Create detailed specification in docs/issues/
GitHub Issues - Create epic and/or task issues with proper hierarchy
Linking - Connect issues bidirectionally and update roadmap
File Management - Follow naming conventions
Quality Checks - Run linters before committing

🎯 Issue Hierarchy

Our roadmap uses a three-level hierarchy:

Roadmap (Issue #1)
└── Epic (e.g., Issue #2: "Scaffolding for main app")
    ├── Task (e.g., Issue #3: "Setup logging for production CLI")
    ├── Task (e.g., Issue #4: "Add configuration file support")
    └── Task (e.g., Issue #5: "Add help command")

When to Create Each Type

Epic Issue: For roadmap sections (e.g., "1. Add scaffolding for main app")
- Represents a major feature area or capability
- Contains multiple related tasks
- Links directly to roadmap issue (#1)
Task Issue: For individual roadmap items (e.g., "1.1 Setup logging")
- Represents a single, implementable unit of work
- Links to parent epic issue
- Has detailed specification document

📝 Complete Workflow

Step 1: Create Issue Specification Document

Create a detailed specification in docs/issues/ with temporary name:

# Copy the template to create your specification document
cp docs/issues/SPECIFICATION-TEMPLATE.md docs/issues/setup-logging-for-production-cli.md

# Edit the document to fill in all sections
vim docs/issues/setup-logging-for-production-cli.md

Document Structure

Use the template at docs/issues/SPECIFICATION-TEMPLATE.md as your starting point. The template includes:

Header: Issue number, parent epic, and related links
Overview: Clear description of what the task accomplishes
Goals: High-level objectives with checkboxes
Specifications: Detailed technical specifications with code examples
Implementation Plan: Phased breakdown with specific, actionable subtasks
Acceptance Criteria: Clear definition of what "done" means
Related Documentation: Links to relevant docs, ADRs, and examples
Notes: Additional context or considerations

Key Principles

Be Specific: Include code examples, command-line arguments, file structures
Be Actionable: Break work into small, trackable tasks with checkboxes
Provide Context: Link to related documentation, ADRs, and examples
Estimate Time: Help others understand scope
Define Success: Clear acceptance criteria (see Common Acceptance Criteria below)
Specify Architecture: Include DDD layer, module path, and architectural constraints (see template guidance below)

Architectural Requirements

When creating issues that involve code changes, always specify:

DDD Layer: Which layer the change belongs to (Presentation, Application, Domain, Infrastructure)
Module Path: Exact location in the codebase (src/{layer}/{module}/)
Architectural Constraints: Dependencies, patterns, and anti-patterns to follow
Related Documentation: Link to docs/codebase-architecture.md and other relevant architectural guidance

This ensures AI assistants and contributors understand not just what to implement, but where and how to implement it within the project's architectural patterns.

Common Acceptance Criteria

Every issue should include these standard acceptance criteria in addition to task-specific criteria:

Quality Checks (applies to every commit and PR):

- [ ] Pre-commit checks pass: `./scripts/pre-commit.sh`

This verification ensures:

✅ No unused dependencies (cargo machete)
✅ All linters pass (markdown, yaml, toml, clippy, rustfmt, shellcheck)
✅ All unit tests pass (cargo test)
✅ Documentation builds successfully (cargo doc)
✅ All E2E tests pass (config, provision, full suite)

Why Include This?

Reminder: Makes quality requirements explicit and visible
AI Assistants: Ensures automated tools run all checks before submitting work
Consistency: Every contributor knows the baseline quality standards
Early Detection: Catches issues before PR review

The pre-commit script is the single source of truth for all quality checks. By including it in acceptance criteria, we make it clear that passing these checks is required, not optional.

Acceptance Criteria as PR Review Checklist

Acceptance criteria serve a dual purpose in our workflow:

For Issue Authors: They define what "done" means for the task
For Contributors: They provide a pre-review checklist before submitting PRs

Both issue templates (SPECIFICATION-TEMPLATE.md and GITHUB-ISSUE-TEMPLATE.md) include a note that reminds contributors:

Note for Contributors: These criteria define what the PR reviewer will check. Use this as your pre-review checklist before submitting the PR to minimize back-and-forth iterations.

Benefits of this approach:

Clear expectations: Contributors know exactly what reviewers will check
Self-review: Encourages contributors to verify their work before submission
Faster merges: Reduces back-and-forth in PR reviews by catching issues early
Quality consistency: Ensures all PRs meet the same standards
Learning opportunity: New contributors learn project standards through acceptance criteria

When creating issues, think about what you would check when reviewing the PR. Make acceptance criteria specific, measurable, and aligned with the project's quality standards as documented in the PR Review Guide.

Step 2: Create GitHub Epic Issue (if needed)

If this is the first task in a roadmap section, create an epic issue first:

Go to GitHub Issues: https://github.com/torrust/torrust-tracker-deployer/issues
Click "New Issue"
Fill in Epic Details: Use the template at docs/issues/EPIC-TEMPLATE.md and fill in:
- Title with the roadmap section name
- Overview describing the epic's purpose
- Roadmap reference with quote from the roadmap
- Initial task list (will be updated as tasks are created)
- Parent link to roadmap issue (#1)
Add Labels: epic, roadmap
Set Parent: In the right sidebar, under "Development", link to parent issue (#1)
Create Issue - Note the issue number (e.g., #2)

Step 3: Create GitHub Task Issue

Go to GitHub Issues: https://github.com/torrust/torrust-tracker-deployer/issues
Click "New Issue"
Fill in Task Details: Use the template at docs/issues/GITHUB-ISSUE-TEMPLATE.md and fill in:
- Title with the task name from roadmap
- Overview with brief description
- Specification link (will be updated after file rename)
- Implementation plan with phased tasks
- Acceptance criteria
- Related links to parent epic and specification document
Add Labels: task, roadmap, relevant technical labels (rust, cli, etc.)
Set Parent: Link to parent epic issue
Create Issue - Note the issue number (e.g., #3)

Step 4: Update Issue Specification Document

Update the specification document with the issue number:

# [Task Title]

**Issue**: #3
**Parent Epic**: #2 - [Epic Name]
**Related**: [Links to related issues]

[Rest of document...]

Step 5: Rename File with Issue Number

Follow the naming convention based on issue type:

For Task Issues: {issue-number}-{description}.md

# Example: Task Issue #3
mv docs/issues/setup-logging-for-production-cli.md \
   docs/issues/3-setup-logging-for-production-cli.md

For Epic Issues: {issue-number}-epic-{description}.md

# Example: Epic Issue #2
mv docs/issues/scaffolding-for-main-app-epic.md \
   docs/issues/2-epic-scaffolding-for-main-app.md

Naming Rules:

Start with issue number
Use epic- prefix after the number for epic issues
Use lowercase
Separate words with hyphens
Keep descriptive but concise
Match branch naming convention

Manual Test Documentation (Optional):

If your issue requires extensive manual E2E testing, you can document test results in:

docs/issues/manual-tests/{issue-number}-{description}.md

Example:

docs/issues/manual-tests/248-network-segmentation-test-results.md

This extra documentation:

Provides detailed test results for complex implementations
Can include test commands, expected outputs, screenshots, and verification steps
Should be linked from the main issue specification file
Will be deleted when the issue is cleaned up (see Cleanup Process)

Step 6: Update GitHub Task Issue

Update the task issue with the correct file link:

## Specification

See detailed specification: [docs/issues/3-setup-logging-for-production-cli.md](../docs/issues/3-setup-logging-for-production-cli.md)

Step 7: Update GitHub Epic Issue

Update the epic issue task list with the new task:

## Tasks

- [ ] #3 - Setup logging for production CLI
- [ ] #X - [Next task name]
- [ ] #X - [Another task name]

Step 8: Update Roadmap

Update docs/roadmap.md to link the epic and task issues:

## 1. Add scaffolding for main app (Epic: [#2](https://github.com/torrust/torrust-tracker-deployer/issues/2))

- 1.1 Setup logging (Task: [#3](https://github.com/torrust/torrust-tracker-deployer/issues/3))
- 1.2 Add configuration file support
- 1.3 Add help command

Step 9: Pre-Commit Verification

Follow the commit process and run the pre-commit verification script:

./scripts/pre-commit.sh

All checks must pass before proceeding.

Step 10: Commit Changes

Follow the conventional commit format:

# Stage files
git add docs/roadmap.md docs/issues/

# Commit (note: we're on main, not on issue branch yet)
git commit -m "docs: add issue specification for roadmap task X.Y

- Create epic issue #X for roadmap section X
- Create task issue #Y for task X.Y
- Add detailed specification document
- Update roadmap with issue links"

# Push to remote
git push

🔍 Complete Example

Here's a complete example following the workflow:

Scenario

Implementing roadmap task 1.1 Setup logging

Execution

# 1. Create initial specification document from template
cp docs/issues/SPECIFICATION-TEMPLATE.md docs/issues/setup-logging-for-production-cli.md
vim docs/issues/setup-logging-for-production-cli.md
# ... fill in all sections: overview, goals, specs, implementation plan ...

# 2. Create GitHub Epic Issue #2: "Scaffolding for main app"
# - Browser: Create issue, link to #1, add labels
# - Note issue number: #2

# 3. Create GitHub Task Issue #3: "Setup logging for production CLI"
# - Browser: Create issue, link to #2, add labels
# - Note issue number: #3

# 4. Update specification with issue numbers
vim docs/issues/setup-logging-for-production-cli.md
# Add: **Issue**: #3
# Add: **Parent Epic**: #2

# 5. Rename file with issue number
mv docs/issues/setup-logging-for-production-cli.md \
   docs/issues/3-setup-logging-for-production-cli.md

# 6. Update GitHub Task Issue #3
# - Browser: Update specification link to correct filename

# 7. Update GitHub Epic Issue #2
# - Browser: Add task to task list: "- [ ] #3 - Setup logging..."

# 8. Update roadmap
vim docs/roadmap.md
# Update section 1.1 with issue link

# 9. Run pre-commit checks (see docs/contributing/commit-process.md)
./scripts/pre-commit.sh

# 10. Commit and push
git add docs/roadmap.md docs/issues/
git commit -m "docs: add issue specification for roadmap task 1.1

- Create epic issue #2 for roadmap section 1
- Create task issue #3 for task 1.1
- Add detailed specification document
- Update roadmap with issue links"
git push

📋 Pre-Commit Checklist

Before committing, verify:

🚨 Common Mistakes to Avoid

❌ Don't Create Implementation Branch Before Specification is Committed

# Wrong: Creating branch before specification is committed to main
git checkout -b 3-setup-logging-for-production-cli
# Problem: Specification should be on main first

✅ Correct: Commit specification to main first

Exception: If you plan to use GitHub Copilot agents, create and push the branch after committing the specification but before assigning Copilot to the issue

❌ Don't Forget to Rename File

# Wrong: File still has temporary name
docs/issues/setup-logging-for-production-cli.md
# Problem: Should have issue number prefix

# Wrong: Epic file missing "epic-" prefix
docs/issues/2-scaffolding-for-main-app.md
# Problem: Epic files need "epic-" prefix after number

✅ Correct:

Task issues: docs/issues/3-setup-logging-for-production-cli.md
Epic issues: docs/issues/2-epic-scaffolding-for-main-app.md

❌ Don't Skip Bidirectional Linking

# Wrong: Only roadmap links to issue
# Missing: Issue linking back to roadmap
# Missing: Epic listing the task

✅ Correct: All issues linked in both directions

❌ Don't Commit Without Linting

# Wrong: git add && git commit without running checks
# Problem: May have markdown, yaml, or other linting issues

✅ Correct: Always run ./scripts/pre-commit.sh first

🔗 Related Documentation

Branching Conventions - Branch naming for implementation
Commit Process - Conventional commit format
Project Roadmap - The roadmap being implemented
Development Principles - Quality standards

📞 Questions?

If you have questions about:

Issue structure: Review existing issues in docs/issues/
GitHub linking: Check how #2 and #3 are connected
Commit format: See commit-process.md
Linting: See linting.md

🚀 Next Steps

After completing this process, you have two options for implementation:

Option 1: Manual Implementation (Default)

Create Implementation Branch: git checkout -b {issue-number}-{description}
Start Implementation: Follow the plan in the specification document
Track Progress: Check off tasks in the GitHub issue as you complete them
Create PR: When complete, create pull request for review

Option 2: Using GitHub Copilot Agent (Optional)

If you want to use GitHub Copilot to assist with implementation:

Create Implementation Branch First:
```
git checkout -b {issue-number}-{description}
git push -u origin {issue-number}-{description}
```
Important: The branch must exist on GitHub before assigning Copilot to the issue.
Assign Copilot to the Issue:
- Go to the GitHub issue page
- Use the GitHub Copilot interface to assign the agent
- Copilot will use the existing branch to create a PR with proposed changes
Review Copilot's Work:
- Review the generated PR carefully
- Test the changes locally
- Request modifications if needed
- Approve and merge when satisfied
Track Progress: Check off completed tasks in the GitHub issue

Note: GitHub Copilot agents work best with well-defined specifications, which is why we create detailed issue documents first.

🧹 Cleaning Up Closed Issues

Over time, as issues are completed and closed on GitHub, the docs/issues/ folder can accumulate documentation for closed issues. Periodically clean up these files to keep the repository focused on active work.

When to Clean Up

After completing a major milestone or epic
During regular maintenance cycles
When preparing releases
Whenever the docs/issues/ folder feels cluttered

Cleanup Process

List Current Issue Files:
```
ls docs/issues/
```
Issue files follow the format: {issue-number}-{description}.md

Check Issue Status on GitHub:

Use the GitHub CLI to check the status of each issue:

# Check individual issue
gh issue view 21 --json state --jq .state

# Check multiple issues at once
for issue in 21 22 23 24; do
  state=$(gh issue view $issue --json state --jq .state 2>/dev/null || echo "NOT_FOUND")
  echo "$issue:$state"
done

Issue states:

OPEN - Issue is still active (keep the file)
CLOSED - Issue has been completed (remove the file)
NOT_FOUND - Issue doesn't exist (remove the file)

Check for Manual Test Documentation:

Some issues may have additional manual testing documentation in docs/issues/manual-tests/:

# Check if manual test documentation exists for closed issues
ls docs/issues/manual-tests/

# Manual test files follow format: {issue-number}-{description}.md
# Example: 248-network-segmentation-test-results.md

Remove Closed Issue Files and Manual Tests:

# Remove specific closed issue specification files
cd docs/issues/
rm -f 21-fix-e2e-infrastructure-preservation.md \
      22-rename-app-commands-to-command-handlers.md \
      23-add-clap-subcommand-configuration.md \
      24-add-user-documentation.md

# Remove associated manual test documentation (if exists)
cd manual-tests/
rm -f 21-*.md 22-*.md 23-*.md 24-*.md

# Or remove specific files if you know the names
rm -f 248-network-segmentation-test-results.md

Verify Remaining Files:
```
ls docs/issues/
ls docs/issues/manual-tests/
```
Only open issues, their associated manual tests, and template files should remain.

Commit the Changes:

# Stage the deletions (both issue specs and manual tests)
git add docs/issues/

# Commit with descriptive message
git commit -m "chore: remove closed issue documentation files

Removed X closed issue documentation files from docs/issues/:
- #21: fix-e2e-infrastructure-preservation
- #22: rename-app-commands-to-command-handlers
- #23: add-clap-subcommand-configuration
- #24: add-user-documentation

Also removed associated manual test documentation from docs/issues/manual-tests/.

All these issues have been closed on GitHub and no longer need
local documentation files.

Remaining open issues: #16, #17, #18, #19, #34"

# Push to remote
git push

Important Notes

Keep Template Files: Never delete EPIC-TEMPLATE.md, GITHUB-ISSUE-TEMPLATE.md, or SPECIFICATION-TEMPLATE.md
Manual Test Documentation: Check docs/issues/manual-tests/ for issue-specific test results (format: {issue-number}-*.md) and remove them along with the issue specification
Verify Before Deleting: Always double-check issue status before removing files
Document Removals: Use descriptive commit messages listing which issues were removed
Team Communication: Consider notifying the team before large cleanup operations
Git History: Closed issue documentation remains available in git history if needed for future reference

By following this workflow, you ensure that roadmap tasks are properly documented, tracked, and implemented with high quality and consistency.

FilesExpand file tree

roadmap-issues.md

Latest commit

History