From 90016254a9281b88d2d999aa094758f3dc9b3b53 Mon Sep 17 00:00:00 2001 From: DustyWalker Date: Mon, 4 Aug 2025 21:09:31 +0200 Subject: [PATCH] 23 --- plan-for-devs.md | 115 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 105 insertions(+), 10 deletions(-) diff --git a/plan-for-devs.md b/plan-for-devs.md index c328a3b..b7ea38a 100644 --- a/plan-for-devs.md +++ b/plan-for-devs.md @@ -1,3 +1,108 @@ +Below is a pragmatic branching & workflow recipe that fits a **3-developer team on Forgejo**, keeps *main* stable, and bakes security into every merge. + +--- + +## Key take-away (one-paragraph summary) + +For a small, fast-moving team the safest and simplest approach is **trunk-based development**: protect a single *main* branch, work in short-lived feature/bug-fix branches, gate every merge through mandatory reviews, signed commits, and a Forgejo Actions CI pipeline. Branch protection rules in Forgejo stop direct pushes, require 1-2 approvals, verified signatures, and green status checks, while team-level permissions ensure only reviewers (not all contributors) can override rules. This set-up gives you continuous delivery speed without the complexity of full GitFlow, yet still allows optional *release/*\*\* or *hotfix/*\*\* branches when you tag production versions. + +--- + +## 1. Choose a lightweight trunk-based flow + +* **Why trunk-based?** Comparative studies show it reduces merge debt and is easier to automate than GitFlow for small teams that deploy often. ([Assembla][1], [Graphite.dev][2]) +* **Branch lifetime:** create a branch per ticket, keep it under a few days, merge when CI passes. Long-running “develop” branches are unnecessary overhead here. ([Assembla][1]) + +--- + +## 2. Default branches & naming conventions + +| Purpose | Pattern | Notes | +| -------------------------- | ----------------------------- | --------------------------------------- | +| Production/trunk | **main** | Always deployable. | +| Working branches | **feature/\***, **bugfix/\*** | One per task. | +| Stable releases (optional) | **release/**\* | e.g. `release/2025-08-beta`. | +| Emergency fixes | **hotfix/\*** | Branched from *main*, merged back fast. | + +Clear prefixes make it obvious what can be safely deleted after merge and align with widely-used conventions. ([Medium][3], [Graphite.dev][4]) + +--- + +## 3. Protect *main* (and *release/*\*\*) branches + +* **Enable branch protection**: go to **Settings → Branches → Add rule** in Forgejo and apply to `main` and `release/**`. ([forgejo.org][5]) +* **Checks to require** + + 1. *Minimum approvals*: set to **2** so any code needs a peer review. ([docs.gitea.com][6], [GitHub Docs][7]) + 2. *Status checks*: gate merge on “ci/forgejo-actions” passing. ([forgejo.org][8]) + 3. *Signed commits*: tick “reject unsigned” so only GPG- or SSH-signed commits reach trunk. ([Gitea][9], [Gitea][10]) + 4. *Force-push & branch deletion*: disable both for protected branches to retain history. ([GitHub Docs][11]) +* **Linear history (optional)**: require “rebase-merge” to avoid merge bubbles if you prefer a tidy log. ([forgejo.org][5]) + +--- + +## 4. CI gates with Forgejo Actions + +1. **Runner**: add a `forgejo-runner` container; it spins up each job in Docker for parity with prod. ([forgejo.org][12]) +2. **Workflow file** (`.forgejo/workflows/ci.yml`): + + * lint → test → build → (optionally) Docker image scan. + * upload artifacts so reviewers can download a built ZIP. +3. **Status check**: Forgejo automatically publishes a context (e.g. `ci/forgejo-actions`); make this required in branch protection. ([forgejo.org][8]) + +--- + +## 5. Repository permissions & secret management + +* **Teams & roles**: give “Write” to developers and “Admin” only to one maintainer account; review-only roles can still approve PRs. ([forgejo.org][13]) +* **Secrets**: store test API keys in Forgejo’s encrypted Secrets UI; runners inject them at runtime so they never enter Git history. ([forgejo.org][14]) + +--- + +## 6. Merge policy & code review hygiene + +* **Pull Request template**: checklist for tests, docs, threat modelling. +* **CODEOWNERS**: although Forgejo doesn’t yet enforce mandatory owner approval, it still auto-pings the right reviewer set. ([GitHub][15]) +* **Conversation resolution**: reviewers can block merge until all comments are addressed (mirrors GitHub’s “require conversation resolution”). ([GitHub Docs][7]) + +--- + +## 7. Day-to-day workflow (example) + +1. `git switch -c feature/login-rate-limit` +2. Code & commit with `-S` to sign. +3. Push and open PR; CI runs automatically. +4. Two devs review; one fixes comments; CI re-runs. +5. Merge via “Rebase & Merge” button; branch auto-deleted. +6. CI (on *main*) builds & pushes image to registry; CD pipeline (outside Forgejo) deploys staging. + +--- + +## 8. Extra safety nets + +* **Draft PRs** for work-in-progress so CI still runs but can’t merge. +* **Feature flags** in code to dark-deploy risky features. +* **Dependabot/Gitea Mirror** for automated security updates (make those branches exempt from approval but still require CI). +* **Nightly end-to-end run** on *main* to catch hidden regressions. + +--- + +### Final checklist + +| Guardrail | Enabled? | +| --------------------------------- | -------- | +| Protected *main* & *release/*\*\* | ✅ | +| Required CI status | ✅ | +| 2 reviewer approvals | ✅ | +| Signed commit verification | ✅ | +| No force-push / deletions | ✅ | +| Secrets in Forgejo vault | ✅ | + +Follow this structure and you’ll have a **secure, review-driven workflow** that lets all three developers move quickly without breaking production. + + + + **Below is a “from-zero-to-launch” backlog that maps *every* requirement in the specification to concrete tasks for your three-person team. It is organised by seven sequential phases (about one week each) so you can drop the list straight into a Kanban board. After the backlog you’ll find a compact milestone calendar. Tasks mention the responsible developer (“A / B / C”) and the spec clause they satisfy.** --- @@ -101,13 +206,3 @@ *Each numbered requirement in the specification (10-90) is matched to at least one backlog item above, ensuring nothing is missed.* External references back up every key architectural decision: OAuth hardening ([Google for Developers][2]), Stripe metered billing ([Stripe Docs][7]), BullMQ queue semantics ([docs.bullmq.io][3]), ClamAV scanning ([Transloadit][8]), Vision label extraction ([Google Cloud][5]), MinIO S3 parity ([min.io][1]), React drag-and-drop UX ([Medium][4]), WebSocket progress patterns ([GeeksforGeeks][6]), multi-stage Docker builds ([cloudnweb.dev][10]), and Redis rate-limiting ([webdock.io][9]). Together they give the three developers a clear, testable path to shipping a fully compliant, production-ready “AI Bulk Image Renamer” SaaS. -[1]: https://min.io/product/s3-compatibility?utm_source=chatgpt.com "AWS S3 Compatible Object Storage" -[2]: https://developers.google.com/identity/protocols/oauth2/resources/best-practices?utm_source=chatgpt.com "Best Practices | Authorization Resources" -[3]: https://docs.bullmq.io/?utm_source=chatgpt.com "What is BullMQ | BullMQ" -[4]: https://medium.com/%40dprincecoder/creating-a-drag-and-drop-file-upload-component-in-react-a-step-by-step-guide-4d93b6cc21e0?utm_source=chatgpt.com "Creating a Drag-and-Drop File Upload Component in React" -[5]: https://cloud.google.com/vision/docs/labels?utm_source=chatgpt.com "Detect Labels | Cloud Vision API" -[6]: https://www.geeksforgeeks.org/reactjs/real-time-updates-with-websockets-and-react-hooks/?utm_source=chatgpt.com "Real-time Updates with WebSockets and React Hooks" -[7]: https://docs.stripe.com/billing/subscriptions/usage-based/recording-usage-api?utm_source=chatgpt.com "Record usage for billing with the API" -[8]: https://transloadit.com/devtips/implementing-server-side-malware-scanning-with-clamav-in-node-js/?utm_source=chatgpt.com "Implementing server-side malware scanning with ClamAV ..." -[9]: https://webdock.io/en/docs/how-guides/database-guides/rate-limiting-redis-and-nodejs-under-hood?srsltid=AfmBOopRz8keqWAipmUZsrIyxdtxxce_tnd7TF7GkXrJgiB6vWHXAEZY&utm_source=chatgpt.com "Rate Limiting with Redis and Node.js: Under the Hood" -[10]: https://www.cloudnweb.dev/2019/10/crafting-multi-stage-builds-with-docker-in-node-js/?utm_source=chatgpt.com "Crafting multi-stage builds with Docker in Node.js - DEV Community"