Jika tim Anda memakai repo seperti CS Fundamentals sebagai sumber belajar internal, masalahnya biasanya bukan kekurangan materi, tetapi kontribusi yang cepat berantakan: folder tidak konsisten, tautan rusak, catatan sulit dicari, dan update materi tidak terlacak dengan baik. Learning pipeline CS fundamentals di GitHub Actions membantu mengubah repo belajar menjadi sistem yang dapat divalidasi otomatis, mudah direview, dan nyaman dipakai untuk onboarding maupun persiapan interview internal.

Pendekatan ini tidak membahas isi DSA, DBMS, OS, atau System Design-nya, melainkan tooling dan otomasi di sekeliling repo. Target akhirnya sederhana: setiap kontribusi mengikuti struktur yang sama, lolos lint, punya checklist review yang jelas, index materi selalu mutakhir, dan perubahan penting bisa diringkas lewat release notes.

Mengapa repo belajar perlu pipeline, bukan hanya README

Repo pembelajaran tim sering dimulai dari satu README besar lalu tumbuh tanpa aturan. Pada tahap awal itu masih cukup, tetapi saat kontributor bertambah, kualitas konten mulai tidak merata. GitHub Actions berguna di sini karena ia memberi guardrail yang konsisten setiap kali ada pull request atau update ke branch utama.

  • Konsistensi struktur: topik dan subtopik punya format folder yang sama.
  • Kualitas dokumen: heading, link, dan file Markdown dapat divalidasi otomatis.
  • Review lebih cepat: reviewer fokus ke substansi karena format dasar sudah dicek mesin.
  • Navigasi lebih baik: index atau TOC dapat dibuat ulang otomatis dari struktur folder.
  • Audit perubahan: update materi bisa dirangkum dalam release notes.

Untuk use case tim, ini sangat berguna saat engineer baru perlu jalur belajar yang rapi atau saat ada program placement prep internal yang memerlukan ritme update materi mingguan.

Struktur repo yang disarankan untuk CS fundamentals

Jangan langsung memulai dari workflow YAML. Rapikan dulu bentuk repo-nya, karena automation akan mengikuti konvensi yang Anda tetapkan. Struktur yang terlalu bebas akan membuat validasi sulit dan hasil otomasi tidak stabil.

Contoh struktur direktori

cs-fundamentals/
├─ README.md
├─ CONTRIBUTING.md
├─ .github/
│  ├─ pull_request_template.md
│  └─ workflows/
│     ├─ docs-ci.yml
│     ├─ generate-index.yml
│     └─ release-notes.yml
├─ scripts/
│  ├─ validate-structure.sh
│  └─ generate-index.py
├─ docs/
│  ├─ dsa/
│  │  ├─ README.md
│  │  ├─ arrays/
│  │  │  └─ notes.md
│  │  ├─ linked-list/
│  │  │  └─ notes.md
│  │  └─ trees/
│  │     └─ notes.md
│  ├─ dbms/
│  │  ├─ README.md
│  │  ├─ normalization/
│  │  │  └─ notes.md
│  │  └─ indexing/
│  │     └─ notes.md
│  ├─ os/
│  │  ├─ README.md
│  │  ├─ processes-threads/
│  │  │  └─ notes.md
│  │  └─ scheduling/
│  │     └─ notes.md
│  └─ system-design/
│     ├─ README.md
│     ├─ caching/
│     │  └─ notes.md
│     └─ load-balancing/
│        └─ notes.md
└─ changelog/
   └─ releases.md

Aturan struktur yang sebaiknya dibakukan

  • Semua materi inti berada di bawah folder docs/.
  • Kategori utama dibatasi, misalnya: dsa, dbms, os, system-design.
  • Setiap subtopik memakai nama folder lowercase-kebab-case.
  • Isi minimal subtopik adalah notes.md.
  • Setiap kategori punya README.md untuk ringkasan dan daftar topik.
  • Hindari menyimpan file acak seperti final.md, notes-new.md, atau copy 2.md.

Kenapa aturan ini penting? Karena otomatisasi seperti generator index, validasi folder, dan pengecekan link bekerja paling baik jika nama dan letak file dapat diprediksi.

Komponen learning pipeline di GitHub Actions

Untuk repo belajar, pipeline umumnya tidak perlu rumit. Mulailah dari empat komponen inti yang benar-benar berguna.

1. Lint Markdown dan validasi tautan

Lint Markdown membantu menjaga heading, list, dan format dasar tetap konsisten. Validasi tautan membantu mendeteksi link internal yang rusak setelah file dipindahkan atau diganti nama.

Yang perlu diperhatikan:

  • Markdown lint menangkap masalah style dan keterbacaan.
  • Link check penting untuk internal link antar-file.
  • Untuk external link, hasilnya kadang flaky karena rate limit atau situs tujuan sedang down. Karena itu, bedakan penanganan link internal dan eksternal jika perlu.

2. Validasi format folder dan nama file

Ini adalah komponen yang paling sering terlewat. Tanpa validasi struktur, repo belajar biasanya cepat kehilangan bentuk. Anda bisa memakai script shell atau Python sederhana untuk memastikan hanya folder dan file yang diizinkan yang bisa masuk.

3. Auto-generate index atau TOC

Jika daftar topik ditulis manual, ia cepat basi. Lebih aman jika index utama atau README kategori dibuat dari struktur folder. Dengan begitu, navigasi repo selalu sinkron dengan materi yang benar-benar ada.

4. Release notes untuk update materi

Release notes tidak harus formal seperti proyek software. Untuk repo belajar, release notes berguna untuk menjawab pertanyaan: topik apa yang baru ditambahkan, apa yang direvisi, dan apa yang wajib dibaca tim minggu ini.

Workflow GitHub Actions yang sederhana dan praktis

Berikut contoh workflow CI dasar untuk learning pipeline CS fundamentals di GitHub Actions. Contoh ini menjalankan lint Markdown, pengecekan tautan dasar, dan validasi struktur folder.

name: docs-ci

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  validate-docs:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install markdown tools
        run: |
          npm install -g markdownlint-cli markdown-link-check

      - name: Lint markdown files
        run: |
          markdownlint README.md docs/**/*.md

      - name: Check markdown links
        run: |
          find docs -name "*.md" -print0 | xargs -0 -I{} markdown-link-check {} 

      - name: Validate repository structure
        run: |
          bash scripts/validate-structure.sh

Workflow di atas sengaja dibuat sederhana. Dalam praktik nyata, Anda mungkin ingin menambahkan caching, mengecualikan folder tertentu, atau membatasi link checker hanya pada file yang berubah di pull request.

Contoh script validasi struktur

Script berikut memastikan kategori utama valid, subfolder memakai format kebab-case, dan setiap subtopik memiliki notes.md.

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

ROOT="docs"
ALLOWED_CATEGORIES=("dsa" "dbms" "os" "system-design")

is_allowed_category() {
  local value="$1"
  for item in "${ALLOWED_CATEGORIES[@]}"; do
    if [[ "$item" == "$value" ]]; then
      return 0
    fi
  done
  return 1
}

for category_path in "$ROOT"/*; do
  [[ -d "$category_path" ]] || continue
  category=$(basename "$category_path")

  if ! is_allowed_category "$category"; then
    echo "Kategori tidak diizinkan: $category"
    exit 1
  fi

  for topic_path in "$category_path"/*; do
    [[ -d "$topic_path" ]] || continue
    topic=$(basename "$topic_path")

    if [[ ! "$topic" =~ ^[a-z0-9-]+$ ]]; then
      echo "Nama topik harus lowercase-kebab-case: $category/$topic"
      exit 1
    fi

    if [[ ! -f "$topic_path/notes.md" ]]; then
      echo "File notes.md tidak ditemukan di: $category/$topic"
      exit 1
    fi
  done
done

echo "Struktur repository valid"

Kenapa script seperti ini efektif? Karena ia murah dipelihara, mudah dibaca reviewer, dan langsung memaksa kontributor mengikuti pola repo. Untuk use case dokumentasi internal, shell script sederhana sering lebih cukup daripada tool yang terlalu kompleks.

Auto-generate index dan TOC agar navigasi tidak basi

Index otomatis sangat membantu ketika jumlah topik bertambah. Anda bisa membuat script kecil yang memindai folder di bawah docs/ lalu menulis ulang daftar topik ke README utama atau file index terpisah.

Contoh generator index sederhana dengan Python

from pathlib import Path

root = Path("docs")
output = ["# CS Fundamentals Index", ""]

for category in sorted([p for p in root.iterdir() if p.is_dir()]):
    output.append(f"## {category.name.upper()}")
    output.append("")
    for topic in sorted([p for p in category.iterdir() if p.is_dir()]):
        notes = topic / "notes.md"
        if notes.exists():
            output.append(f"- [{topic.name}]({notes.as_posix()})")
    output.append("")

Path("README.md").write_text("\n".join(output), encoding="utf-8")
print("README.md berhasil diperbarui")

Workflow untuk generate index otomatis

name: generate-index

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'scripts/generate-index.py'

jobs:
  update-index:
    runs-on: ubuntu-latest
    permissions:
      contents: write

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.x'

      - name: Generate index
        run: python scripts/generate-index.py

      - name: Commit updated index
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add README.md
          git diff --cached --quiet || git commit -m "chore(docs): update generated index"
          git push

Ada satu trade-off penting di sini: workflow yang melakukan commit balik ke branch utama harus dirancang hati-hati agar tidak memicu loop. Cara aman yang umum adalah membatasi trigger ke path tertentu atau memastikan commit generator tidak mengubah file yang sama berulang kali.

PR checklist dan aturan branch untuk menjaga kualitas kontribusi

Automation tidak akan efektif kalau proses review manusianya longgar. Karena itu, kombinasikan CI dengan aturan branch dan template PR yang jelas.

Aturan branch yang disarankan

  • Gunakan main sebagai branch terlindungi.
  • Nonaktifkan direct push ke main.
  • Wajibkan pull request untuk semua perubahan materi.
  • Wajibkan status check lulus sebelum merge.
  • Minimal satu reviewer untuk perubahan besar atau perubahan struktur.
  • Gunakan nama branch yang konsisten, misalnya docs/dsa-binary-search atau fix/dbms-link-indexing.

Contoh PR template

## Ringkasan perubahan
- Menambahkan / memperbarui topik:
- Kategori:
- Alasan perubahan:

## Checklist penulis
- [ ] File ditempatkan di folder yang benar
- [ ] Nama folder memakai lowercase-kebab-case
- [ ] Setiap topik memiliki notes.md
- [ ] Link internal sudah dicek
- [ ] Tidak ada duplikasi materi yang jelas
- [ ] README / index relevan ikut diperbarui bila perlu

## Checklist reviewer
- [ ] Materi sesuai kategori
- [ ] Penjelasan cukup jelas untuk pembaca internal
- [ ] Struktur dan istilah konsisten dengan repo
- [ ] Tidak ada tautan rusak atau referensi yang hilang

Checklist seperti ini terlihat sederhana, tetapi sangat membantu saat repo dipakai banyak engineer dengan gaya menulis yang berbeda. Mesin mengecek aturan teknis, sedangkan reviewer fokus ke kualitas isi dan ketepatan konteks.

Release notes untuk update materi belajar

Jika tim Anda rutin memperbarui materi, release notes akan memudahkan komunikasi. Anda tidak harus membuat versi semantik seperti aplikasi produksi. Cukup buat ritme yang cocok, misalnya mingguan atau per batch pembelajaran.

Apa yang sebaiknya masuk ke release notes

  • Topik baru yang ditambahkan.
  • Materi lama yang direvisi signifikan.
  • Perubahan struktur repo atau format penulisan.
  • Daftar bacaan wajib untuk onboarding batch berikutnya.

Contoh workflow release notes sederhana

name: release-notes

on:
  workflow_dispatch:
  push:
    tags:
      - 'learning-*'

jobs:
  publish-notes:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Build release summary
        run: |
          echo "## Update materi" > release_body.md
          git log --pretty=format:"- %s" $(git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo "")..HEAD >> release_body.md || true
          cat release_body.md

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: release-notes
          path: release_body.md

Workflow ini belum otomatis membuat GitHub Release, tetapi sudah cukup untuk menghasilkan ringkasan perubahan sebagai artefak. Jika tim Anda memang membutuhkan release yang formal, Anda bisa melanjutkannya dengan action tambahan, tetapi mulai dari bentuk sederhana biasanya lebih mudah dipelihara.

Kesalahan umum dan tips debugging

Link checker terlalu sering gagal

Penyebab umum adalah external link yang tidak stabil atau diblokir sementara. Solusinya:

  • Prioritaskan validasi internal link sebagai blocking check.
  • Jadikan external link check sebagai non-blocking atau pisahkan workflow-nya.
  • Simpan daftar domain yang sering bermasalah jika memang perlu dikecualikan.

Workflow generator index melakukan commit terus-menerus

Biasanya terjadi karena file output tidak deterministik, misalnya urutan folder berubah-ubah atau ada timestamp yang ikut ditulis. Pastikan generator menghasilkan output stabil dan hanya commit jika benar-benar ada perubahan.

Validasi struktur terlalu ketat

Ini sering membuat kontributor frustrasi, terutama saat tim masih bereksperimen. Mulailah dari aturan minimum yang benar-benar penting: lokasi folder, penamaan, dan keberadaan file inti. Jangan langsung menambahkan banyak aturan style yang sulit dijelaskan manfaatnya.

CI lambat untuk repo dokumentasi

Untuk repo dokumen, pipeline idealnya cepat. Hindari setup yang terlalu berat. Kalau perlu, jalankan pengecekan hanya pada file yang berubah, terutama untuk link check dan generator yang mahal.

Kapan otomasi ini paling berguna

Pipeline seperti ini paling terasa manfaatnya dalam dua skenario.

1. Onboarding engineer baru

Engineer baru sering butuh peta belajar yang jelas. Dengan repo yang tervalidasi dan terindeks otomatis, mereka tidak perlu menebak urutan topik atau mencari file yang tercecer. Reviewer juga lebih mudah memastikan materi onboarding tetap konsisten antar batch.

2. Placement prep atau interview prep internal

Jika tim mengadakan persiapan internal untuk assessment, mobility, atau interview, repo belajar biasanya diperbarui cepat oleh banyak orang. Tanpa automation, hasilnya mudah kacau. Dengan GitHub Actions, tim bisa menjaga kualitas catatan sambil tetap bergerak cepat.

Aturan praktisnya: semakin banyak kontributor, semakin sering struktur berubah, dan semakin penting repo itu untuk proses tim, semakin besar nilai otomasi ini.

Rekomendasi implementasi bertahap

Supaya adopsinya tidak terasa berat, terapkan bertahap:

  1. Tahap 1: rapikan struktur folder dan buat PR template.
  2. Tahap 2: aktifkan Markdown lint dan validasi struktur.
  3. Tahap 3: tambahkan pengecekan tautan internal.
  4. Tahap 4: otomatisasi index atau TOC.
  5. Tahap 5: buat release notes untuk update materi periodik.

Urutan ini bekerja baik karena Anda membangun fondasi lebih dulu. Jika langsung memulai dari release notes atau generator tanpa struktur yang jelas, pipeline justru menambah noise.

Penutup

Mengubah repo referensi seperti CS Fundamentals menjadi workflow belajar tim yang rapi tidak memerlukan platform baru. Dengan GitHub Actions, beberapa script kecil, aturan branch yang masuk akal, dan checklist review yang konsisten, Anda bisa menjadikan repo belajar sebagai sistem yang terkelola, bukan sekadar kumpulan catatan.

Fokus utamanya adalah menjaga kualitas kontribusi: struktur folder jelas untuk DSA/DBMS/OS/System Design, Markdown dan tautan tervalidasi, index selalu diperbarui, dan perubahan materi mudah ditelusuri. Untuk onboarding engineer dan placement prep internal, kombinasi ini biasanya memberi dampak yang paling nyata.