diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8a55820..3016359a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,8 @@ Thank you for considering contributing to this project! This document outlines the process for contributing and some guidelines to follow. +🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first! + Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements. ## Code of Conduct diff --git a/README.md b/README.md index 4f70ae59..b7ae3a19 100644 --- a/README.md +++ b/README.md @@ -241,7 +241,10 @@ Ask the agent you are using for help with /help (in the web) or \*help in the id ## Contributing -We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. +We welcome contributions! + +- 🆕 **New to GitHub?** Start with our [Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) +- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines ### Development Setup diff --git a/docs/how-to-contribute-with-pull-requests.md b/docs/how-to-contribute-with-pull-requests.md new file mode 100644 index 00000000..44886ad8 --- /dev/null +++ b/docs/how-to-contribute-with-pull-requests.md @@ -0,0 +1,141 @@ +# How to Contribute with Pull Requests + +**New to GitHub and pull requests?** This guide will walk you through the basics step by step. + +## What is a Pull Request? + +A pull request (PR) is how you propose changes to a project on GitHub. Think of it as saying "Here are some changes I'd like to make - please review and consider adding them to the main project." + +## Before You Start + +⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first. + +## Step-by-Step Guide + +### 1. Fork the Repository + +1. Go to the [BMAD-METHOD repository](https://github.com/bmadcode/bmad-method) +2. Click the "Fork" button in the top-right corner +3. This creates your own copy of the project + +### 2. Clone Your Fork + +```bash +# Replace YOUR-USERNAME with your actual GitHub username +git clone https://github.com/YOUR-USERNAME/bmad-method.git +cd bmad-method +```text + +### 3. Create a New Branch + +**Never work directly on the `main` branch!** Always create a new branch for your changes: + +```bash +# Create and switch to a new branch +git checkout -b fix/typo-in-readme +# or +git checkout -b feature/add-new-agent +``` + +**Branch naming tips:** + +- `fix/description` - for bug fixes +- `feature/description` - for new features +- `docs/description` - for documentation changes + +### 4. Make Your Changes + +- Edit the files you want to change +- Keep changes small and focused on one thing +- Test your changes if possible + +### 5. Commit Your Changes + +```bash +# Add your changes +git add . + +# Commit with a clear message +git commit -m "Fix typo in README.md" +```text + +**Good commit messages:** + +- "Fix typo in installation instructions" +- "Add example for new agent usage" +- "Update broken link in docs" + +**Bad commit messages:** + +- "stuff" +- "changes" +- "update" + +### 6. Push to Your Fork + +```bash +# Push your branch to your fork +git push origin fix/typo-in-readme +``` + +### 7. Create the Pull Request + +1. Go to your fork on GitHub +2. You'll see a green "Compare & pull request" button - click it +3. Fill out the PR template: + - **Title**: Clear, descriptive title + - **Description**: Explain what you changed and why + +### 8. Wait for Review + +- A maintainer will review your PR +- They might ask for changes +- Be patient and responsive to feedback + +## What Makes a Good Pull Request? + +✅ **Good PRs:** + +- Change one thing at a time +- Have clear, descriptive titles +- Explain what and why in the description +- Include only the files that need to change + +❌ **Avoid:** + +- Changing formatting of entire files +- Multiple unrelated changes in one PR +- Copying your entire project/repo into the PR +- Changes without explanation + +## Common Mistakes to Avoid + +1. **Don't reformat entire files** - only change what's necessary +2. **Don't include unrelated changes** - stick to one fix/feature per PR +3. **Don't paste code in issues** - create a proper PR instead +4. **Don't submit your whole project** - contribute specific improvements + +## Need Help? + +- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help +- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions) +- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues) +- 📖 Read the full [Contributing Guidelines](../CONTRIBUTING.md) + +## Example: Good vs Bad PRs + +### 😀 Good PR Example + +**Title**: "Fix broken link to installation guide" +**Changes**: One file, one line changed +**Description**: "The link in README.md was pointing to the wrong file. Updated to point to correct installation guide." + +### 😞 Bad PR Example + +**Title**: "Updates" +**Changes**: 50 files, entire codebase reformatted +**Description**: "Made some improvements" + +--- + +**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner.