Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
248 lines (181 loc) · 5.79 KB

CONTRIBUTING.md

File metadata and controls

248 lines (181 loc) · 5.79 KB

Contributing to Compose to Kubernetes Workshop

Thank you for your interest in contributing to this Kubernetes workshop! This document provides guidelines and information for contributors.

How to Contribute

Reporting Issues

If you find errors, typos, or have suggestions:

  1. Check existing issues to avoid duplicates
  2. Create a new issue with:
    • Clear description
    • Steps to reproduce (if applicable)
    • Expected vs actual behavior
    • Environment details (OS, Kubernetes version, etc.)

Suggesting Enhancements

We welcome suggestions for:

  • New workshop sections
  • Additional examples
  • Improved explanations
  • Better lab exercises
  • Tool updates

Contributing Content

Workshop Content Guidelines

  1. Structure

    • Each section should have: README.md (theory), examples/, lab/instructions.md, lab/solutions/
    • Follow existing format and style
    • Keep explanations clear and concise

  2. Code Examples

    • Use public container images (no proprietary images)
    • Test all examples before submitting
    • Include comments explaining key concepts
    • Follow Kubernetes best practices

  3. Lab Exercises

    • Include clear objectives
    • Provide step-by-step instructions
    • Add verification steps
    • Include solutions with explanations

  4. Style Guide

    • No emojis in documentation (accessibility)
    • Use markdown for formatting
    • Code blocks with proper syntax highlighting
    • Consistent terminology

Pull Request Process

  1. Fork the repository

  2. Create a feature branch

    git checkout -b feature/your-feature-name

  3. Make your changes

    • Follow the style guide
    • Test all examples and exercises
    • Update relevant documentation

  4. Commit with clear messages

    git commit -m "Add: Section on StatefulSets advanced patterns"

  5. Push to your fork

    git push origin feature/your-feature-name

  6. Create a Pull Request

    • Describe what you changed and why
    • Reference related issues
    • Include screenshots if relevant

Testing Requirements

Before submitting:

  • All YAML files are valid
  • Examples work on a fresh cluster
  • Lab solutions are accurate
  • No broken links in documentation
  • Spelling and grammar checked

Commit Message Format

Use clear, descriptive commit messages:

Type: Brief description

Detailed explanation of changes (if needed)

Fixes #123

Types:

  • Add: New content or features
  • Fix: Bug fixes or corrections
  • Update: Changes to existing content
  • Remove: Deletion of content
  • Docs: Documentation only changes
  • Style: Formatting changes

Documentation Contributions

Help improve documentation by:

  • Fixing typos and grammar
  • Clarifying confusing sections
  • Adding diagrams or visual aids
  • Improving examples
  • Updating outdated information

Translation Contributions

We welcome translations to other languages:

  1. Create a new directory: part-1-[language-code]/
  2. Translate all content
  3. Maintain the same structure
  4. Test all examples work with your translations

Development Setup

We provide multiple ways to set up your development environment:

Option 1: Dev Container (Recommended)

The easiest way to contribute! All tools are pre-installed and configured.

Prerequisites:

  • Visual Studio Code with Remote-Containers extension
  • Docker Desktop or Podman Desktop

Steps:

  1. Clone the repository
  2. Open in VS Code
  3. Click "Reopen in Container" when prompted
  4. Wait for the container to build (5-10 minutes first time)
  5. Start contributing!

What's included:

  • kubectl, helm, kind, k9s, flux
  • Marp CLI for editing slides
  • Markdown linting and validation tools
  • YAML validation
  • All VS Code extensions pre-configured

See .devcontainer/README.md for more details.

Option 2: GitHub Codespaces

Work directly in your browser:

  1. Click "Code" → "Codespaces" → "Create codespace on main"
  2. Everything is set up automatically
  3. Start contributing immediately

Option 3: Local Setup

Prerequisites:

  • Podman or Docker
  • Git
  • Text editor (VS Code recommended)
  • Node.js (for Marp CLI)

Installation:

# Clone repository
git clone https://github.com/rfaes/compose-to-kubernetes.git
cd compose-to-kubernetes

# Install Marp CLI
npm install -g @marp-team/marp-cli

# Install markdown tools
npm install -g markdownlint-cli markdown-link-check

# Start workshop environment
cd setup
./start-workshop.sh  # Linux
# or
.\start-workshop.ps1  # Windows

Testing Your Changes

Using Make (recommended):

make validate       # Validate all YAML
make test           # Run full test suite
make lint           # Lint markdown files

Manual testing:

# Create kind cluster
kind create cluster --config setup/kind/simple.yaml

# Test examples
kubectl apply -f part-1/03-deployments/examples/

# Verify
kubectl get all

# Validate YAML
kubectl apply --dry-run=client -f your-file.yaml

Preview slides:

# Live preview with hot reload
marp part-1/slides.md --watch --server

# Export to PDF
marp part-1/slides.md --pdf

Code of Conduct

Please note that this project is released with a Code of Conduct. By participating in this project you agree to abide by its terms.

Recognition

Contributors will be recognized in the project:

  • Added to AUTHORS file
  • Mentioned in release notes
  • Acknowledged in documentation

Questions?

  • Open an issue for questions about contributing
  • Join discussions in issues and pull requests
  • Check existing issues and PRs for answers

License

By contributing, you agree that your contributions will be licensed under the MIT License.

Thank You!

Your contributions make this workshop better for everyone learning Kubernetes. We appreciate your time and effort!