Skip to content

development-workflow.md

Latest commit

 

History

History
430 lines (318 loc) · 16.1 KB

development-workflow.md

File metadata and controls

430 lines (318 loc) · 16.1 KB
Raw

Development Workflow Guide

This document describes the standard development workflow for AIXCL. All contributors, including agents, must follow this workflow.

Overview

We follow an Issue-First Development workflow:

  1. Create an issue describing the problem or feature
  2. Create a branch to address the issue
  3. Make changes and commit
  4. Push changes and create a Pull Request that references the issue
  5. Review and merge

Step-by-Step Workflow

1. Create an Issue First

Always create an issue before starting work. This ensures:

  • Problems are documented and tracked
  • PRs can reference the issue they're solving
  • Discussion happens before implementation
  • Work is traceable and organized

Using GitHub CLI:

# Note: GitHub CLI doesn't support setting issue type directly
# Set the type in GitHub UI, then add labels:
gh issue create --title "Brief description" --body "Detailed description of the problem or feature" --label "component:cli" --assignee <your-github-username>

Best Practices:

  • Use clear, descriptive titles
  • Provide context and background
  • Include steps to reproduce (for bugs)
  • Use plain text formatting (avoid special Unicode characters)
  • Always add appropriate labels (see Label Guidelines below)
  • Always assign the issue to the person working on it using --assignee

2. Create a Branch

Create a branch from dev with a descriptive name:

git checkout dev
git pull origin dev
git checkout -b issue-<number>/<short-description>

Branch naming convention:

  • issue-<number>/<short-description> (e.g., issue-217/fix-encoding-problem)
  • feature/<name> for new features
  • fix/<name> for bug fixes
  • refactor/<name> for refactoring

3. Make Changes and Commit

Make your changes, then commit with clear messages:

git add <files>
git commit -m "type: Brief description

- Detailed point 1
- Detailed point 2

Fixes #<issue-number>"

Commit message format:

  • Use conventional commit types: fix:, feat:, refactor:, docs:, test:, etc.
  • Reference the issue number in the commit message
  • Keep the first line under 72 characters
  • Use bullet points for multiple changes

GPG-Signed Commits (Required for main/dev):

All commits to main and dev branches must be GPG-signed. Setup is automated:

# One-time setup
./scripts/utils/setup-gpg.sh

# Commits are automatically signed after setup
git commit -m "feat: add new feature"

# Verify signature
git log --show-signature

See GPG-Signed Commits Guide for complete documentation.

4. Push and Create Pull Request

Push your branch and create a PR:

git push -u origin <branch-name>
gh pr create --title "Title referencing issue" --body "Description linking to issue #<number>"

# Always assign yourself and add matching labels to the PR
gh pr edit <number> --add-assignee <your-github-username> --add-label "component:cli"

PR Best Practices:

  • Title should reference the issue without colon: "Fix Issue title (#<number>)"
  • Note: Both issue titles and PR titles should NOT use colons (e.g., "Fix CLI error handling" not "Fix: CLI error handling")
  • Always assign the PR to the author
  • Always add labels to the PR matching the labels on the linked issue
  • Description should:
    • Link to the issue: "Fixes #<number>" or "Addresses #<number>"
    • Describe what changed
    • Use plain text formatting (markdown checkboxes - [x] instead of Unicode)
    • Include testing notes if applicable
  • Verify CI Status: Monitor the status checks in the GitHub PR interface. The task is not complete until all checks (Bash-CI, CodeQL, etc.) are green.

Example PR body:

Fixes #217

## Changes
- [x] Fixed encoding issue in issue/PR descriptions
- [x] Updated workflow documentation
- [x] Added plain text formatting guidelines

## Testing
- Verified issue creation works correctly
- Confirmed PR formatting displays properly

5. Review and Merge

  • Verify CI Status: Ensure all automated checks (Linting, Security, Environment) have passed. The change is not complete until CI is green.
  • Wait for code review
  • Address feedback
  • Once approved and status checks are passing, merge via GitHub UI or CLI

Promotion Workflow (Dev to Main)

When releasing changes from dev to main:

  1. Ensure all CI checks pass on dev:

    git checkout dev
git pull origin dev

  2. Create a release issue (optional but recommended):

    cat > /tmp/release-issue.md << 'EOF'
## Release X.Y.Z

## Deliverables
- [ ] Changelog updated
- [ ] All tests passing on dev
- [ ] Documentation updated
EOF
gh issue create --title "Release X.Y.Z" --body-file /tmp/release-issue.md --label "component:infrastructure,Maintenance" --assignee <your-github-username>

  3. Create promotion PR:

    gh pr create --title "Release X.Y.Z (#<release-issue>)" --body "Fixes #<release-issue>" --base main --head dev --assignee <your-github-username> --label "component:infrastructure"

  4. Merge after final review and status checks

Changelog Policy

CHANGELOG updates happen at release time, not at merge time.

This project uses the [Unreleased] section in CHANGELOG.md strictly as a placeholder. Individual feature or fix PRs must not edit CHANGELOG.md. This avoids:

  • Merge conflicts on the [Unreleased] section from parallel PRs
  • Wasted administrative commits and CI cycles for every merged change
  • Documenting changes that may later be reverted or superseded

How it works:

  1. Changes merge to dev with no CHANGELOG edit
  2. Issues and PRs serve as the canonical pre-release history
  3. When cutting a release, the release author compiles all merged PRs since the last version
  4. The CHANGELOG is updated in the promotion PR (dev -> main) that creates the release
  5. The [Unreleased] section is replaced with the new version header and date

Rationale: Issues and PRs already provide full traceability. The CHANGELOG is a release artifact for end-users, not a running development log.

Human in the Loop Checklist Policy

The agent MUST distinguish between agent-completed items and human-verification items.

Party Fills [x] Example
Agent Items the agent performed "Issue referenced", "Branch named correctly"
Human Items requiring manual verification "Behavior works as expected", "No regressions observed"

The human sees [ ] on verification items and ticks them during code review. The checklist serves as a gate, not passive decoration.

Label Guidelines

GitHub Issue Types and Labels are required for all issues. GitHub has native issue types that are separate from labels. Both help organize issues, track work, and make it easier to find related issues.

GitHub Issue Types (Required - Select One)

GitHub provides native issue types that must be set for each issue. These are separate from labels:

  • Bug - An unexpected problem or behavior
  • Feature - A request, idea, or new functionality
  • Task - A specific piece of work

Note: You cannot create custom issue types in GitHub. Use labels for additional categorization (see below).

Label Categories

Labels are organized into categories using prefixes:

Component Labels (Select All That Apply)

  • component:runtime-core - Runtime core services (Ollama)
  • component:ollama - Ollama LLM inference engine
  • component:persistence - Database and persistence services
  • component:observability - Monitoring and observability (Prometheus, Grafana, Loki)
  • component:ui - User interface components (Open WebUI)
  • component:cli - Command-line interface and tooling
  • component:infrastructure - Infrastructure and deployment (Docker, profiles, configuration)
  • component:testing - Tests and test infrastructure

Priority Labels (Optional - Select One)

  • P1 - High priority issue requiring immediate attention
  • P2 - Medium priority issue
  • P3 - Low priority issue

Profile Labels (Select All That Apply)

  • profile:bld - Affects bld profile (observability-focused)
  • profile:sys - Affects sys profile (full deployment)

Category Labels (Select All That Apply)

  • Fix - A fix for a bug or issue (use with Bug issue type)
  • Enhancement - Improvement to existing functionality (use with Feature issue type)
  • Refactor - Code refactoring without changing functionality (use with Task issue type)
  • Maintenance - Maintenance tasks and housekeeping (use with Task issue type)
  • documentation - Improvements or additions to documentation (GitHub default)

Note: "Task" is an issue type, not a label. Use the Task issue type for tasks, refactoring, and maintenance work. Do not create a "Task" label as it's redundant with the issue type.

Other Labels

  • dependencies - Dependency updates and management
  • good first issue - Good for newcomers
  • help wanted - Extra attention is needed
  • question - Further information is requested

How to Add Labels

When creating an issue:

# Add labels during creation (set issue type in GitHub UI)
gh issue create --title "Title" --body "Description" --label "component:cli,P1"

# Or add labels after creation
gh issue edit <number> --add-label "component:cli"

Note: GitHub CLI doesn't support setting the issue type (Bug/Feature/Task) directly. Set the type in the GitHub web interface, then use CLI for labels.

Issue Type and Label Selection Guidelines:

  1. Always select one GitHub issue type - Bug, Feature, or Task (set via GitHub's Type field)
    • Note: "Task" is an issue type only, not a label. Do not create or use a "Task" label.
  2. Select relevant component labels - Helps identify which part of the system is affected
  3. Select category labels if applicable - Fix, Enhancement, Refactor, Maintenance for additional context
  4. Select priority if applicable - Helps prioritize work
  5. Select profile labels if issue is profile-specific - Helps identify deployment impact
  6. Use other labels as appropriate - good first issue, help wanted, etc.

Examples:

  • Bug in CLI: Type: Bug, Labels: component:cli
  • New feature for observability: Type: Feature, Labels: component:observability
  • Fix for database issue: Type: Bug, Labels: Fix,component:persistence
  • Task for infrastructure: Type: Task, Labels: component:infrastructure
  • Enhancement affecting all profiles: Type: Feature, Labels: Enhancement,profile:bld,profile:sys
  • High priority bug: Type: Bug, Labels: component:runtime-core,P1
  • Dependency update: Type: Task, Labels: dependencies,Maintenance

Checking Available Labels

# List all labels
gh label list

# List labels for a specific issue
gh issue view <number> --json labels

Formatting Guidelines

IMPORTANT: Use plain text formatting to avoid encoding issues.

DO:

  • Use markdown checkboxes: - [x] for completed items
  • Use standard markdown: **bold**, *italic*, `code`
  • Use plain ASCII characters
  • Use numbered lists: 1., 2., 3.

DON'T:

  • Use Unicode checkmarks (for example, \\u2713, \\u2714, or checkmark emoji) as they can appear garbled
  • Use emoji in technical documentation
  • Use special Unicode characters that may not render consistently

Line Endings

All text files in this repository must use Unix-style line endings (LF), not Windows-style (CRLF).

Why This Matters

  • Cross-platform compatibility
  • Consistent diffs and reviews
  • Git best practices

Automatic Handling

The repository includes a .gitattributes file that automatically converts line endings for most contributors.

Manual Conversion (if needed)

If you accidentally commit files with CRLF line endings, convert them before submitting a PR:

# Convert a single file
sed -i 's/\r$//' <filename>

# Convert all files in a directory
find . -type f -name "*.md" -exec sed -i 's/\r$//' {} \;

CI Check

The CI workflow automatically checks for CRLF line endings and will fail the build if any are found.

GitHub Code Quality Agent findings and automated fixes:

  • Automated PRs from GitHub Code Quality (Copilot Autofix) may bypass the Issue-First workflow
  • These PRs should still be reviewed carefully before merging
  • After merging automated PRs, create a documentation issue to track the work completed
  • This ensures traceability even when automation creates PRs directly

Example: If automated PRs #351-355 are merged, create issue #356 documenting them.

Running the workflow with OpenCode CLI

A single agent runs this workflow end-to-end (issue, branch, commit, PR, assign and label). Use it from the repo root with OpenCode CLI and approve gh/git tool calls when prompted:

opencode

See opencode-setup.md for installation and configuration instructions.

Agent Instructions

Follow the development workflow documented in this document:
1. Always create an issue first using 'gh issue create' with appropriate labels and assignee
2. Read the template file first before composing any issue or PR body
3. Use /tmp for all generated body files and drafts (never commit generated artifacts)
4. Create a branch with format 'issue-<number>/<description>' from dev
5. Make changes and commit with conventional commit format
6. Push branch and create PR that references the issue
7. Assign the PR and add matching labels to it
8. Use plain text formatting (markdown checkboxes - [x], not Unicode)
9. Reference the issue number in commits and PRs
10. Add labels to issues (type, component, priority, profile as applicable)
11. Verify CI status: Monitor GitHub Actions and ensure all checks are green before finalizing the task
12. For automated PRs, document them retroactively with an issue
13. Follow Human in the Loop policy: Agent fills [x] for agent-completed items, Human fills [x] for verification items

Quick Reference Commands

# Create issue with labels and assignee (set issue type in GitHub UI)
# Note: Both issue and PR titles should NOT include colon (e.g., "Fix CLI error handling" not "Fix: CLI error handling")
gh issue create --title "Fix CLI error handling" --body "Description" --label "component:cli,P1" --assignee <your-github-username>

# Or add labels/assignee after creation
gh issue edit <number> --add-label "component:cli" --add-assignee <your-github-username>

# Create branch
git checkout -b issue-<number>/<description>

# Commit
git add .
git commit -m "type: Description

Fixes #<number>"

# Push and create PR
git push -u origin issue-<number>/<description>
gh pr create --title "Fix Title (#<number>)" --body "Fixes #<number>

## Changes
- [x] Change 1
- [x] Change 2"

# Assign and label the PR (matching the issue labels)
gh pr edit <number> --add-assignee <your-github-username> --add-label "component:cli,P1"

Why This Workflow?

  • Traceability: Every PR links to an issue explaining why it exists
  • Documentation: Issues serve as documentation of problems and solutions
  • Organization: Easier to track what's being worked on
  • Discussion: Issues allow discussion before implementation
  • Consistency: Standardized process works across all contributors

Checking Agent and Skill Files

When creating or modifying Agent files (.opencode/agents/agent-*.md), or Agent reports (docs/reference/ai-report-*.md), run the lint check script before committing:

./scripts/checks/check-agents.sh

This script validates:

  • Naming conventions (agent-*.md, ai-report-*.md)
  • Skill files (skill-*.md) if .opencode/skills/ directory exists
  • Required YAML frontmatter fields (name, description, role: system)
  • Required sections (Purpose, Canonical references, Global rules, Tool usage, Workflow steps, Safety/governance)
  • References to core documentation (development-workflow.md, 01_ai_guidance.md)

The same checks run automatically in CI on pull requests that touch agent, skill, or report files.

Note: Custom skills in .opencode/skills/ are optional. The directory only exists if skills are actually defined.

Questions?

If you're unsure about the workflow, check:

  • This document (development-workflow.md)
  • CONTRIBUTING.md for general contribution guidelines
  • Existing issues and PRs for examples