feature/* ─┐
           ├──→ develop ──→ release/* ──→ main ──→ [tag v1.x.x]
bugfix/*  ─┘                                ↑
                                     hotfix/* ──→ develop

git init
git commit --allow-empty -m "chore: initial commit"
git branch -M main
git remote add origin https://github.com/user/repo.git
git push -u origin main

git checkout -b develop
git push -u origin develop

git checkout develop
git pull --rebase origin develop        # dùng rebase, không tạo merge commit rác
git checkout -b feature/ten-tinh-nang

# ... code ...
git add -p                              # add từng hunk, không add cả file blind
git commit -m "feat(module): mô tả ngắn"
git push origin feature/ten-tinh-nang

git checkout develop && git pull --rebase origin develop
git branch -d feature/ten-tinh-nang
git push origin --delete feature/ten-tinh-nang

git checkout develop && git pull --rebase origin develop
git checkout -b release/v1.2.0

# Chỉnh CHANGELOG, bump version trong pyproject.toml / package.json
git commit -m "chore: bump version to 1.2.0"
git push origin release/v1.2.0

# Sau review:
git checkout main && git merge --no-ff release/v1.2.0
git tag -a v1.2.0 -m "Release v1.2.0"
git push origin main --tags

git checkout develop && git merge --no-ff release/v1.2.0
git push origin develop

git branch -d release/v1.2.0
git push origin --delete release/v1.2.0

git checkout main && git pull origin main
git checkout -b hotfix/fix-crash-login

# ... sửa lỗi ...
git commit -m "fix: null pointer khi user chưa xác thực"
git push origin hotfix/fix-crash-login

git checkout main && git merge --no-ff hotfix/fix-crash-login
git tag -a v1.2.1 -m "Hotfix v1.2.1"
git push origin main --tags

git checkout develop && git merge --no-ff hotfix/fix-crash-login
git push origin develop

git branch -d hotfix/fix-crash-login
git push origin --delete hotfix/fix-crash-login

# Quy trình rebase chuẩn trước khi tạo PR
git checkout develop && git pull --rebase origin develop
git checkout feature/ten-tinh-nang
git rebase develop
# Xử lý conflict từng commit một
git push --force-with-lease origin feature/ten-tinh-nang   # KHÔNG dùng --force

# Lưu tạm khi cần nhảy nhánh giữa chừng
git stash push -m "wip: đang làm auth module"
git stash list
git stash pop                          # hoặc git stash apply stash@{0}

# Lấy 1 commit cụ thể từ nhánh khác
git cherry-pick <commit-hash>
git cherry-pick A..B                   # range từ A+1 đến B

# Dọn dẹp commit trước khi PR
git rebase -i HEAD~4
# squash / fixup / reword / drop từng commit

# Xem lịch sử dạng graph
git log --oneline --graph --all

# So sánh nhánh
git diff develop...feature/ten-tinh-nang

# Ký commit với GPG (nhiều org bắt buộc)
git config --global commit.gpgsign true
git commit -S -m "feat: signed commit"

.github/
├── CODEOWNERS                    # auto-assign reviewer đúng người
├── pull_request_template.md      # template PR
├── ISSUE_TEMPLATE/
│   ├── bug_report.md
│   └── feature_request.md
└── workflows/
    ├── ci.yml
    └── cd.yml

# Security-related files → chỉ team security mới approve được
src/crypto/      @org/security-team
*.yml            @org/devops-team
docs/            @org/tech-lead

## Mô tả thay đổi
<!-- Tóm tắt ngắn -->

## Loại thay đổi
- [ ] feat  - [ ] fix  - [ ] refactor  - [ ] docs  - [ ] chore

## Checklist
- [ ] Đã tự review code của mình
- [ ] Đã viết/cập nhật test
- [ ] Không có secret/credential trong code
- [ ] Đã cập nhật docs nếu cần

feat(api)!: đổi response format của /users endpoint

pip install pre-commit

repos:
  # --- Format & Lint ---
  - repo: https://github.com/psf/black
    rev: 23.12.0
    hooks:
      - id: black

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.9
    hooks:
      - id: ruff
        args: [--fix]

  # --- Security: chặn secret bị commit ---
  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.18.1
    hooks:
      - id: gitleaks

  # --- C++ (nếu dùng) ---
  - repo: https://github.com/pre-commit/mirrors-clang-format
    rev: v17.0.6
    hooks:
      - id: clang-format
        types_or: [c, c++]

  # --- Chung ---
  - 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-merge-conflict
      - id: detect-private-key          # chặn private key
      - id: check-added-large-files     # chặn file > 500KB
        args: ['--maxkb=500']

pre-commit install          # cài hook vào .git/hooks
pre-commit run --all-files  # chạy thủ công toàn bộ

# Cài (cần Docker)
brew install act          # macOS
# hoặc: curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

# Dùng
act                                      # chạy tất cả push triggers
act pull_request                         # simulate PR event
act -j lint                              # chỉ chạy job "lint"
act -W .github/workflows/ci.yml          # chỉ chạy file cụ thể
act --dryrun                             # xem sẽ chạy gì, không thực thi
act --verbose                            # log chi tiết

-P ubuntu-latest=catthehacker/ubuntu:act-latest
--secret-file .secrets

GITHUB_TOKEN=ghp_xxx
CODECOV_TOKEN=xxx
SONAR_TOKEN=xxx

name: CI

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

jobs:
  # ── Job 1: Nhanh, fail early ──────────────────────────────
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: pip
      - run: pip install black ruff mypy bandit
      - run: black --check src/
      - run: ruff check src/
      - run: mypy src/
      - run: bandit -r src/ -ll -x tests/   # SAST cơ bản

  # ── Job 2: Test (matrix) ─────────────────────────────────
  test:
    needs: lint
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ['3.10', '3.11', '3.12']
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
          cache: pip
      - run: pip install -r requirements.txt -r requirements-dev.txt
      - run: pytest tests/ -v --cov=src --cov-report=xml --cov-fail-under=75
      - uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  # ── Job 3: Security scan ──────────────────────────────────
  security:
    needs: lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # cần full history cho secret scan

      - name: Audit dependencies
        run: |
          pip install pip-audit
          pip-audit -r requirements.txt --fail-on-vuln

      - name: Scan secrets (full history)
        uses: trufflesecurity/trufflehog@main
        with:
          path: ./
          base: ${{ github.event.repository.default_branch }}

      - name: Container scan (nếu có Dockerfile)
        uses: aquasecurity/trivy-action@master
        with:
          scan-type: fs
          severity: CRITICAL,HIGH
          exit-code: 1

  # ── Job 4: SAST nâng cao (SonarCloud) ────────────────────
  sonar:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: SonarSource/sonarcloud-github-action@master
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}

name: CD

on:
  push:
    tags: ['v*.*.*']

jobs:
  release:
    runs-on: ubuntu-latest
    permissions:
      contents: write         # cần để tạo GitHub Release

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Build artifact
      - name: Build
        run: |
          pip install build
          python -m build

      # Tự động generate CHANGELOG từ conventional commits
      - name: Generate changelog
        id: changelog
        uses: orhun/git-cliff-action@v3
        with:
          config: cliff.toml
          args: --latest

      # Tạo GitHub Release với changelog
      - name: Create Release
        uses: softprops/action-gh-release@v1
        with:
          body: ${{ steps.changelog.outputs.content }}
          files: dist/*
          draft: false
          prerelease: ${{ contains(github.ref, 'rc') || contains(github.ref, 'beta') }}

# .github/workflows/release-please.yml
name: Release Please

on:
  push:
    branches: [main]

jobs:
  release-please:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        with:
          release-type: python        # hoặc node, go, ...
          package-name: my-package

Môi trường DEV   → .env (local only, gitignored)
Môi trường CI    → GitHub Secrets / GitLab CI Variables
Môi trường PROD  → HashiCorp Vault / AWS Secrets Manager / GCP Secret Manager

# Workflow kiểm tra secret sắp hết hạn
- name: Check token expiry
  run: |
    expiry=$(curl -H "Authorization: token ${{ secrets.MY_TOKEN }}" \
      https://api.github.com/rate_limit | jq '.rate.reset')
    echo "Token reset: $expiry"

          /\
         /E2E\          ← ít nhất, chạy chậm, dễ vỡ
        /──────\
       /Integration\    ← test boundary: DB, API, filesystem
      /──────────────\
     /   Unit Tests   \ ← nhiều nhất, nhanh, isolated
    /──────────────────\

# conftest.py
import pytest

@pytest.fixture(scope='session')
def db():
    engine = create_engine('sqlite:///:memory:')
    Base.metadata.create_all(engine)
    yield engine
    Base.metadata.drop_all(engine)

@pytest.fixture(autouse=True)
def reset_db(db):
    # Clean state mỗi test, không leak giữa các test
    with db.connect() as conn:
        for table in reversed(Base.metadata.sorted_tables):
            conn.execute(table.delete())
        conn.commit()

# Chạy test với output hữu ích
pytest -v --tb=short --cov=src --cov-report=term-missing

# Chỉ chạy test liên quan đến file đang sửa
pytest --lf              # last failed
pytest -x               # dừng ngay khi fail đầu tiên
pytest -k "test_auth"   # filter theo tên

# Dùng Atheris (Python fuzzer của Google)
pip install atheris

import atheris
import sys

@atheris.instrument_func
def TestOneInput(data):
    try:
        import pefile
        pefile.PE(data=data)
    except pefile.PEFormatError:
        pass  # Expected
    except Exception as e:
        # Unexpected exception = potential bug
        raise

atheris.Setup(sys.argv, TestOneInput)
atheris.Fuzz()

python fuzz_pe_parser.py -max_len=65536 corpus/

import structlog

log = structlog.get_logger()

# Gắn context theo request
log = log.bind(request_id="abc-123", user_id=42)

log.info("user_login", method="password", ip="1.2.3.4")
log.warning("rate_limit_exceeded", endpoint="/api/scan", count=100)
log.error("parse_failed", filename="malware.exe", error=str(e))

{"event": "user_login", "request_id": "abc-123", "user_id": 42, "method": "password", "level": "info", "timestamp": "2024-01-15T10:30:00Z"}

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

tracer = trace.get_tracer(__name__)

def analyze_file(filepath):
    with tracer.start_as_current_span("analyze_file") as span:
        span.set_attribute("file.path", filepath)
        span.set_attribute("file.size", os.path.getsize(filepath))

        with tracer.start_as_current_span("extract_features"):
            features = extract_features(filepath)

        with tracer.start_as_current_span("ml_predict"):
            result = model.predict(features)

        span.set_attribute("prediction", result)
        return result

Branch: main
✅ Require pull request before merging
  ✅ Required approvals: 1 (hoặc 2 cho prod)
  ✅ Dismiss stale reviews when new commits pushed
  ✅ Require review from CODEOWNERS
✅ Require status checks to pass
  ✅ lint
  ✅ test
  ✅ security
✅ Require branches to be up to date
✅ Require signed commits        ← GPG
✅ Do not allow bypassing         ← kể cả admin

□ Khởi tạo repo với main + develop
□ Cấu hình branch protection (main + develop)
□ Thêm CODEOWNERS
□ Thêm PR template
□ Cài pre-commit (gitleaks + linter)
□ Viết .gitignore đúng (secrets, venv, build artifacts)
□ CI pipeline cơ bản (lint → test → security)
□ act test CI chạy local được
□ Secrets đặt trong GitHub Secrets, không trong code
□ Conventional commits từ commit đầu tiên
□ README: cách setup, cách chạy test, cách contribute