bea1903ac9
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Co-authored-by: Cursor <cursoragent@cursor.com>
208 lines
4.6 KiB
Markdown
208 lines
4.6 KiB
Markdown
# Contributor Guidelines
|
||
|
||
**Last Updated:** 2025-01-20
|
||
**Document Version:** 1.0
|
||
**Status:** Active Documentation
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
This document provides guidelines for contributing to the documentation, including style standards, review process, and approval workflow.
|
||
|
||
---
|
||
|
||
## Style Guide Reference
|
||
|
||
**Primary Reference:**
|
||
- [DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md) ⭐⭐⭐
|
||
|
||
**Key Standards:**
|
||
- File naming: `UPPERCASE_WITH_UNDERSCORES.md`
|
||
- Headers: Include Last Updated, Document Version, Status
|
||
- Cross-references: Use Related Documentation sections
|
||
- Code blocks: Include language identifiers and expected output
|
||
|
||
---
|
||
|
||
## Contribution Process
|
||
|
||
### Step 1: Identify Need
|
||
|
||
**Ways to contribute:**
|
||
- Fix errors or outdated information
|
||
- Add missing documentation
|
||
- Improve existing documentation
|
||
- Add examples or use cases
|
||
- Create diagrams or visualizations
|
||
|
||
---
|
||
|
||
### Step 2: Follow Standards
|
||
|
||
**Before contributing:**
|
||
1. Read [DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)
|
||
2. Review similar documents for consistency
|
||
3. Use templates where available
|
||
4. Follow naming conventions
|
||
|
||
---
|
||
|
||
### Step 3: Create/Update Document
|
||
|
||
**Where to add docs (directory structure):**
|
||
- **01-getting-started/** – Prerequisites, quick start, first-time setup
|
||
- **02-architecture/** – Network, hardware, VMID, orchestration
|
||
- **03-deployment/** – Runbooks, deployment guides, status
|
||
- **04-configuration/** – MCP, router, Cloudflare, secrets, SSH, templates
|
||
- **05-network/** – NGINX, RPC, Cloudflare routing
|
||
- **06-besu/** – Besu allowlist, nodes, validator keys
|
||
- **07-ccip/** – CCIP deployment spec
|
||
- **08-monitoring/** – Monitoring, block production
|
||
- **09-troubleshooting/** – FAQ, QBFT, troubleshooting flows
|
||
- **10-best-practices/** – Recommendations, checklists
|
||
- **11-references/** – API, paths, token list, network master
|
||
- **12-quick-reference/** – Quick refs, cards, templates
|
||
- **00-meta/** – Style guide, reviews, task list, metrics
|
||
|
||
**Index:** Add new docs to [MASTER_INDEX.md](../MASTER_INDEX.md) in the appropriate section and update the directory tree if needed.
|
||
|
||
**For new documents:**
|
||
- Use appropriate directory structure (above)
|
||
- Follow style guide header format
|
||
- Include Related Documentation section
|
||
- Add to MASTER_INDEX.md
|
||
|
||
**For updates:**
|
||
- Update Last Updated date
|
||
- Increment Document Version if significant changes
|
||
- Update change log if document has one
|
||
- Verify all links still work
|
||
|
||
---
|
||
|
||
### Step 4: Review and Test
|
||
|
||
**Self-review checklist:**
|
||
- [ ] Follows style guide
|
||
- [ ] All links work
|
||
- [ ] Code examples tested (if applicable)
|
||
- [ ] No placeholder content
|
||
- [ ] Proper cross-references
|
||
- [ ] Added to index files
|
||
|
||
---
|
||
|
||
### Step 5: Submit for Review
|
||
|
||
**Review process:**
|
||
1. Create pull request or notify team
|
||
2. Include description of changes
|
||
3. Reference related issues/tasks
|
||
4. Wait for review approval
|
||
|
||
---
|
||
|
||
## Approval Workflow
|
||
|
||
### Review Levels
|
||
|
||
**Level 1: Self-Review**
|
||
- Minor corrections
|
||
- Formatting fixes
|
||
- Link updates
|
||
|
||
**Level 2: Peer Review**
|
||
- New documents
|
||
- Significant updates
|
||
- Configuration changes
|
||
|
||
**Level 3: Team Review**
|
||
- Architecture changes
|
||
- Major procedure changes
|
||
- Policy updates
|
||
|
||
---
|
||
|
||
## Examples and Templates
|
||
|
||
### New Document Template
|
||
|
||
```markdown
|
||
# Document Title
|
||
|
||
**Navigation:** [Home](../01-getting-started/README.md) > [Category](../01-getting-started/README.md) > Document Title
|
||
|
||
**Last Updated:** YYYY-MM-DD
|
||
**Document Version:** 1.0
|
||
**Status:** 🟢 Active Documentation
|
||
|
||
---
|
||
|
||
## Overview
|
||
|
||
[Document purpose and scope]
|
||
|
||
---
|
||
|
||
[Content sections]
|
||
|
||
---
|
||
|
||
## Related Documentation
|
||
|
||
- **[MASTER_INDEX](../MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index (in docs/)
|
||
- **[DOCUMENTATION_STYLE_GUIDE](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐ - Style standards
|
||
|
||
---
|
||
|
||
**Last Updated:** YYYY-MM-DD
|
||
**Review Cycle:** [Monthly/Quarterly/As Needed]
|
||
```
|
||
|
||
---
|
||
|
||
## Common Contribution Types
|
||
|
||
### Adding Examples
|
||
|
||
**Guidelines:**
|
||
- Use real-world scenarios
|
||
- Include expected outputs
|
||
- Test examples before documenting
|
||
- Update if procedures change
|
||
|
||
---
|
||
|
||
### Fixing Errors
|
||
|
||
**Process:**
|
||
1. Identify error
|
||
2. Verify correct information
|
||
3. Update document
|
||
4. Update related documents if needed
|
||
5. Test fix
|
||
|
||
---
|
||
|
||
### Adding Diagrams
|
||
|
||
**Guidelines:**
|
||
- Use Mermaid for new diagrams
|
||
- Follow diagram standards
|
||
- Reference in text
|
||
- Update visual index
|
||
|
||
---
|
||
|
||
## Related Documentation
|
||
|
||
- **[DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐⭐ - Style guide
|
||
- **[MASTER_INDEX.md](../MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index
|
||
- **[DOCUMENTATION_METRICS.md](../archive/00-meta-pruned/DOCUMENTATION_METRICS.md)** ⭐ - Documentation health and review
|
||
|
||
---
|
||
|
||
**Last Updated:** 2025-01-20
|
||
**Review Cycle:** Quarterly
|