Skip to content

Latest commit

 

History

History
361 lines (253 loc) · 8.47 KB

CONTRIBUTING.md

File metadata and controls

361 lines (253 loc) · 8.47 KB

Contributing to DevTrail

Thank you for your interest in contributing to DevTrail! This document provides guidelines and information for contributors.

Languages: English | Español

Table of Contents

Code of Conduct

This project is governed by our Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code.

In short: be respectful, inclusive, and constructive in all interactions. Harassment, discrimination, and trolling are not tolerated. Please read the full Code of Conduct before contributing.

Contributor License Agreement (CLA)

This project requires all contributors to sign a Contributor License Agreement (CLA) before their pull requests can be merged. We use CLA Assistant to manage this process.

How it works

  1. When you open your first pull request, CLA Assistant will automatically post a comment asking you to sign the CLA.
  2. Click the link in the comment to review and sign the agreement.
  3. The CLA only needs to be signed once — it covers all future contributions to this project.
  4. Once signed, CLA Assistant will update the PR check status and your contribution can proceed to review.

If you have questions about the CLA, please open a Discussion.

How Can I Contribute?

Reporting Bugs

Before creating a bug report, please check existing issues to avoid duplicates.

When reporting a bug, include:

  • A clear, descriptive title
  • Steps to reproduce the behavior
  • Expected behavior
  • Actual behavior
  • Screenshots (if applicable)
  • Environment details (OS, AI platform, etc.)

Suggesting Features

Feature suggestions are welcome! Please include:

  • A clear description of the feature
  • The problem it solves
  • Potential implementation approaches
  • Any alternatives you've considered

Improving Documentation

Documentation improvements are highly valued:

  • Fix typos or unclear wording
  • Add examples
  • Improve explanations
  • Translate to other languages

Submitting Code

Code contributions should:

  • Fix a bug or implement a feature
  • Include appropriate tests (if applicable)
  • Follow the project's style guidelines
  • Update documentation as needed

Development Setup

Prerequisites

  • Git
  • A text editor (VS Code recommended)
  • Bash (for Linux/Mac validation scripts)
  • PowerShell (for Windows validation scripts)
  • Rust toolchain (for CLI development — install via rustup.rs)
  • Node.js 20+ (optional, for markdownlint)

Setup Steps

  1. Fork the repository

    Click "Fork" on the GitHub repository page.

  2. Clone your fork

    git clone https://github.com/your-username/devtrail.git
cd devtrail

  3. Install the pre-commit hook

    cp dist/scripts/pre-commit-docs.sh .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

  4. Install development tools (optional)

    # Markdown linting
npm install -g markdownlint-cli

  5. Create a branch

    git checkout -b feature/your-feature-name
# or
git checkout -b fix/your-bug-fix

  6. Make your changes and validate

    # Linux/Mac
bash dist/scripts/pre-commit-docs.sh

# Windows
.\dist\scripts\validate-docs.ps1

Pull Request Process

Before Submitting

  • Run validation scripts successfully
  • Update documentation if needed
  • Add yourself to CONTRIBUTORS.md (if applicable)
  • Write a clear PR description

PR Title Format

Use conventional commit format:

type(scope): description

Examples:
feat(templates): add template for security reviews
fix(validation): correct regex for file naming
docs(readme): clarify installation steps
chore(ci): update GitHub Actions workflow

Types:

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation changes
  • chore - Maintenance tasks
  • refactor - Code refactoring
  • test - Test additions or fixes

PR Description Template

## Summary
Brief description of changes

## Motivation
Why is this change needed?

## Changes
- Change 1
- Change 2

## Testing
How were these changes tested?

## Checklist
- [ ] Validation scripts pass
- [ ] Documentation updated
- [ ] No sensitive information included

Review Process

  1. A maintainer will review your PR
  2. Address any requested changes
  3. Once approved, a maintainer will merge

Style Guidelines

Markdown

  • Use ATX-style headers (#, ##, etc.)
  • Use fenced code blocks with language identifiers
  • Use tables for structured data
  • Keep lines under 120 characters when practical
  • Use blank lines to separate sections

YAML Front-matter

---
id: TYPE-YYYY-MM-DD-NNN
title: Clear, descriptive title
status: draft | accepted | deprecated
created: YYYY-MM-DD
# Additional fields as needed
---

File Naming

DevTrail documents:

[TYPE]-[YYYY-MM-DD]-[NNN]-[description].md
  • Use lowercase for description
  • Use hyphens to separate words
  • Keep descriptions concise but clear

Code in Scripts

  • Use clear variable names
  • Add comments for complex logic
  • Follow shell/PowerShell best practices

Documentation Standards

Adding a New Document Type

If you're proposing a new document type:

  1. Create the template

    • Add TEMPLATE-NEWTYPE.md to dist/.devtrail/templates/
    • Follow existing template patterns

  2. Update governance docs

    • dist/.devtrail/00-governance/DOCUMENTATION-POLICY.md
    • dist/.devtrail/00-governance/AGENT-RULES.md
    • dist/.devtrail/QUICK-REFERENCE.md

  3. Update agent configs

    • dist/dist-templates/directives/ (distribution templates)

  4. Update validation

    • dist/scripts/pre-commit-docs.sh
    • dist/scripts/validate-docs.ps1
    • dist/.github/workflows/docs-validation.yml

  5. Document the change

    • Create an ADR explaining the new type
    • Update the README if needed

Writing Templates

Templates should include:

  • Complete YAML front-matter with all fields
  • Clear section headers
  • Placeholder text explaining what goes in each section
  • Examples where helpful

Writing Governance Documents

  • Be clear and unambiguous
  • Use tables for reference information
  • Include examples
  • Keep rules actionable

CLI Development

The DevTrail CLI is written in Rust and located in the cli/ directory.

Building

cd cli
cargo build

Running Tests

cd cli
cargo test

Release Build

cd cli
cargo build --release

The release binary is optimized with LTO and stripped for minimal size.

Architecture

cli/src/
├── main.rs          # Entry point + clap CLI definition
├── commands/
│   ├── mod.rs       # Subcommand routing
│   ├── init.rs      # devtrail init [path]
│   ├── update.rs    # devtrail update
│   ├── remove.rs    # devtrail remove [--full]
│   ├── update_cli.rs # devtrail update-cli
│   └── about.rs     # devtrail about
├── config.rs        # Config and checksums management
├── download.rs      # GitHub Releases download
├── inject.rs        # Directive file injection (markers)
├── manifest.rs      # dist-manifest.yml parsing
├── platform.rs      # OS/arch detection for binary downloads
├── self_update.rs   # CLI binary self-update logic
└── utils.rs         # Helpers (hashing, colors, paths)

Questions?

If you have questions about contributing:

  1. Check existing Issues
  2. Check Discussions
  3. Open a new Discussion for general questions
  4. Open an Issue for specific bugs or features

Recognition

Contributors are recognized in:

  • GitHub's contributor graph
  • Release notes for significant contributions
  • CONTRIBUTORS.md (for recurring contributors)

Thank you for helping make DevTrail better!

DevTrail — Because every change tells a story.

Strange Days Tech