Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
219 lines (143 loc) · 5.2 KB

CONTRIBUTING.md

File metadata and controls

219 lines (143 loc) · 5.2 KB
Raw

Contributing to Kubelabs

Thank you for contributing to Kubelabs! This guide explains how to add new tutorials and keep the repository clean and well-structured.

Table of Contents

Code of Conduct

Be respectful, inclusive, and constructive. See the Collabnix Community Slack for community guidelines.

How to Add a New Tutorial

  1. Pick a topic — Check the existing directories to avoid duplicates. Good candidates are Kubernetes features, ecosystem tools, or cloud provider integrations not yet covered.

  2. Create the directory — Name it <Topic>101 for beginner content or <Topic>201 for intermediate:

    mkdir Gateway101

  3. Follow the tutorial structure described below.

  4. Validate your tutorial before opening a PR:

    ./scripts/validate-tutorials.sh Gateway101/

  5. Open a Pull Request targeting the master branch.

Tutorial Structure

Every tutorial directory must contain:

<Topic>101/
├── README.md          ← Main tutorial file (required)
└── *.yaml             ← Kubernetes manifests referenced in the tutorial

Additional files (optional):

<Topic>101/
├── README.md
├── <subtopic>.md      ← Additional markdown pages for advanced topics
├── *.yaml             ← Manifest files
└── scripts/           ← Helper scripts (shell, Python, etc.)

Tutorial Structure Template

Use the following template when creating a new tutorial (README.md):

# <Topic> 101

A brief (2-3 sentence) description of what this topic is and why it matters.

## What You Will Learn

- Concept 1
- Concept 2
- Hands-on lab

## Prerequisites

- A running Kubernetes cluster (use [Play with Kubernetes](https://labs.play-with-k8s.com/) if needed)
- `kubectl` installed and configured
- Any topic-specific tools

---

## What is <Topic>?

<!-- Theory section: explain the concept clearly with diagrams or tables if helpful -->

---

## Lab 1: <First Lab Title>

<!-- Step-by-step instructions -->

```bash
# Example command
kubectl apply -f example.yaml

Expected output:

<paste real output here>

Cleaning Up

kubectl delete -f example.yaml

Further Reading


---

## Tutorial Checklist

Before opening a PR, verify:

- [ ] Directory is named `<Topic>101` or `<Topic>201`
- [ ] `README.md` exists and is non-empty (≥ 100 bytes)
- [ ] `README.md` starts with an `# H1` heading
- [ ] All YAML manifests are syntactically valid (`yamllint`)
- [ ] All YAML manifests include `resources.requests` and `resources.limits` for containers
- [ ] Steps are in logical order and can be followed top-to-bottom
- [ ] A "Cleaning Up" section is included
- [ ] A "Further Reading" or "Next Steps" section is included
- [ ] The tutorial is linked from `README.md` in the repo root
- [ ] `./scripts/validate-tutorials.sh <dir>` passes with no errors

---

## YAML Manifest Guidelines

- Always specify `apiVersion`, `kind`, `metadata`, and `spec`
- Always add `resources.requests` and `resources.limits` to container specs
- Use `namespace: default` explicitly unless a different namespace is required
- Add comments to explain non-obvious fields
- Use realistic but minimal resource values (e.g., `cpu: "50m"`, `memory: "64Mi"`)
- Prefer multi-document YAML files (separated by `---`) over many single-resource files

---

## Validation

The repository includes an automated validator. Run it locally before opening a PR:

```bash
# Validate all tutorials
./scripts/validate-tutorials.sh

# Validate a specific tutorial
./scripts/validate-tutorials.sh Gateway101/

The validator checks:

  1. ✅ README.md exists
  2. ✅ README.md has at least 100 bytes of content
  3. ✅ README.md contains a Markdown heading
  4. ✅ All *.yaml / *.yml files are syntactically valid
  5. ⚠️ No placeholder links (e.g., TODO, FIXME, bare #)

The same validation runs automatically in CI on every pull request via the Validate Tutorials GitHub Actions workflow.

Submitting a Pull Request

  1. Fork the repository and create a feature branch:

    git checkout -b add-gateway101-tutorial

  2. Make your changes following the guidelines above.

  3. Run the validator:

    ./scripts/validate-tutorials.sh <YourTopic>101/

  4. Commit your changes with a descriptive message:

    git commit -m "Add Gateway API 101 tutorial"

  5. Push and open a Pull Request against master.

  6. The automated CI will:

    • Validate tutorial structure
    • Lint Markdown files
    • Validate YAML syntax
    • Summarise changed tutorial directories

  7. Address any review comments and update your PR.

Thank you for helping make Kubelabs the best free Kubernetes learning platform! 🚀