THiNK Playbook
Home / Docs

Version Control

Guidelines for Git and version control practices

Version Control Best Practices for the Tech Innovators Network (THiNK) Adapted from Git, GitHub, and VSCode workflows to streamline collaboration, ML projects, and code quality.

1. Introduction

Version control isn’t just about tracking changes—it’s the backbone of collaboration, especially when juggling ML models, websites, databases, and web apps. At THiNK, we use Git for version control, GitHub for collaboration, and VSCode to supercharge our workflow. Whether you’re training a model, deploying an app, or fixing a bug, these practices ensure your work is organized, traceable, and secure.

2. Git Workflow Basics

The THiNK Workflow

  1. Branch Like a Boss:

    • Work in feature branches (e.g., feat/rag-app-search or fix/model-deployment-bug).
    • Use descriptive names to clarify the branch’s purpose.

  2. Commit Early, Commit Often:

    • Make atomic commits—focus each commit on a single task (e.g., “Add training script for v2 model”).
    • Use commit prefixes to categorize changes (see examples below).

  3. Pull Requests (PRs):

    • Open a PR when your branch is ready for review.
    • Include testing instructions (e.g., “Run npm test to validate model accuracy”).

  4. Merge Strategically:

    • Merge PRs only after approval and CI/CD checks pass.
    • Keep the main branch deployable at all times.

3. Commit Prefixes

Why Prefixes Matter: Prefixes make commit histories readable and help filter changes by type (e.g., feat:, fix:). Here’s what we use at THiNK:

PrefixUse CaseExample
feat:New functionalityfeat: Add RAG query handler
fix:Bug fixesfix: Resolve model training timeout
model:ML model changesmodel: Train v3 of image classifier
deploy:Deployment updatesdeploy: Roll out rag-app to production
chore:Maintenance taskschore: Update VSCode extensions
docs:Documentation changesdocs: Add model training guide
test:Test additions/updatestest: Add unit tests for model inference

Pro Tip: Use git commit -m "feat: Add RAG query handler" to save time.

4. Branching Strategies

  • Feature Branches: Isolate work (e.g., feat/rag-app).
  • Hotfix Branches: Quick fixes for production (e.g., hotfix/critical-bug).
  • Release Branches: Prep for deployment (e.g., release/v1.0).

Avoid: Directly committing to main or prod branches.

5. VSCode + Git Power-Ups

  • Staging Changes: Use the VSCode Source Control panel to stage/unstage files.
  • Commit Templates: Configure VSCode to auto-suggest commit prefixes.
  • Pull Requests: Open PRs directly from the editor.
  • GitHub Actions: Trigger CI/CD pipelines (e.g., model testing, deployment) from VSCode.

Example VSCode Shortcut:

  • Stage all changes: Ctrl+Shift+A (Windows/Linux) or Cmd+Shift+A (Mac).
  • Commit: Ctrl+Shift+Enter (after typing the message).

6. ML-Specific Practices

  • Model Versioning: Tag trained models in commits (e.g., model: Train v3 - 92% accuracy).
  • Experiment Tracking: Use branches to isolate experiments (e.g., exp/rag-new-dataset).
  • Large Files: Store models/datasets in Git LFS (Large File Storage) to avoid bloating the repo.
  • CI/CD for ML: Automate model testing and deployment via GitHub Actions (e.g., “Run unit tests on push to feature branches”).

Example GitHub Action Snippet:

name: Model Testing  
on: [push]  
jobs:
  test:
    runs-on: ubuntu-latest  
    steps:
      - uses: actions/checkout@v4  
      - run: python test_model.py

7. Security & Best Practices

  • Branch Protection: Require PRs for main/prod branches.
  • Secrets Management: Use GitHub Secrets for API keys, not hard-coded values.
  • Code Scanning: Enable GitHub Advanced Security to catch vulnerabilities.
  • Access Control: Limit write access to critical branches (e.g., main).

Pro Tip: Run git log --graph --oneline to audit changes before merging.

8. Common Pitfalls to Avoid

  • Committing Non-Code Files: Use .gitignore to exclude logs, temp files, and model artifacts.
  • Ignoring CI Failures: Fix failing tests before merging.
  • Overloading Branches: Keep branches focused—don’t mix model training and UI fixes.

9. Conclusion

Version control at THiNK is about clarity, collaboration, and speed. By using Git prefixes, isolating work in branches, and leveraging VSCode/GitHub tools, we keep our projects organized and our team aligned—whether we’re deploying a web app or fine-tuning a model.

Real-Life Example: A developer trained a new model in a branch named model/v3-training. They committed with model: Train v3 - 92% accuracy and opened a PR. During review, a teammate spotted a data leakage issue. The fix took 1 hour—saving weeks of retraining.

Let’s keep our repos clean, our models sharp, and our workflows smooth! 🚀

Documentation

✏️ Edit this page