showmygear

Git Hygiene: Identitas & Standar

[!NOTE] Jika Software adalah Teks, Git History adalah Sastranya. Tuliskan riwayat perubahan dengan martabat engineering.

Riwayat commit yang berantakan menurunkan keterbacaan software seiring waktu. Kami menerapkan kebersihan ketat untuk memastikan repositori menceritakan “kisah” yang jelas.

---

📖 Daftar Isi

• ⚛️ Atomic Commit dan Conventional Commits
• 🤖 Agentic Git: Berkolaborasi dengan AI
• 🛡️ Identitas dan Keamanan: Signing
• ⚙️ Otomasi: Pre-commit Hooks
• ✅ Verifikasi: Integritas Dokumentasi
• ⚙️ Configuration Boilerplate

1. Atomic Commit dan Conventional Commits

Filosofi: Satu commit, satu perubahan logis. \(Kualitas Commit = \frac{1}{\Delta Ruang Lingkup}\)

flowchart LR
    S1["Mulai Perubahan"] --> S2["Implementasi"]
    S2 --> S3{"Tes Lulus?"}
    S3 -->|Tidak| S2
    S3 -->|Ya| S4["Stage & Sign"]
    S4 --> S5["Atomic Commit"]

Kami mengikuti spesifikasi Conventional Commits untuk memungkinkan Semantic Versioning dan pembuatan Changelog otomatis.

Struktur

tipe(scope): deskripsi

Tangga Tipe

• feat: Fitur baru untuk pengguna.
• fix: Perbaikan bug.
• chore: Tugas pemeliharaan (deps, config) yang tidak mengubah source code.
• docs: Perubahan dokumentasi saja.
• style: Formatting, titik koma kurang, dll (tidak ada perubahan logika).
• refactor: Restrukturisasi kode (tidak ada perubahan API, tidak ada fitur baru).
• test: Menambahkan tes yang kurang.

---

2. Agentic Git: Berkolaborasi dengan AI

Di era di mana AI bisa menulis ribuan baris kode, beban verifikasi berpindah ke pundak Arsitek. Git bukan sekadar tempat menyimpan kode, tapi tempat Anda memvalidasi setiap langkah agen AI.

A. Atomic Agentic Commits (Reviewable Chunks)

Jangan biarkan AI melakukan commit raksasa yang tidak mungkin di-review manusia.

• Aksi: Pecah hasil kerja AI menjadi potongan-potongan kecil. Jika AI mengubah Types, Logic, dan Tests, bagi menjadi 3 commit terpisah.
• Manual Review: Setiap commit dari AI harus melalui Verification Gate manual. Jangan pernah melakukan git commit -am pada hasil kerja AI tanpa inspeksi visual.

B. Context in Commits (Metadata untuk Masa Depan)

Gunakan commit message sebagai “Lighthouse” untuk pengambilan konteks AI di masa depan.

• Deskripsi Panjang (Body): Jelaskan “Mengapa” (Rasio) perubahan dilakukan, bukan hanya “Apa”. Ini membantu RAG/Long-Context AI memahami niat asli Anda saat Anda memintanya melakukan refactor 6 bulan kemudian.
• Traces: Cantumkan referensi manual instruksi atau prompt penting jika perubahan tersebut bersifat fundamental (misal: “Ref: .cursorrules section 3”).

graph TD
    AI["AI: Generate Code"] --> Triage["Architect: Triage & Slicing"]
    Triage --> C1["Commit 1: Typings/Schemas"]
    Triage --> C2["Commit 2: Business Logic"]
    Triage --> C3["Commit 3: UI/Presentation"]
    
    C1 --> V["Manual Verification / Testing"]
    C2 --> V
    C3 --> V
    V --> Push["Push to Remote"]
    
    style Triage fill:#fff9c4,stroke:#fbc02d

---

3. Identitas dan Keamanan: Signing

Lencana “Verified”

[!IMPORTANT] Di era pembuatan kode AI, Identitas adalah segalanya. Sebuah commit harus terbukti secara kriptografi berasal dari Anda.

• Syarat: Semua commit wajib ditandatangani (Signed) via GPG atau SSH.
• GitHub: Upload Public Key GPG/SSH Anda ke pengaturan GitHub.

sequenceDiagram
    participant Dev as Developer
    participant Git as Local Git
    participant Key as GPG/SSH Key
    participant GH as GitHub
    
    Dev->>Git: git commit -S -m "feat:..."
    Git->>Key: Request Signature
    Key-->>Git: Signed Hash
    Git->>GH: git push
    GH->>GH: Verify Public Key
    GH-->>Dev: Badge "Verified" ✅

• Verifikasi: Jalankan git log --show-signature untuk memeriksa kepercayaan lokal.

[!TIP] Mengapa ribet begini? Lihat Bukti Pemikiran (Proof of Thought). Tanda tangan kriptografi adalah satu-satunya bukti bahwa Logic Trace ini milik Anda, bukan hasil copy-paste anonim.

4. Otomasi: Pre-commit Hooks

Jangan mengandalkan ingatan. Gunakan Framework pre-commit untuk menegakkan standar secara otomatis.

• Linting: Blokir commit dengan Syntax Error.
• Formatting: Auto-format (Prettier/Black/Rustfmt) sebelum commit masuk.
• Secrets: Deteksi ketidaksengajaan commit Private Key.

5. Verifikasi: Integritas Dokumentasi

Sebelum melakukan push, pastikan model visual dan matematis Anda terformat dengan benar untuk rendering.

• Validator: Gunakan perintah py scripts/validate_docs.py untuk mengaudit semua file markdown terhadap blok yang tidak tertutup atau diagram Mermaid yang malformat.
• Otomasi: Idealnya, integrasikan ini sebagai Pre-commit Hook untuk menjaga kualitas repositori.

6. Configuration Boilerplate

Rekomendasi .pre-commit-config.yaml

Letakkan ini di root repository Anda untuk mengotomatisasi kebersihan.

repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  # Keamanan: Deteksi Key/Secret
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.1
    hooks:
      - id: gitleaks

  # Identitas: Paksa Conventional Commits
  - repo: https://github.com/compilerla/conventional-pre-commit
    rev: v3.1.0
    hooks:
      - id: conventional-pre-commit
        stages: [commit-msg]

---

🏠 Home | 🗺️ Roadmap | 🤖 Protokol Agentik