Guide for contributing to Hyper2KVM documentation.
Every documentation directory must have:
| Type | Pattern | Example |
|---|---|---|
| Index/Hub | README.md or index.md |
features/README.md |
| Numbered Guides | ##-description.md |
01-Installation.md |
| Feature Docs | feature-name.md |
vmdk-inspector.md |
| Topic Docs | topic-name.md |
security-best-practices.md |
| Versioned | NAME_v#.#.#.md |
RELEASE_NOTES_v2.1.0.md |
# Document Title (H1 - Only One Per Document)
Brief description of what this document covers.
---
## Section (H2)
Content here.
### Subsection (H3)
More specific content.
---
## Related Documentation
- [Link Text](relative/path.md) - Description
Rules:
--- horizontal rules to separate major sectionsdocs/
├── index.md # Main hub - links to everything
├── FAQ.md # Frequently asked questions
├── GLOSSARY.md # Complete terminology
├── QUICK_REFERENCE.md # One-page command reference
│
├── getting-started/ # New user documentation
│ ├── README.md # Getting started hub
│ └── ##-*.md # Numbered guides
│
├── tutorials/ # Step-by-step learning
│ ├── README.md # Tutorials hub
│ └── ##-*.md # Numbered tutorials
│
├── recipes/ # Quick solutions
│ ├── README.md # Recipes hub
│ └── ##-*.md # Recipe collections
│
├── guides/ # Task-oriented guides
│ ├── README.md # Guides hub
│ ├── cli/ # CLI documentation
│ ├── migration/ # Migration workflows
│ ├── tui/ # Terminal UI guides
│ └── configuration/ # Configuration guides
│
├── features/ # Feature documentation
│ ├── README.md # Features hub
│ └── vmcraft/ # VMCraft engine docs
│
├── os-support/ # OS-specific guides
│ ├── README.md # OS support hub
│ └── windows/ # Windows-specific docs
│
├── deployment/ # Deployment guides
│ ├── README.md # Deployment hub
│ ├── openshift/ # OpenShift-specific
│ └── releases/ # Release notes
│
├── worker/ # Worker protocol
│ └── README.md # Worker protocol hub
│
├── test-results/ # Test reports
│ └── README.md # Test results hub
│
├── reference/ # Technical reference
│ ├── README.md # Reference hub
│ └── api/ # API documentation
│
└── development/ # Development guides
└── README.md # Development hub
| Content Type | Location | Example |
|---|---|---|
| Getting Started | getting-started/ |
Installation, quick start |
| Step-by-Step Tutorial | tutorials/ |
Beginner migration tutorial |
| Quick Recipe | recipes/ |
“Migrate Ubuntu VM” recipe |
| Task Guide | guides/ |
“Batch Migration” guide |
| Feature Documentation | features/ |
“VMDK Inspector” feature |
| OS-Specific | os-support/ |
“Windows Migration” guide |
| Deployment | deployment/ |
“OpenShift Deployment” |
| API Reference | reference/api/ |
“VMCraft API” reference |
| Test Results | test-results/ |
“CentOS 9 Test Results” |
| Worker Protocol | worker/ |
“REST API Specification” |
# Guide Title
Brief description (1-2 sentences).
**Time**: 10 minutes
**Level**: Beginner
**Prerequisites**: List what's needed
---
## Quick Start
Fastest path to success (3-5 steps).
---
## Detailed Steps
### Step 1: First Thing
Instructions...
### Step 2: Second Thing
Instructions...
---
## Troubleshooting
Common issues and solutions.
---
## Next Steps
- [Related Guide 1](link)
- [Related Guide 2](link)
# Feature Name
Brief description and use case.
**Status**: ✅ Production Ready
**Since**: v1.0.0
---
## Overview
What this feature does and why it exists.
---
## Usage
### Basic Usage
```yaml
# Configuration example
# Advanced configuration
Description and code.
Description and code.
| Option | Type | Default | Description |
|---|---|---|---|
name |
string | - | What it does |
Common issues and solutions.
# Tutorial Title
What you'll learn in this tutorial.
**Time**: 30 minutes
**Level**: Intermediate
**Prerequisites**:
- Prerequisite 1
- Prerequisite 2
---
## Learning Objectives
By the end of this tutorial, you will:
1. Objective 1
2. Objective 2
3. Objective 3
---
## Step 1: Setup
Instructions...
## Step 2: Main Task
Instructions...
## Step 3: Validation
How to verify it worked.
---
## Summary
What you accomplished.
---
## Next Steps
- [Next Tutorial](link)
- [Related Topic](link)
# Recipe Title
One-sentence description of what this recipe does.
**Time**: 10 min | **Difficulty**: ⭐⭐ | **Platform**: Linux
---
## Use Case
When to use this recipe.
---
## Quick Steps
```bash
# Step 1: Command
command here
# Step 2: Another command
another command
# Full configuration
command: local
vmdk: /path/to/vm.vmdk
# ... rest of config
How to adapt this recipe:
Quick fixes for common issues.
---
## Emoji Usage Guide
Use emojis consistently for visual navigation:
| Emoji | Meaning | Usage |
|-------|---------|-------|
| 🚀 | Getting Started | Installation, quick start |
| 📚 | Documentation | Guides, references |
| 🎓 | Learning | Tutorials, education |
| 🍳 | Recipes | Quick solutions |
| 🛠️ | Tools | CLI, utilities |
| 🔧 | Features | Feature documentation |
| 🖥️ | OS-Specific | Operating system guides |
| 🚢 | Deployment | Deployment guides |
| 🔄 | Worker/Jobs | Worker protocol, jobs |
| 🔬 | Testing | Test results, validation |
| ⚡ | Quick Access | Fast reference |
| ✅ | Success/Done | Completed, working |
| ❌ | Error/No | Not working, don't do |
| ⭐ | Featured/Important | Highlighted content |
| 💡 | Tip | Helpful information |
| ⚠️ | Warning | Caution required |
| 🔗 | Links | Related documentation |
| 📊 | Metrics/Stats | Performance, statistics |
| 🎯 | Goal/Target | Objectives, use cases |
---
## Adding New Documentation
### Process
1. **Identify the type** of documentation (guide, tutorial, recipe, reference)
2. **Choose the location** based on the file organization guide
3. **Create the file** with appropriate naming
4. **Write content** following the structure templates
5. **Add navigation** - update parent README.md
6. **Cross-reference** - link from related docs
7. **Update indexes** - add to docs/index.md if major
8. **Test links** - verify all links work
9. **Submit PR** - for review
### Checklist for New Documentation
- [ ] File created in correct directory
- [ ] Follows naming convention
- [ ] Uses correct structure template
- [ ] Includes all required sections
- [ ] Has clear, concise content
- [ ] Includes code examples (if applicable)
- [ ] Links to related documentation
- [ ] Added to parent README.md
- [ ] Added to docs/index.md (if major)
- [ ] All links tested and working
- [ ] Spelling and grammar checked
- [ ] Follows emoji usage guide
- [ ] Screenshots/diagrams added (if needed)
---
## Updating Existing Docs
### When to Update
- New features added
- Bugs fixed or behavior changed
- Better examples discovered
- User feedback indicates confusion
- Links broken or outdated
- New best practices emerge
### Update Process
1. **Read the existing doc** completely
2. **Identify what needs updating** (content, links, examples)
3. **Make changes** while maintaining consistency
4. **Test all examples** to ensure they work
5. **Update "Last Updated"** date at bottom
6. **Submit PR** with clear description of changes
### Major vs Minor Updates
**Minor Updates** (direct commit):
- Fix typos
- Update broken links
- Clarify existing content
- Update dates/versions
**Major Updates** (PR required):
- Restructure document
- Add/remove major sections
- Change examples significantly
- Update architecture/design docs
---
## Code Examples
### YAML Examples
```yaml
# migration.yaml - Description of what this does
command: local
vmdk: /path/to/vm.vmdk
output_dir: /output
to_output: vm.qcow2
# Enable features
fstab_mode: stabilize-all # Comment explaining why
regen_initramfs: true # Another helpful comment
Rules:
# Description of what this command does
h2kvmctl migrate local /path/to/vm.vmdk --output /output/vm.qcow2
# Multi-line command with explanation
h2kvmctl --config << EOF
command: local
vmdk: /path/to/vm.vmdk
output_dir: /output
EOF
Rules:
from hyper2kvm import Migration
# Create a migration instance
migration = Migration(
vmdk="/path/to/vm.vmdk",
output_dir="/output"
)
# Execute the migration
result = migration.run()
print(f"Migration complete: {result.success}")
Rules:
Use tables for comparing options:
| Feature | Option A | Option B |
|---------|----------|----------|
| Speed | Fast | Slower |
| Size | Large | Small |
| Use Case | Production | Testing |
Use tables for documenting options:
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `timeout` | integer | 300 | Operation timeout in seconds |
| `retry` | integer | 3 | Number of retry attempts |
Use for sequential steps:
1. First step
2. Second step
3. Third step
Use for non-sequential items:
- Item one
- Item two
- Item three
Use relative paths:
- [Installation Guide](/hyper2kvm/getting-started/01-Installation.html)
- [API Reference](/hyper2kvm/reference/api/API-Reference.html)
Include description:
- [QEMU Documentation](https://www.qemu.org/docs/) - Official QEMU docs
For same-page navigation:
- [Overview](#overview)
- [Examples](#examples)
docs/images/ directory
Before submitting:
Reviewers should check:
# Check for broken links
find docs -name "*.md" -exec grep -H "](.*)" {} \; | \
grep -v "http" | cut -d: -f2 | cut -d\( -f2 | cut -d\) -f1 | \
while read link; do [ -f "$link" ] || echo "Broken: $link"; done
# Using aspell
find docs -name "*.md" -exec aspell check {} \;
Always test code examples:
# Test YAML examples
yamllint docs/**/*.md
# Test bash examples (manually)
# Copy each bash example and run it
Include at the bottom of major documents:
---
**Last Updated**: February 2026
**Hyper2KVM Version**: 2.1.0
**Documentation Version**: 2.1.0
For deprecated features:
> ⚠️ **DEPRECATED**: This feature is deprecated as of v2.0.0.
> Use [New Feature](link-to-new.md) instead.
| Task | Command/Action |
|---|---|
| Create new guide | Add to appropriate directory, update README |
| Update existing | Edit file, test examples, update date |
| Add to index | Update docs/index.md |
| Test links | Run link checker or manual testing |
| Submit changes | Create PR with description |
Last Updated: February 2026 Documentation Version: 2.1.0