From 7c9c0a67a7b301724d2e18a94f89ffcae85cb36c Mon Sep 17 00:00:00 2001 From: Martin Date: Fri, 21 Nov 2025 23:59:59 +0100 Subject: [PATCH] Add contribution guidelines and clean up internal files - Add CONTRIBUTING.md with detailed contribution guide - Add docs/contribute.md page in documentation site - Update README.md to emphasize community collaboration - Remove internal project files from repository (DEV.md, PROJECT_STATUS.md, etc.) - Update .gitignore to exclude internal working files --- .gitignore | 7 ++ CONTRIBUTING.md | 249 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 34 +++++-- docs/contribute.md | 195 +++++++++++++++++++++++++++++++++++ mkdocs.yml | 2 + 5 files changed, 478 insertions(+), 9 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 docs/contribute.md diff --git a/.gitignore b/.gitignore index 4862e38..0129edb 100644 --- a/.gitignore +++ b/.gitignore @@ -38,6 +38,13 @@ github-docs/ # Scripts - internal tooling only scripts/ +# Internal project files +CLAUDE.md +PROJECT_STATUS.md +COMPARISON.md +PAGES_TO_ADD.md +parsed-content/ + # Environment variables .env .env.local diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..28b9c28 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,249 @@ +# Contributing to BC250 Documentation + +**Help us improve the BC250 documentation!** Instead of posting solutions in Discord where they get lost, add them here so everyone can find them. + +## Why Contribute? + +- **Searchable:** Documentation is indexed by search engines +- **Organized:** Information is categorized and easy to find +- **Permanent:** Won't get lost in chat history +- **Collaborative:** Everyone benefits from improvements + +## Quick Start (No Git Knowledge Required) + +### Method 1: Edit Directly on GitHub (Easiest) + +1. **Browse to the page you want to edit** on GitHub: https://github.com/elektricM/amd-bc250-docs/tree/main/docs +2. **Click the pencil icon** (✏️) in the top right +3. **Make your changes** using the editor +4. **Scroll down** and click "Propose changes" +5. **Click "Create pull request"** + +Done! We'll review and merge your contribution. + +### Method 2: Report Issues + +Found incorrect information or missing content? + +1. Go to https://github.com/elektricM/amd-bc250-docs/issues +2. Click "New Issue" +3. Describe what's wrong or what's missing +4. Submit + +We'll fix it or add the missing information. + +## What to Contribute + +### High Priority + +- **Tested hardware configurations** (power supplies, cooling solutions, displays) +- **Game compatibility** (FPS, settings, issues, workarounds) +- **Troubleshooting solutions** (especially if you solved something not documented) +- **Distribution-specific setup steps** (if you got a distro working) +- **BIOS settings** that work well +- **Benchmark results** with your configuration + +### Also Welcome + +- **Fixing typos or unclear explanations** +- **Adding missing commands or steps** +- **Updating outdated information** +- **Adding screenshots or diagrams** +- **Improving organization** + +### Don't Contribute + +- ❌ Speculation or unverified claims +- ❌ Proprietary/copyrighted BIOS files +- ❌ Instructions for illegal activities +- ❌ Personal opinions without technical basis + +## Documentation Structure + +``` +docs/ +├── getting-started/ # First-time setup +├── hardware/ # Specs, power, cooling, displays +├── bios/ # BIOS flashing, VRAM, overclocking +├── linux/ # Distribution setup guides +├── drivers/ # RADV, environment variables +├── system/ # Governor, sensors, power management +├── gaming/ # Game compatibility +├── troubleshooting/ # Common problems and solutions +└── reference/ # Quick references +``` + +## For Advanced Contributors (Using Git) + +### Setup Local Environment + +```bash +# Clone the repository +git clone https://github.com/elektricM/amd-bc250-docs.git +cd amd-bc250-docs + +# Install dependencies +pip install mkdocs-material + +# Preview your changes locally +mkdocs serve +# Open http://127.0.0.1:8000/ in your browser +``` + +### Making Changes + +```bash +# Create a new branch +git checkout -b fix-something + +# Edit files in docs/ directory +# Preview changes with: mkdocs serve + +# Stage your changes +git add docs/ + +# Commit with clear message +git commit -m "Fix Fedora setup instructions for Mesa 25.1" + +# Push to your fork +git push origin fix-something + +# Create pull request on GitHub +``` + +### Writing Guidelines + +**Style:** +- Use clear, concise language +- Write for beginners but include advanced details +- Use code blocks for commands +- Add warnings for risky operations + +**Markdown Format:** +```markdown +# Page Title + +Brief introduction explaining what this page covers. + +## Section Heading + +Content here. + +### Subsection + +More specific content. + +!!!warning "Important Warning" + Use admonitions for critical information. + +!!!tip "Pro Tip" + Helpful hints for users. + +```bash +# Code blocks with syntax highlighting +sudo dnf install mesa-vulkan-drivers +``` + +**Links:** +```markdown +[Relative link to another page](../bios/flashing.md) +[External link](https://example.com/) +``` +``` + +**Testing:** +- Test all commands you document +- Verify links work +- Check formatting with `mkdocs serve` + +## Contribution Examples + +### Example 1: Adding Game Compatibility + +Edit `docs/gaming/compatibility.md`: + +```markdown +### Cyberpunk 2077 + +**Status:** ✅ Playable +**Performance:** 45-60 FPS @ 1080p Medium +**VRAM:** 512MB dynamic or 8GB/8GB split +**Settings:** +- RT: Off (too demanding) +- FSR: Quality mode +- RADV_DEBUG=nocompute %command% + +**Issues:** +- Occasional stuttering in crowded areas +- Fixed with kernel 6.13+ +``` + +### Example 2: Adding Troubleshooting Solution + +Edit `docs/troubleshooting/boot.md`: + +```markdown +### Black Screen After Kernel Update + +**Symptoms:** +- System boots but no display output +- Fans running normally + +**Solution:** +1. Boot into recovery kernel from GRUB +2. Downgrade to previous kernel version: + ```bash + sudo dnf downgrade kernel + ``` +3. Report kernel version that failed on GitHub Issues +``` + +### Example 3: Adding Distribution Guide + +Create new file `docs/linux/gentoo.md`: + +```markdown +# Gentoo Setup + +Step-by-step guide for setting up BC250 on Gentoo. + +## Prerequisites +- Gentoo installation media +- Basic Gentoo knowledge + +## Installation +[...] +``` + +Then add to `mkdocs.yml`: +```yaml +- Linux Setup: + - Gentoo Setup: linux/gentoo.md +``` + +## Review Process + +1. **Submit pull request** (PR) +2. **Automated checks** verify documentation builds +3. **Maintainers review** for accuracy and clarity +4. **Feedback/changes** may be requested +5. **Merged** once approved +6. **Published** automatically to https://elektricM.github.io/amd-bc250-docs/ + +## Questions? + +- **Documentation issues:** Open an issue on GitHub +- **General BC250 discussion:** Join Discord (but please document solutions here!) +- **Pull request help:** Ask in the PR comments + +## License + +By contributing, you agree your contributions will be licensed under: +- **Documentation:** CC BY-SA 4.0 +- **Code examples:** MIT + +--- + +**Thank you for helping make BC250 documentation better for everyone!** + +Instead of answering the same questions in Discord, let's build a knowledge base that helps everyone. diff --git a/README.md b/README.md index afc82ea..bf7feb3 100644 --- a/README.md +++ b/README.md @@ -1,17 +1,20 @@ # AMD BC250 Documentation -Community-driven documentation for the AMD BC250 board. +**Comprehensive, community-driven documentation for the AMD BC250 board.** -**Visit the documentation:** [https://elektricM.github.io/amd-bc250-docs/](https://elektricM.github.io/amd-bc250-docs/) +📖 **Read the docs:** [https://elektricM.github.io/amd-bc250-docs/](https://elektricM.github.io/amd-bc250-docs/) + +✏️ **Contribute:** Found a solution? Add it to the docs so everyone can find it! See [CONTRIBUTING.md](CONTRIBUTING.md) ## What's Included -- Linux setup guides for multiple distributions -- BIOS configuration and flashing procedures -- Hardware specifications and requirements -- Troubleshooting guides with verified solutions -- Gaming compatibility database -- Performance tuning and optimization +- **Linux setup guides** for 7+ distributions (Fedora, Bazzite, CachyOS, Arch, Debian, etc.) +- **BIOS flashing** and configuration (including GPU frequency patch) +- **Hardware specs** - power requirements, cooling, display compatibility +- **Troubleshooting** - boot issues, performance problems, stability fixes +- **Gaming compatibility** - tested games, settings, FPS data +- **Driver setup** - RADV configuration, environment variables +- **System configuration** - GPU governor, sensors, power management ## Building Locally @@ -37,7 +40,20 @@ Built from: ## Contributing -Join the [BC250 Discord](https://discord.com/invite/uDvkhNpxRQ) or submit pull requests to improve the documentation. +**Please contribute your knowledge!** Instead of posting solutions in Discord where they get lost, add them to the documentation: + +- **Easy way:** Click "Edit on GitHub" on any page and submit changes +- **Report issues:** Found wrong info? [Open an issue](https://github.com/elektricM/amd-bc250-docs/issues) +- **Full guide:** See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions + +**What we need:** +- ✅ Tested hardware configurations +- ✅ Game compatibility reports +- ✅ Troubleshooting solutions you've found +- ✅ Distribution-specific setup steps +- ✅ Fixes for outdated information + +**Join Discord:** [https://discord.com/invite/uDvkhNpxRQ](https://discord.com/invite/uDvkhNpxRQ) - but please document your solutions here! ## License diff --git a/docs/contribute.md b/docs/contribute.md new file mode 100644 index 0000000..37c6079 --- /dev/null +++ b/docs/contribute.md @@ -0,0 +1,195 @@ +# How to Contribute + +**Help us make BC250 documentation better!** Instead of posting solutions only in Discord, add them here where everyone can find them. + +## Why Contribute to the Docs? + +| Discord Posts | Documentation | +|--------------|---------------| +| Gets buried in chat history | Searchable forever | +| Hard to find later | Organized by topic | +| Same questions repeated | One permanent answer | +| Limited formatting | Code blocks, images, tables | +| No version control | Track changes, revert mistakes | + +## Easy Ways to Contribute + +### 1. Edit This Page (Easiest!) + +1. Click the **edit icon** (✏️) in the top right of any page +2. Make your changes in the GitHub editor +3. Click "Propose changes" → "Create pull request" +4. Done! We'll review and merge it + +**No Git knowledge required!** + +### 2. Report Issues + +Found incorrect or missing information? + +**[Open an issue →](https://github.com/elektricM/amd-bc250-docs/issues)** + +Tell us: +- What's wrong or missing +- What should be there instead +- Any relevant links or sources + +### 3. Share Your Configuration + +Got BC250 working well? Share your setup: + +**Hardware:** +- What PSU works for you? +- Which cooler keeps temps good? +- Display adapter compatibility? + +**Software:** +- Your distro setup steps +- Kernel version that works +- BIOS settings you use +- Games you've tested + +**Add it to the relevant page!** + +## What We Need Most + +### 🔥 High Priority + +- **Game compatibility reports** (FPS, settings, issues) +- **Troubleshooting solutions** you've discovered +- **Hardware testing** (PSUs, coolers, displays that work) +- **Distribution guides** for distros not yet documented +- **BIOS settings** that work well for different use cases + +### ✅ Also Welcome + +- Fixing typos and unclear explanations +- Adding missing commands or configuration steps +- Updating outdated information +- Screenshots or diagrams +- Benchmark results + +### ❌ Please Don't + +- Post speculation without testing +- Copy proprietary content +- Add unverified claims +- Include personal opinions without technical basis + +## Contribution Examples + +### Example: Add Game Compatibility + +Edit `docs/gaming/compatibility.md`: + +```markdown +### Elden Ring + +**Status:** ✅ Playable +**Performance:** 55-60 FPS @ 1080p High +**VRAM:** 512MB dynamic recommended +**Settings:** +- Graphics: High +- Anti-aliasing: Medium +- RADV_DEBUG=nocompute %command% + +**Notes:** +- Stuttering in some areas with 8GB/8GB split +- Smooth with 512MB dynamic VRAM +``` + +### Example: Add Troubleshooting Solution + +Edit `docs/troubleshooting/boot.md`: + +```markdown +### Black Screen After Mesa Update + +**Symptoms:** +- System boots but no display +- SSH still works + +**Solution:** +Downgrade Mesa to last working version: + +```bash +sudo dnf downgrade mesa-vulkan-drivers mesa-dri-drivers +``` + +Then report the issue to Mesa GitLab. +``` + +### Example: Add Hardware Compatibility + +Edit `docs/hardware/power.md`: + +```markdown +### Tested PSUs + +**Corsair SF450 (450W SFX)** +- ✅ Works perfectly +- Tested with RTX 3060 Ti (TDP mod) +- No stability issues +- Tested by: @username +``` + +## Advanced: Local Development + +Want to preview changes locally? + +```bash +# Clone repository +git clone https://github.com/elektricM/amd-bc250-docs.git +cd amd-bc250-docs + +# Install MkDocs +pip install mkdocs-material + +# Preview locally +mkdocs serve +# Open http://127.0.0.1:8000/ +``` + +**Full guide:** [CONTRIBUTING.md on GitHub](https://github.com/elektricM/amd-bc250-docs/blob/main/CONTRIBUTING.md) + +## Documentation Structure + +Know where to add your contribution: + +``` +docs/ +├── getting-started/ # First-time setup, prerequisites +├── hardware/ # Specs, power, cooling, displays +├── bios/ # BIOS flashing, VRAM, overclocking +├── linux/ # Distribution-specific guides +├── drivers/ # RADV driver, environment variables +├── system/ # GPU governor, sensors, power +├── gaming/ # Game compatibility, performance +├── troubleshooting/ # Common problems and solutions +└── reference/ # Quick references, cheatsheets +``` + +## Review Process + +1. **Submit** your contribution +2. **Automated checks** verify it builds correctly +3. **Review** by maintainers (usually within 48 hours) +4. **Feedback** if changes needed +5. **Merged** and automatically published +6. **Live** at https://elektricM.github.io/amd-bc250-docs/ + +## Questions? + +- **How do I...?** Read [CONTRIBUTING.md](https://github.com/elektricM/amd-bc250-docs/blob/main/CONTRIBUTING.md) +- **Found a bug?** [Open an issue](https://github.com/elektricM/amd-bc250-docs/issues) +- **Need help?** Ask in Discord, but add the answer here when solved! + +--- + +## Thank You! + +Every contribution helps someone avoid hours of troubleshooting. + +**Instead of answering the same questions in Discord, let's build a knowledge base that helps everyone.** + +[Start Contributing →](https://github.com/elektricM/amd-bc250-docs) diff --git a/mkdocs.yml b/mkdocs.yml index 279202f..ef3ab84 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -157,6 +157,8 @@ nav: - Reference: - Quick Reference: reference/quick-reference.md + - 📝 Contribute: contribute.md + # Extra extra: social: