Skip to content

Latest commit

 

History

History
370 lines (260 loc) · 8.66 KB

CONTRIBUTING.md

File metadata and controls

370 lines (260 loc) · 8.66 KB

Contributing Guide

Thanks for helping build this community resource! Every improvement helps future learners. Goal: high-quality, searchable interview Q&A—organized by week—with consistent metadata.

Contents

  1. Prerequisites
  2. First-Time Setup (once)
     • Step 1 — Fork & Authenticate
     • Step 2 — Clone Your Fork Locally
     • Step 3 — Install deps & Pre-commit Hook
  3. Your First PR (end-to-end)
  4. Every PR: Quick Checklist
  5. Keeping Your Fork in Sync
  6. Answer Structure & Frontmatter
  7. Commit & PR Conventions
  8. Reviews, Governance & FAQ

Prerequisites

  • Git (with SSH or HTTPS set up)
  • Python 3.11+
  • Bash (Git Bash on Windows is fine)

Why: Contributors run two scripts locally to validate metadata and rebuild the index.

Don’t edit .github/** or scripts/**. If you need something changed there, open an issue or propose the change under meta/proposals/ and maintainers will apply it.

First-Time Setup (once)

Step 1 — Fork & Authenticate

  1. Fork the repo: https://github.com/pravinmishraaws/devops-micro-internship-interviews

  2. Authenticate Git SSH (recommended):

    ssh-keygen -t ed25519 -C "your.email@example.com"
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

    Add ~/.ssh/id_ed25519.pub to GitHub → Settings → SSH and GPG keys.

    Force SSH for GitHub (avoids HTTPS prompts):

    git config --global url."git@github.com:".insteadOf "https://github.com/"

    HTTPS (alternative):

    git config --global credential.helper cache

  3. Test:

    ssh -T git@github.com

    Expected: greeting from GitHub.

Step 2 — Clone Your Fork Locally

git clone git@github.com:yourusername/devops-micro-internship-interviews.git
cd devops-micro-internship-interviews
git remote -v

Add the original repo as upstream:

git remote add upstream https://github.com/pravinmishraaws/devops-micro-internship-interviews.git

# Now, check remote again
git remote -v

Why: You’ll pull updates from upstream and push your work to origin (your fork).

Step 3 — Install Deps & Pre-commit Hook

Create a virtualenv and install deps:

macOS / Linux

python -m venv .venv && source .venv/bin/activate
pip install -r scripts/requirements.txt

Windows (PowerShell)

py -m venv .venv
. .\.venv\Scripts\Activate.ps1
pip install -r scripts\requirements.txt

(Recommended) One-shot setup script

[Mac, Linux user ] Create scripts/setup.sh (commit this file to repo) and include the pre-commit hook installer:

#!/usr/bin/env bash
set -euo pipefail

# Create venv if missing
if [ ! -d ".venv" ]; then
  python -m venv .venv
fi

# Activate venv (POSIX shells)
# shellcheck source=/dev/null
source .venv/bin/activate || true

# Fallback for Git Bash on Windows
if [ ! -n "${VIRTUAL_ENV-}" ] && [ -f ".venv/Scripts/activate" ]; then
  # shellcheck disable=SC1091
  . .venv/Scripts/activate
fi

pip install -r scripts/requirements.txt

# Install pre-commit hook
HOOK_PATH=".git/hooks/pre-commit"
echo "Setting up pre-commit hook..."
cat > "$HOOK_PATH" <<'EOF'
#!/bin/bash
echo "🧹 Running pre-commit validation..."
python scripts/validate_frontmatter.py || exit 1
python scripts/build_index.py || exit 1
echo "✅ Validation passed!"
EOF
chmod +x "$HOOK_PATH"
echo "✅ Pre-commit hook installed successfully!"

[ Windows User ] helper (scripts/setup.ps1) for PowerShell users:

$ErrorActionPreference = "Stop"

if (-not (Test-Path ".venv")) {
  py -m venv .venv
}

. .\.venv\Scripts\Activate.ps1
pip install -r scripts\requirements.txt

$hookPath = ".git/hooks/pre-commit"
@"
#!/bin/bash
echo "🧹 Running pre-commit validation..."
python scripts/validate_frontmatter.py || exit 1
python scripts/build_index.py || exit 1
echo "✅ Validation passed!"
"@ | Out-File -FilePath $hookPath -Encoding ascii -NoNewline
bash -lc "chmod +x $hookPath"
Write-Host "✅ Pre-commit hook installed successfully!"

Run it once:

bash scripts/setup.sh

Now every commit will auto-run: python scripts/validate_frontmatter.py and python scripts/build_index.py and block bad commits.

Your First PR (end-to-end)

  1. Sync main (fast-forward only)
git fetch upstream
git checkout main
git pull --ff-only upstream main
  1. Create a feature branch
git checkout -b Q####-kebab-title
  1. Add your question
  • Path: weeks/<week>/questions/
  • File: Q####-kebab-title.md
  • Include frontmatter and sections (see below)
  1. Run validators manually (optional)
python scripts/validate_frontmatter.py && python scripts/build_index.py
  1. Commit (pre-commit will auto-validate)
git add weeks/<week>/questions/Q####-kebab-title.md
git commit -m "question(Q0401): add IAM role vs user with pitfalls and refs"
  1. Push & open PR
git push -u origin Q####-kebab-title

On GitHub → Compare & pull request. Base: pravinmishraaws/main • Compare: yourusername/Q####-kebab-title

  1. Fill PR description
  • What you added, which week, validation passed, any notes

Every PR: Quick Checklist

  • One question per file → weeks/<week>/questions/Q####-kebab-title.md

  • Frontmatter includes: id, title, difficulty, week, topics, tags, author, reviewed

  • Structure: Short Answer → Deep Dive → Pitfalls → References

  • Run locally (auto via pre-commit) or manually:

    python scripts/validate_frontmatter.py && python scripts/build_index.py

  • Rebase on main before pushing

  • Cite sources; avoid plagiarism

Why: CI runs the same checks—passing locally saves reviewers’ time.

Keeping Your Fork in Sync

Before you start or when PRs merge:

git fetch upstream
git checkout main
git pull --ff-only upstream main
git checkout Q####-kebab-title
git rebase main
# If conflicts: fix -> git add <files> -> git rebase --continue
# If you rewrote history: 
git push --force-with-lease origin Q####-kebab-title

Why: Linear history keeps diffs clean and reviews fast.

Answer Structure & Frontmatter

Frontmatter (copy/paste)

---
id: Q0001
title: OSI vs TCP/IP — what’s the practical difference?
difficulty: entry         # one of: entry | easy | medium | hard | expert
week: 00
topics: [networking, models]
tags: [networking, osi, tcpip]
author: yourgithubusername
reviewed: false
---

Tip: id number must match the file name (Q0001-…md).

Recommended sections

## Short Answer
2–4 sentences an interviewer could accept.

## Deep Dive
Context, trade-offs, examples, diagrams if helpful, commands.

## Pitfalls
Common mistakes and how to avoid them.

## References
- Official docs
- High-quality blogs, RFCs, whitepapers

Commit & PR Conventions

Conventional Commit examples:

question(Q0401): add IAM role vs user
docs: improve contributing guide with pre-commit hook
chore: fix build index path

PR title:

question(Q0401): add IAM role vs user with pitfalls and references

PR description:

  • What changed (week, file)
  • Validation passed locally
  • Any reviewer notes

Reviews, Governance & FAQ

Reviews & Governance

  • PRs require CODEOWNERS approval for the week you changed
  • CI enforces metadata/formatting; blocked PRs must be fixed and re-pushed
  • High-quality answers are later marked reviewed: true

Common Pitfalls

Issue Fix
id doesn’t match file name Rename file or update id to match
Missing frontmatter field Copy template again; run validator
Multiple questions in one PR Split into separate PRs
Failing CI Run both scripts locally; read the error output

FAQ

  • Can I update an existing answer? Yes—explain the change in your PR.
  • Can I submit multiple questions in one PR? Prefer one per PR.
  • Do I need SSH? Recommended. HTTPS works with cached credentials.

Code of Conduct Be respectful and constructive. Disagreements are fine—disrespect isn’t.

Thanks!

Your contributions help hundreds of learners practice confidently. 🙌