Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
278 lines (195 loc) · 7.91 KB

CONTRIBUTING.md

File metadata and controls

278 lines (195 loc) · 7.91 KB

Contributing to AD-SDLC

Thank you for your interest in contributing to AD-SDLC! This document provides guidelines and instructions for contributing.

Code of Conduct

Please read and follow our Code of Conduct to maintain a welcoming environment for all contributors.

Getting Started

Prerequisites

  • Node.js 18+
  • Git 2.30+
  • GitHub CLI (gh) 2.0+
  • Claude Code CLI

Development Setup

  1. Fork the repository
  2. Clone your fork: 
    git clone https://github.com/YOUR_USERNAME/claude_code_agent.git
cd claude_code_agent
  3. Install dependencies: 
    npm install
  4. Create a feature branch: 
    git checkout -b feature/your-feature-name

Development Workflow

Branch Naming

Use descriptive branch names following this pattern:

  • feature/description - New features
  • fix/description - Bug fixes
  • docs/description - Documentation updates
  • refactor/description - Code refactoring
  • test/description - Test additions or updates

Commit Messages

We use Conventional Commits. Each commit message should follow this format:

type(scope): description

[optional body]

[optional footer(s)]

Types

  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that don't affect the meaning of the code
  • refactor: Code change that neither fixes a bug nor adds a feature
  • perf: Performance improvement
  • test: Adding or updating tests
  • chore: Changes to build process or auxiliary tools
  • ci: Changes to CI configuration

Examples

feat(agent): add token usage tracking to collector

fix(workflow): resolve race condition in parallel worker execution

docs(readme): add CI/CD section with workflow descriptions

Language Policy

All commit messages must be written in English.

Attribution Policy

When using AI assistants (like Claude) for code generation:

  • Do NOT include AI-generated signatures in commits
  • Do NOT add "Generated by Claude" or similar attribution
  • Do NOT include "Co-Authored-By: Claude" or AI-related co-author tags
  • Code ownership and responsibility belong to the human committer

This ensures clean git history and proper accountability for all contributions.

Code Style

  • Run linter before committing: npm run lint
  • Run formatter: npm run format
  • Ensure all tests pass: npm test

Technical Debt Comments

We use standardized comment markers to track technical debt in the codebase. These markers help identify areas that need improvement and ensure debt is visible and actionable.

Comment Types

Marker Purpose When to Use
// TODO: Future improvements Features to add, optimizations to make
// FIXME: Known bugs or issues Code that works but has problems
// HACK: Temporary workarounds Quick fixes that need proper solutions
// NOTE: Important context Non-obvious behavior explanations

Format

// TODO: Add caching to reduce API calls
// Description of what needs to be done and why.
// Optional: link to related issue #123

// FIXME: Race condition when multiple workers access same file
// Current workaround is retry logic, but proper locking is needed.

// HACK: Using setTimeout to wait for external service
// Should implement proper event-driven approach.

Guidelines

  1. Explain why - Not just what, but why it's needed
  2. Link issues when applicable - Use #issue-number for tracking
  3. Keep comments updated - Remove when fixed, update if scope changes
  4. Be specific - Vague comments like "TODO: fix this" are not helpful

Viewing Technical Debt

# List all TODOs
npm run todo

# List all TODOs, FIXMEs, and HACKs
npm run todo:all

# VS Code users: Install "Todo Tree" extension for sidebar view

Testing

  • Write tests for new features
  • Update tests when modifying existing functionality
  • Aim for 80%+ code coverage
# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific test file
npm test -- path/to/test.spec.ts

# Run E2E tests only
npm run test:e2e

# Run unit tests only
npm test -- tests/controller

Test Categories

Category Location Description
Unit Tests tests/{module}/ Individual component testing
E2E Tests tests/e2e/ Full pipeline and integration testing
Orchestration Tests tests/e2e/orchestration.e2e.test.ts Multi-agent coordination and parallel worker execution

Orchestration Tests

The orchestration tests (tests/e2e/orchestration.e2e.test.ts) validate:

  • Controller → Worker distribution: Work order assignment and tracking
  • State persistence: Controller state save/restore between runs
  • Parallel execution: 3-5 concurrent workers without conflicts
  • Resource contention: Priority queue and concurrent access handling
  • Deadlock prevention: Interleaved operations without blocking
  • Failure recovery: Worker failure handling and task reassignment

Pull Request Process

Before Submitting

  1. Ensure your code follows the style guidelines
  2. Update documentation if needed
  3. Add or update tests as appropriate
  4. Run the full test suite locally
  5. Rebase on the latest main branch

Submitting a PR

  1. Push your changes to your fork
  2. Create a Pull Request using the PR template
  3. Fill out all sections of the template
  4. Link related issues using Closes #issue-number
  5. Request review from maintainers

Review Process

  1. Automated checks must pass (lint, test, build)
  2. At least one maintainer approval required
  3. Address review feedback promptly
  4. Squash commits if requested

Issue Guidelines

Reporting Bugs

Use the Bug Report template and include:

  • Clear description of the bug
  • Steps to reproduce
  • Expected vs actual behavior
  • Environment details
  • Relevant logs or screenshots

Requesting Features

Use the Feature Request template and include:

  • Problem statement
  • Proposed solution
  • Alternatives considered
  • Priority assessment

Project Structure

claude_code_agent/
├── .github/                 # GitHub configuration
│   ├── workflows/           # CI/CD workflows
│   ├── ISSUE_TEMPLATE/      # Issue templates
│   ├── CODEOWNERS           # Code ownership
│   └── pull_request_template.md
├── .claude/                 # Claude agent definitions
│   └── agents/
├── .ad-sdlc/                # AD-SDLC configuration
├── docs/                    # Documentation
├── src/                     # Source code
└── tests/                   # Test files

Release Process

Releases are automated via GitHub Actions:

  1. Maintainer creates a version tag: git tag v1.2.3
  2. Push the tag: git push origin v1.2.3
  3. Release workflow builds, tests, and publishes
  4. GitHub Release is created with auto-generated notes

Version Numbering

We follow Semantic Versioning:

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes (backward compatible)

Questions?

If you have questions, feel free to:

Thank you for contributing!