proxmox/docs/00-meta/CONTRIBUTOR_GUIDELINES.md

# Contributor Guidelines

**Last Updated:** 2026-03-27  
**Document Version:** 1.1  
**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

---

## Git submodules (proxmox parent repo)

This workspace vendors many repositories under `git submodule`. Guidelines:

1. **Detached HEAD** after `git submodule update` is normal when you are not developing inside the submodule.
2. **To contribute code in a submodule:** `cd` into it, `git checkout main` (or the repo’s default branch), branch/commit as usual, **push that submodule’s remote**, then at the **parent** root run `git add <path>` and commit the updated submodule SHA, then push the parent.
3. **Never commit secrets** in submodule JSON “reference” files under `config/`; those snapshots are for public addresses only. See [SUBMODULE_HYGIENE.md](SUBMODULE_HYGIENE.md).
4. **Verify clean trees** before tagging or CI: `bash scripts/verify/submodules-clean.sh` from the parent root.

---

## Related Documentation

- **[DOCUMENTATION_STYLE_GUIDE.md](DOCUMENTATION_STYLE_GUIDE.md)** ⭐⭐⭐ - Style guide
- **[MASTER_INDEX.md](../MASTER_INDEX.md)** ⭐⭐⭐ - Documentation index
- **[SUBMODULE_HYGIENE.md](SUBMODULE_HYGIENE.md)** — submodule workflow, explorer remotes, JSON config notes
- **[DOCUMENTATION_CONSOLIDATION_PLAN.md](DOCUMENTATION_CONSOLIDATION_PLAN.md)** — consolidation scope; **[DOCUMENTATION_QUALITY_REVIEW.md](DOCUMENTATION_QUALITY_REVIEW.md)** — quality review

---

**Last Updated:** 2026-03-27  
**Review Cycle:** Quarterly