.github/CONTRIBUTING.md

Contributing Guidelines

Welcome to the project! 🎉
We move fast, but we keep code quality and stability in check.

---

🏗️ Branching Model

• main → Always stable and demo-ready.
• dev → Integration branch.
• feature/ → Active development branches.

Flow:

1. Branch off dev for your work.
2. Open a Pull Request (PR) into dev.
3. Once dev is stable, it’s merged into main via a PR + review.

Example: main ← dev ← feature/email-agent

---

✅ Pull Request Rules

• All merges into main or dev require at least one approving review.
• Keep PRs small and focused (<300 lines if possible).
• Use clear titles and short descriptions (what + why).
• You can open draft PRs early for feedback.
• Squash merge when possible to keep history clean.

Naming Convention:

• feat: add Gmail OAuth flow
• fix: handle missing image extraction
• docs: update setup instructions

---

⚙️ Branch Protection

main

• Requires PR review before merging
• Requires status checks to pass (CI, tests, lint)
• Must be up-to-date with base before merging
• No direct commits or force pushes

dev

• Requires PR review before merging
• Requires at least 1 approval
• Conversations must be resolved
• Status checks optional (for fast iteration)
• No direct commits or force pushes
• Squash or rebase merges only (no merge commits)

---

🚀 Quick Workflow

1. git checkout dev
2. git pull
3. git checkout -b feature/my-new-feature
4. Make your changes.
5. Push & open a PR → base: dev
6. Request a review.
7. Merge when approved and tests pass.
8. Once stable, open a PR from dev → main.

---

🧹 Hygiene

• Delete merged branches.
• Use Conventional Commits for clarity.
• Keep main always deployable/demo-ready.
• If you break something, fix it fast 😉

---

💬 Reviews

• At least one reviewer per PR.
• Anyone can review — small teams move faster.
• Pair reviews encouraged for big changes.
• Minor changes (docs, comments) may be self-approved if trivial.

---

---

⚙️ Branch Protection Setup (GitHub Rulesets)

You can configure these under
➡️ Settings → Code and automation → Rulesets

Branch	Require PR	Required Approvals	Require Status Checks	Require Conversation Resolution	Allow Merge Commit	Force Push	Delete Branch
main	✅	1	✅	✅	❌	❌	❌
dev	✅	1	optional	✅	❌	❌	❌

---

Thanks for contributing — keep it fast, clean, and collaborative! 🚀