176 lines
4.7 KiB
Markdown
176 lines
4.7 KiB
Markdown
# BMAD Documentation Contribution Guidelines
|
|
|
|
## Overview
|
|
|
|
This document outlines the process for contributing to the BMAD Method documentation. Following these guidelines ensures a smooth review process and maintains the high quality of our documentation.
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- GitHub account
|
|
- Basic knowledge of Markdown
|
|
- Familiarity with the BMAD Method
|
|
- Understanding of the documentation structure
|
|
|
|
### Setting Up Your Environment
|
|
|
|
1. Fork the [BMAD Documentation repository](https://github.com/bmad-method/documentation)
|
|
2. Clone your fork locally
|
|
3. Install dependencies:
|
|
```bash
|
|
npm install
|
|
```
|
|
4. Set up pre-commit hooks:
|
|
```bash
|
|
npm run prepare
|
|
```
|
|
|
|
## Contribution Process
|
|
|
|
### 1. Find or Create an Issue
|
|
|
|
- Check existing issues in the [issue tracker](https://github.com/bmad-method/documentation/issues)
|
|
- If your contribution doesn't match an existing issue, create a new one
|
|
- Wait for issue assignment or approval before starting work
|
|
|
|
### 2. Create a Branch
|
|
|
|
- Create a branch from `main` with a descriptive name:
|
|
```bash
|
|
git checkout -b doc/add-developer-guide
|
|
```
|
|
- Use prefixes to indicate the type of change:
|
|
- `doc/` for documentation additions
|
|
- `fix/` for documentation fixes
|
|
- `update/` for documentation updates
|
|
- `review/` for review changes
|
|
|
|
### 3. Make Your Changes
|
|
|
|
- Follow the [Style Guide](./style-guide.md)
|
|
- Run automated checks locally:
|
|
```bash
|
|
npm run lint:all
|
|
```
|
|
- Test your changes by building the documentation locally:
|
|
```bash
|
|
npm run docs:build
|
|
npm run docs:serve
|
|
```
|
|
|
|
### 4. Commit Your Changes
|
|
|
|
- Use conventional commit messages:
|
|
```
|
|
docs(persona): add developer integration guide
|
|
|
|
- Add detailed setup instructions
|
|
- Include code examples
|
|
- Add troubleshooting section
|
|
|
|
Closes #123
|
|
```
|
|
- Keep commits focused and atomic
|
|
- Reference issues in commit messages
|
|
|
|
### 5. Submit a Pull Request
|
|
|
|
- Push your branch to your fork
|
|
- Create a pull request against the `main` branch
|
|
- Fill out the pull request template completely
|
|
- Request review from appropriate team members
|
|
- Address review feedback promptly
|
|
|
|
### 6. Review Process
|
|
|
|
All contributions go through a review process:
|
|
|
|
1. **Automated Checks**: CI/CD pipeline runs linting, spelling, and link validation
|
|
2. **Peer Review**: At least one team member reviews the content
|
|
3. **Technical Review**: Subject matter experts verify technical accuracy
|
|
4. **Final Approval**: Documentation maintainer approves and merges
|
|
|
|
## Documentation Types
|
|
|
|
### New Documentation
|
|
|
|
When creating new documentation:
|
|
|
|
1. Use the appropriate template from the `templates/` directory
|
|
2. Follow the established directory structure
|
|
3. Include all required sections
|
|
4. Add entry to navigation if applicable
|
|
5. Create examples where appropriate
|
|
|
|
### Updates to Existing Documentation
|
|
|
|
When updating existing documentation:
|
|
|
|
1. Maintain the existing structure and style
|
|
2. Clearly mark deprecated content
|
|
3. Update related documentation as needed
|
|
4. Update the "Last Updated" date
|
|
5. Add changelog entry if significant
|
|
|
|
### Translations
|
|
|
|
When contributing translations:
|
|
|
|
1. Create files in the appropriate language directory
|
|
2. Maintain the same structure as the English version
|
|
3. Include language code in filename (e.g., `quickstart.fr.md`)
|
|
4. Update language selector in navigation
|
|
|
|
## Best Practices
|
|
|
|
### Content Guidelines
|
|
|
|
- Write for an international audience
|
|
- Use simple, clear language
|
|
- Provide context and examples
|
|
- Link to related documentation
|
|
- Include troubleshooting sections
|
|
- Consider the user's perspective and needs
|
|
|
|
### Technical Guidelines
|
|
|
|
- Test all code examples
|
|
- Verify command outputs
|
|
- Check compatibility across environments
|
|
- Include version information
|
|
- Provide alternative approaches where applicable
|
|
|
|
### Review Guidelines
|
|
|
|
- Be constructive and specific in feedback
|
|
- Suggest improvements rather than just pointing out issues
|
|
- Consider the author's intent
|
|
- Focus on content quality and accuracy
|
|
- Be timely in your reviews
|
|
|
|
## Recognition
|
|
|
|
Contributors are recognized in several ways:
|
|
|
|
- Listed in the [Contributors](../CONTRIBUTORS.md) file
|
|
- Mentioned in release notes
|
|
- Acknowledged in the documentation they contributed to
|
|
|
|
## Code of Conduct
|
|
|
|
All contributors must adhere to our [Code of Conduct](../CODE_OF_CONDUCT.md). We are committed to providing a welcoming and inclusive environment for all contributors.
|
|
|
|
## Questions and Support
|
|
|
|
If you have questions about contributing:
|
|
|
|
- Join our [Community Slack](https://bmad-method.slack.com)
|
|
- Email the documentation team at docs@bmad-method.org
|
|
- Ask in the #documentation channel on Slack
|
|
- Check the [FAQ](../FAQ.md) for common questions
|
|
|
|
---
|
|
|
|
*These contribution guidelines are maintained by the BMAD Documentation Team. Last updated: Current Date.*
|