8.0 KiB

Raw Blame History

Contributing to BMad

Thank you for considering contributing! We believe in Human Amplification, Not Replacement — bringing out the best thinking in both humans and AI through guided collaboration.

💬 Discord: Join our community for real-time discussions, questions, and collaboration.

Our Philosophy

BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: "Does this make humans and AI better together?"

✅ What we welcome:

Enhanced collaboration patterns and workflows
Improved agent personas and prompts
Domain-specific modules leveraging BMad Core
Better planning and context continuity

❌ What doesn't fit:

Purely automated solutions that sideline humans
Complexity that creates barriers to adoption
Features that fragment BMad Core's foundation

Reporting Issues

ALL bug reports and feature requests MUST go through GitHub Issues.

Before Creating an Issue

Search existing issues — Use the GitHub issue search to check if your bug or feature has already been reported
Search closed issues — Your issue may have been fixed or addressed previously
Check discussions — Some conversations happen in GitHub Discussions

Bug Reports

After searching, if the bug is unreported, use the bug report template and include:

Clear description of the problem
Steps to reproduce
Expected vs actual behavior
Your environment (model, IDE, BMad version)
Screenshots or error messages if applicable

Feature Requests

After searching, use the feature request template and explain:

What the feature is
Why it would benefit the BMad community
How it strengthens human-AI collaboration

For community modules, review TRADEMARK.md for proper naming conventions (e.g., "My Module (BMad Community Module)").

Before Starting Work

⚠️ Required before submitting PRs:

Work Type	Requirement
Bug fix	An open issue (create one if it doesn't exist)
Feature	An open feature request issue
Large changes	Discussion via issue first

Why? This prevents wasted effort on work that may not align with project direction.

Pull Request Guidelines

Target Branch

Submit PRs to the main branch.

PR Size

Ideal: 200-400 lines of code changes
Maximum: 800 lines (excluding generated files)
One feature/fix per PR

If your change exceeds 800 lines, break it into smaller PRs that can be reviewed independently.

New to Pull Requests?

Fork the repository
Clone your fork: git clone https://github.com/YOUR-USERNAME/bmad-method.git
Create a branch: git checkout -b fix/description or git checkout -b feature/description
Make changes — keep them focused
Commit: git commit -m "fix: correct typo in README"
Push: git push origin fix/description
Open PR from your fork on GitHub

PR Description Template

## What
[1-2 sentences describing WHAT changed]

## Why
[1-2 sentences explaining WHY this change is needed]
Fixes #[issue number]

## How
- [2-3 bullets listing HOW you implemented it]
-

## Testing
[1-2 sentences on how you tested this]

Keep it under 200 words.

Commit Messages

Use conventional commits:

feat: New feature
fix: Bug fix
docs: Documentation only
refactor: Code change (no bug/feature)
test: Adding tests
chore: Build/tools changes

Keep messages under 72 characters. Each commit = one logical change.

Git Workflow for Contributors

One-Time Setup

After forking and cloning the repository, set up your development environment:

# 1. Add the upstream remote (main repository)
git remote add upstream git@github.com:bmad-code-org/BMAD-METHOD.git

# 2. Enable git hooks (enforces workflow automatically)
git config core.hooksPath .githooks

Single-Commit Workflow

This repository uses a single-commit-per-branch workflow to keep PR history clean.

Initial Development

# Create feature branch
git checkout -b feat/your-feature

# Make your changes
# ... edit files ...

# Commit once
git commit -m "feat: add your feature description"

# Push to your fork
git push -u origin feat/your-feature

Making Additional Changes

Use amend instead of creating new commits:

# Make more changes
# ... edit files ...

# Stage changes
git add .

# Amend the existing commit
git commit --amend --no-edit

# Force push (safely)
git push --force-with-lease

Addressing PR Feedback

# Make requested changes
# ... edit files ...

# Amend (don't create new commits)
git commit --amend --no-edit

# Force push
git push --force-with-lease

Keeping Your Branch Updated

# Sync your local main with upstream
git checkout main
git pull upstream main

# Rebase your feature branch
git checkout feat/your-feature
git rebase main

# Force push (safely)
git push --force-with-lease

What the Git Hooks Do

The hooks in .githooks/ automate workflow enforcement:

Hook	Purpose
`pre-push`	Ensures upstream sync, blocks direct push to main, enforces single-commit
`pre-commit`	Blocks commits to main, reminds about amend workflow
`post-checkout`	Provides sync reminders when switching branches

The hooks will automatically:

Block commits directly to main branch
Prevent pushing more than 1 commit per branch
Warn if your local main is behind upstream
Remind you to rebase before pushing

Troubleshooting

"Too many commits" error

If you have multiple commits, squash them:

# Reset to main (keeps your changes)
git reset --soft main

# Create single commit
git commit -m "feat: your feature description"

# Force push
git push --force-with-lease

Local main diverged from upstream

# Reset your main to match upstream
git checkout main
git reset --hard upstream/main
git push --force-with-lease origin main

Branch not rebased on main

# Update main first
git checkout main
git pull upstream main

# Rebase your branch
git checkout feat/your-feature
git rebase main

# Force push
git push --force-with-lease

What Makes a Good PR?

✅ Do	❌ Don't
Change one thing per PR	Mix unrelated changes
Clear title and description	Vague or missing explanation
Reference related issues	Reformat entire files
Small, focused commits	Copy your whole project
Work on a branch	Work directly on `main`

Prompt & Agent Guidelines

Keep dev agents lean — focus on coding context, not documentation
Web/planning agents can be larger with complex tasks
Everything is natural language (markdown) — no code in core framework
Use BMad modules for domain-specific features
Validate YAML schemas: npm run validate:schemas

Need Help?

💬 Discord: Join the community
🐛 Bugs: Use the bug report template
💡 Features: Use the feature request template

Code of Conduct

By participating, you agree to abide by our Code of Conduct.

License

By contributing, your contributions are licensed under the same MIT License. See CONTRIBUTORS.md for contributor attribution.

8.0 KiB Raw Blame History