diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..07f9a64 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,148 @@ +# Contributing to Stacks Documentation + +Thank you for your interest in contributing to the Stacks documentation! This repository contains comprehensive documentation about the Stacks blockchain ecosystem, including technical specifications, guides, and educational content. + +## Ways to Contribute + +### 📝 Improve Documentation + +- **Fix typos and grammar**: Help maintain high-quality, professional documentation +- **Clarify explanations**: Make complex concepts easier to understand +- **Add examples**: Include practical examples and use cases +- **Update outdated information**: Keep documentation current with latest developments + +### 📋 Add New Content + +- **Write guides and tutorials**: Create step-by-step guides for developers +- **Document new features**: Explain new Stacks ecosystem features and capabilities +- **Create educational content**: Help newcomers understand Stacks concepts +- **Translate documentation**: Make Stacks accessible to global audiences + +### 🔧 Technical Improvements + +- **Fix broken links**: Ensure all references and links work correctly +- **Improve formatting**: Enhance readability with better markdown formatting +- **Add diagrams and visuals**: Include helpful diagrams and illustrations +- **Optimize structure**: Improve organization and navigation + +## Getting Started + +### 1. Choose an Issue + +- Check our [open issues](../../issues) for tasks that need attention +- Look for issues labeled `documentation`, `good first issue`, or `help wanted` +- Comment on an issue to indicate you're working on it + +### 2. Fork and Clone + +```bash +# Fork this repository on GitHub +# Then clone your fork +git clone https://github.com/YOUR_USERNAME/stacks.git +cd stacks + +# Set up the upstream remote +git remote add upstream https://github.com/stacks-network/stacks.git +``` + +### 3. Create a Feature Branch + +```bash +# Create and switch to a new branch +git checkout -b improve-sbtc-documentation + +# Or for bug fixes +git checkout -b fix-broken-link +``` + +### 4. Make Your Changes + +- Follow the existing documentation style and structure +- Use clear, concise language appropriate for technical and non-technical audiences +- Include proper formatting with headers, lists, and code blocks +- Test links and ensure they work correctly + +### 5. Commit Your Changes + +```bash +# Stage your changes +git add . + +# Commit with a descriptive message +git commit -m "docs: clarify sBTC peg-in process with step-by-step guide + +- Add detailed explanation of Bitcoin deposit process +- Include visual diagram of the peg-in flow +- Add troubleshooting section for common issues" +``` + +We follow [Conventional Commits](https://www.conventionalcommits.org/) format: +- `docs:` for documentation changes +- `feat:` for new content/features +- `fix:` for corrections and fixes +- `style:` for formatting improvements + +### 6. Submit a Pull Request + +```bash +# Push your branch +git push origin improve-sbtc-documentation +``` + +Then create a Pull Request: + +1. Go to your fork on GitHub +2. Click "Compare & pull request" +3. Fill in the PR details: + - **Title**: Clear, descriptive title following conventional commit format + - **Description**: Explain what you changed and why + - **Link issues**: Reference any related issues + +## Documentation Standards + +### Writing Style + +- **Audience-aware**: Write for both technical and non-technical readers +- **Clear and concise**: Avoid jargon or explain it when necessary +- **Active voice**: Use active voice for clarity +- **Consistent terminology**: Use Stacks-specific terms consistently + +### Structure + +- **Logical flow**: Organize content in a logical sequence +- **Clear headings**: Use descriptive headings and subheadings +- **Table of contents**: Include TOC for longer documents +- **Cross-references**: Link related documents and sections + +### Technical Content + +- **Code examples**: Include working code examples where helpful +- **API references**: Keep API documentation up to date +- **Version information**: Note version-specific features or changes +- **Prerequisites**: List requirements before tutorials + +## Review Process + +1. **Automated checks**: Ensure your PR passes any automated checks +2. **Peer review**: A maintainer will review your contribution +3. **Feedback**: Address any requested changes +4. **Approval**: Once approved, your PR will be merged + +## Recognition + +Contributors are recognized for their valuable work in: +- Release notes and changelogs +- Contributor acknowledgments +- Community shoutouts + +## Code of Conduct + +Please adhere to our [Code of Conduct](https://github.com/stacks-network/stacks/blob/master/.github/CODE_OF_CONDUCT.md) in all interactions. + +## Need Help? + +- **Questions**: Ask in our [Discord community](https://stacks.chat/) +- **Issues**: Report bugs or request features via [GitHub Issues](../../issues) +- **Discussions**: Join technical discussions on [GitHub Discussions](../../discussions) + +Thank you for helping improve the Stacks documentation and making blockchain education more accessible! 🚀