DEV TEAM OPERATION HANDBOOK

DEV TEAM OPERATION HANDBOOK

(Sổ tay tổ chức & vận hành đội phát triển phần mềm – bản dùng cho Wiki nội bộ / Markdown)

0. OUTLINE – KIẾN TRÚC TỔ CHỨC & CÔNG CỤ

0.1 Hệ sinh thái công cụ

• Jira / Issue Tracker: quản lý Bug / Feature / Task / Epic, Sprint, Roadmap.
• Git (GitHub): mã nguồn, Pull Request (PR), bảo vệ nhánh, CI/CD.
• Wiki (Confluence/Notion/GitLab Wiki): HLD/LLD, Release Notes, KB, Meeting notes.
• Chat (Teams): daily standup, thông báo release, phối hợp Dev–QA–Ops.
• CI/CD (GitHub Actions): build, test, security scan, deploy.
• Monitoring/Alerting: Sentry/Graylog/ELK + Prometheus/Grafana (log, APM, metric).

0.2 Liên kết giữa các công cụ

• Mỗi issue Jira bắt buộc có Issue Key và được gắn trong commit/PR ([#ISSUE-123]).
• PR phải liên kết Issue và HLD/LLD (nếu là feature/refactor).
• Pipeline CI gửi notification về kênh #dev-release và cập nhật trạng thái vào Issue (transition tự động khi pass).
• Release Notes mỗi version link danh sách PR/Issue đã merge và link tag.

1. TỔ CHỨC WORKSPACE

1.1 Jira / Boards / Workflow

• Boards:
  • Maintenance Board: Bug, Hotfix, Support.
  • Development Board: Feature, Refactor, Improvement.
• Issue types: Epic, Story/Feature, Task, Bug, Sub-task.
• Workflow chuẩn: To Do → In Progress → In Review → In Test → Ready to Deploy → Done.
• Trường bắt buộc: Assignee, Priority (P1/P2/P3), Estimate (SP/giờ), Labels (module), Sprint.

1.2 Wiki / Cấu trúc thư mục

/wiki
├─ roadmap/
├─ release_notes/
├─ design/
│  ├─ hld/
│  └─ lld/
├─ processes/
├─ retro/
└─ templates/

1.3 Channel giao tiếp (ví dụ Slack/Teams)

• #dev-daily: daily standup, blocker.
• #dev-general: trao đổi chung, thông báo.
• #dev-release: thông báo CI/CD, tag, downtime, rollback.
• #qa-channel: xác nhận test, ghi nhận bug.
• #dev-techup: nội dung đào tạo, tài liệu, lịch.

2. QUY TRÌNH CHUẨN ISSUE → DEPLOY (E2E)

3. CHECKLIST THEO GIAI ĐOẠN

3.1 Stage 1 – Tiếp nhận

• Mô tả rõ What/Why/Expected Outcome.
• Assignee, Priority (P1/P2/P3), Estimate (SP/giờ), Labels module.
• Acceptance Criteria (AC) rõ ràng.
• Bug: môi trường, steps to reproduce, expected vs actual, logs/screenshot.
• Feature: link HLD (bắt buộc), LLD nếu chạm DB/API.

3.2 Stage 2 – Design & Plan

• HLD/LLD cập nhật trong /wiki/design/.
• Phân tích rủi ro: dữ liệu, hiệu năng, bảo mật, tương thích ngược.
• Chia nhỏ thành sub-task nếu > 2–3 ngày.
• Gắn Sprint/Milestone, xác nhận effort & dependency.

3.3 Stage 3 – Development

• Tạo branch đúng format (feature/, bugfix/, hotfix/, refactor/).
• Commit message: [TYPE] short description (#ISSUE-ID).
• Không commit secret/.env/log/dump; .gitignore đầy đủ.
• Có unit test/fixture (khi áp dụng), script demo nếu cần.
• Update schema/API phải có migration và doc.

3.4 Stage 4 – Code Review

Reviewer kiểm tra:

• Đúng convention (PEP8/Odoo/ESLint), dễ đọc, tách hàm.
• Không duplicate logic, không magic number.
• Xử lý lỗi/exception đầy đủ, timeout/transaction.
• Truy vấn/IO tối ưu; không N+1; index phù hợp.
• Test/CI pass; PR ≤ 500 LOC (nếu lớn: đề nghị tách PR).
• Tài liệu cập nhật khi đổi hành vi.

3.5 Stage 5 – Testing (QA)

• Test case trong Jira/TestRail; mapping AC đầy đủ.
• Test trên staging với dữ liệu gần thực tế.
• Kiểm tra regression module liên quan.
• Gắn nhãn QA-PASS trước khi deploy.

3.6 Stage 6 – Deployment

• Merge develop → release/x.y; tag vX.Y.Z.
• CI/CD: build, unit/integration test, security scan pass.
• Maintenance window (20:00–22:00) + người trực Dev & QA.
• Post kết quả/rollback (nếu có) vào #dev-release.
• Cập nhật /wiki/release_notes/.

3.7 Stage 7 – Retrospective

• Thống kê bug post-release, MTTR, tỉ lệ pass pipeline.
• Review estimate vs thực tế, nguyên nhân chênh lệch.
• Chốt action items + owner + ETA; lưu /wiki/retro/.

4. QUẢN TRỊ MEETING & NGHI THỨC LÀM VIỆC

4.1 Lịch & nội dung chuẩn

4.2 Quy tắc tổ chức họp

• Bắt đầu đúng giờ, kết thúc đúng giờ; facilitator rõ ràng.
• Tất cả quyết định phải ghi log vào Wiki/Minutes & assign owner.
• Không họp nếu không có agenda; agenda phải gửi tối thiểu 2h trước.

5. CHIẾN LƯỢC BRANCH, PR, CI/CD

5.1 Branching

main (production – protected)
├─ release/x.y (stable for patch)
├─ develop (integration)
│  ├─ feature/<name>
│  ├─ bugfix/<issue-id>-<slug>
│  ├─ hotfix/<critical>
│  └─ refactor/<module>

Quy tắc:

• Chỉ PR mới được merge (cấm push trực tiếp main, release/*, develop).
• hotfix/* có thể từ main → PR vào main + develop (back-merge).

5.2 Commit & PR

• Commit: nhỏ, có ý nghĩa; [TYPE] msg (#ISSUE-ID) (TYPE: FEATURE/BUGFIX/REFACTOR/CHORE/DOCS).
• PR template bắt buộc (mô tả, ảnh hưởng, risk, checklist, test plan).
• Reviewers: ≥ 1 (PR > 500 LOC: ≥ 2). SLA phản hồi: 24h.

5.3 CI/CD Pipeline (tham chiếu)

1. Lint + Unit Test → 2) Build Image/Package → 3) Security Scan (SAST/Dependency) → 4) Integration Test → 5) Staging Deploy → 6) Manual Gate → 7) Prod Deploy khi tag.

6. CODE REVIEW POLICY (TIÊU CHÍ & CHẤM ĐIỂM)

6.1 Tiêu chí đánh giá

• Đúng: logic đúng, AC đạt, không phá backward compatibility.
• Sạch: convention, cấu trúc, tách lớp/service, log rõ ràng.
• Nhanh: truy vấn tối ưu, hạn chế round-trip, batch/bulk hợp lý.
• An toàn: input validation, permission check, secret handling, rate limit.
• Kiểm thử: có test/plan; QA có thể theo dõi và tái hiện.

6.2 Thang điểm gợi ý (0–2 điểm mỗi tiêu chí; tổng 10)

• 0: thiếu/không đạt; 1: chấp nhận được; 2: tốt.
• PR < 7 yêu cầu chỉnh sửa; ≥ 8 cho phép merge.

7. WORKLOAD, KPI & NĂNG LỰC

7.1 Quy tắc phân bổ

• Mỗi dev tối đa 2 issue song song; ưu tiên dứt điểm.
• Task > 3 ngày → chia nhỏ; cập nhật estimate khi thay đổi > 20%.

7.2 KPI đề xuất

• Velocity: Story points/sprint.
• Lead Time: Issue created → Done.
• PR Throughput: số PR/tuần; Review Time trung bình.
• Bug Ratio: (Bug post-release)/(Feature release).
• TechUp Contribution: số buổi host/bài KB/quý.

7.3 Năng lực & mentoring

• Ma trận năng lực: Domain (Odoo/Backend/Frontend/DevOps), Coding, Review, Testing, Communication.
• 1–1 hằng tháng: mục tiêu 3 tháng, kế hoạch học tập, shadowing/mentoring.

8. VAI TRÒ & RACI

(A: Accountable, R: Responsible, C: Consulted)

9. TEMPLATES (RAW MD)

9.1 Pull Request Template

## Description
[Feature/Bug/Refactor] …

## Related Issue
Fixes #ISSUE-ID

## Impact/Risk
- Module ảnh hưởng: …
- Migration: Có/Không (mô tả)

## Test Plan
- Case 1: …
- Case 2: …

## Checklist
- [ ] Đã test local
- [ ] Pass CI
- [ ] Cập nhật wiki/doc
- [ ] Không commit file rác/secret

9.2 Weekly Report Template

# Weekly Report – [Tên Dev] – Tuần [XX]
## Done
- [x] …
## In Progress
- [ ] …
## Blockers
- …
## Next Week Plan
- …

9.3 TechUp Note Template

# TechUp – [Ngày] – [Chủ đề]
**Host:** …
**Tóm tắt:** …
**Demo/Repo:** …
**Bài học:** …
**Tài liệu tham khảo:** …

10. PHỤ LỤC – CHECKLIST TỔNG HỢP THEO LOẠI TASK

10.1 BUG / HOTFIX

• Tiếp nhận: [ ] Steps to reproduce; [ ] Env; [ ] Logs; [ ] Priority P1/P2/P3.
• Dev: [ ] Branch bugfix/ hoặc hotfix/; [ ] Test local; [ ] PR liên kết issue.
• Review: [ ] RCA ngắn; [ ] Không ảnh hưởng chức năng khác; [ ] Pipeline pass.
• Test: [ ] QA regression; [ ] Tag QA-PASS.
• Deploy: [ ] Nếu P1: theo quy trình hotfix (cửa sổ khẩn).

10.2 FEATURE

• Tiếp nhận: [ ] AC; [ ] HLD; [ ] Estimate; [ ] Labels module.
• Dev: [ ] Branch feature/; [ ] Unit test (nếu có); [ ] Doc cập nhật.
• Review: [ ] Design alignment; [ ] Security/permission; [ ] Performance.
• Test: [ ] UAT trên staging với dữ liệu mẫu.
• Deploy: [ ] Tag version; [ ] Release note.

10.3 REFACTOR / IMPROVEMENT

• Tiếp nhận: [ ] Phạm vi; [ ] Chỉ số kỳ vọng (perf/memory/complexity).
• Dev: [ ] Benchmark trước/sau; [ ] Không đổi behavior (hoặc có doc).
• Review: [ ] Code smell giảm; [ ] Test coverage không giảm.
• Test: [ ] Regression lân cận; [ ] So sánh benchmark.

10.4 INFRA / MAINTENANCE

• Kế hoạch: [ ] Thời gian; [ ] Ảnh hưởng; [ ] Rollback plan.
• Thực thi: [ ] Script/IaC; [ ] Change log.
• Sau triển khai: [ ] Health check; [ ] Post-mortem nếu sự cố.

11. MEETING AGENDA – SUMMARY

• Daily: Yesterday/Today/Blocker (<= 60s/người). Cập nhật Jira trước họp.
• Planning: mục tiêu sprint, scope, estimate, risk, DoR/DoD, capacity, dependency.
• Review: demo; KPI sprint; quyết định release.
• Retro: keep/try/stop; 3 hành động ưu tiên + owner + ETA.
• TechUp: 1 chủ đề/tuần; slide + demo; KB sau buổi.

12. ĐỊNH NGHĨA – DoR & DoD

• Definition of Ready (DoR): Issue có mô tả + AC + estimate + assignee + tài liệu kèm.
• Definition of Done (DoD): Code + Review + Test pass + Doc/Release note + Deploy/Verify.

13. BẢO MẬT & TUÂN THỦ

• Không lưu secret trong repo; dùng Vault/CI variables.
• Log không chứa dữ liệu nhạy cảm; ẩn PII theo quy định.
• Bật branch protection, 2FA, review bắt buộc.
• Định kỳ security scan dependency & SAST.