Initial commit: nick docs
This commit is contained in:
moojttaba
219
07 - Development/Git Workflow.md
Normal file
219
07 - Development/Git Workflow.md
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
title: Git Workflow
|
||||
tags: [development]
|
||||
---
|
||||
|
||||
# Git Workflow
|
||||
|
||||
How code moves from a developer's laptop to production.
|
||||
|
||||
---
|
||||
|
||||
## 1. Repositories & branches
|
||||
|
||||
Both repos are hosted on the self-hosted Gitea instance at **`git.manko.yoga`** (SSH on **port 222**, HTTPS on 443).
|
||||
|
||||
| Repo | Path | Branches |
|
||||
|------|------|----------|
|
||||
| Backend | `ssh://git@git.manko.yoga:222/nick/backend.git` | `main`, `development`, `feature/*`, `fix/*` |
|
||||
| Frontend | `ssh://git@git.manko.yoga:222/nick/frontend.git` | `main`, `development`, `feature/*`, `fix/*` |
|
||||
|
||||
### Branch roles
|
||||
|
||||
| Branch | Role | Auto-deploy |
|
||||
|--------|------|-------------|
|
||||
| `main` (or `master`) | **Production.** Always deployable. | Yes — Gitea Actions builds + pushes `:latest`, Watchtower then pulls it. See [[CI-CD Pipeline]] and [[Deployment]]. |
|
||||
| `development` | **Active dev.** Integration branch where features land before promotion. | Yes — builds + pushes `:dev` tag (not consumed by prod Watchtower). |
|
||||
| `feature/<short-slug>` | One change in flight. Branched from `development`. | No |
|
||||
| `fix/<short-slug>` | A bug fix. Branched from `development` (or `main` for a hotfix). | No |
|
||||
| `hotfix/<slug>` | Urgent production fix branched from `main`. | No until merged |
|
||||
|
||||
```
|
||||
main ─●────────●───────────────●───────► (prod, tagged v2.6.x)
|
||||
▲ release merge
|
||||
development ─●────●────●───●───●────●────●────●──► │
|
||||
▲ ▲ ▲ ▲ ▲ │
|
||||
│ │ │ │ │ │
|
||||
feature/* branches off development │
|
||||
hotfix/* ─────────────────────────────●──────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Day-to-day developer flow
|
||||
|
||||
```bash
|
||||
# 1. Sync development
|
||||
git checkout development
|
||||
git pull --rebase
|
||||
|
||||
# 2. Create a branch
|
||||
git checkout -b feature/add-seller-payouts
|
||||
|
||||
# 3. Hack
|
||||
# ...
|
||||
|
||||
# 4. Verify locally
|
||||
npm run lint && npm run typecheck && npm run test
|
||||
# or for frontend
|
||||
yarn lint && yarn test
|
||||
|
||||
# 5. Commit (Conventional Commits — see Coding Standards)
|
||||
git commit -m "feat(payment): add seller payout history view"
|
||||
|
||||
# 6. Push & open PR
|
||||
git push -u origin feature/add-seller-payouts
|
||||
```
|
||||
|
||||
Open the PR in Gitea against `development`. CI will run on the PR if you have workflows enabled.
|
||||
|
||||
> [!tip] Use the `.gitmessage` template (`git config commit.template .gitmessage`) — it pre-fills the conventional-commit format with hints.
|
||||
|
||||
---
|
||||
|
||||
## 3. Commit message convention
|
||||
|
||||
Enforced on the frontend by `frontend/.commitlintrc.json` (and followed by convention on backend). See [[Coding Standards#commit-conventions]] for the full rules and examples.
|
||||
|
||||
Quick reference:
|
||||
|
||||
```
|
||||
type(scope): subject
|
||||
|
||||
feat: add user authentication
|
||||
fix(payment): handle missing tx hash
|
||||
docs: clarify env vars table
|
||||
chore: bump dependencies
|
||||
feat!: redesign API endpoints # breaking change
|
||||
```
|
||||
|
||||
Append `[skip-version]` to skip the auto-version bump when releasing.
|
||||
|
||||
---
|
||||
|
||||
## 4. PR review process
|
||||
|
||||
1. Open the PR with a description that covers **what**, **why**, and **how to test**.
|
||||
2. Link to the related ticket / issue.
|
||||
3. CI must be green (build, lint, tests where wired up).
|
||||
4. **At least one reviewer** approves.
|
||||
5. Squash-merge into `development` with a clean conventional-commit message.
|
||||
6. Delete the source branch.
|
||||
|
||||
Reviewers check against [[Coding Standards#pr-review-checklist]].
|
||||
|
||||
> [!warning] Do **not** force-push to a PR branch after review starts — it invalidates review history. Use additional commits and let the squash-merge tidy up.
|
||||
|
||||
---
|
||||
|
||||
## 5. Releasing to production
|
||||
|
||||
The release path is `development → main → registry → production`.
|
||||
|
||||
```bash
|
||||
# On a clean development that's ready to ship:
|
||||
git checkout development
|
||||
git pull --rebase
|
||||
|
||||
# Run AI-assisted version bump (chooses major/minor/patch from commit messages)
|
||||
npm run smart-release
|
||||
# This: bumps package.json, commits "chore: bump version to vX.Y.Z",
|
||||
# creates a `vX.Y.Z` tag, and pushes commits + tags.
|
||||
|
||||
# Promote to main
|
||||
git checkout main
|
||||
git pull --rebase
|
||||
git merge --ff-only development # fast-forward only — no merge commit
|
||||
git push
|
||||
```
|
||||
|
||||
What happens next:
|
||||
|
||||
- Pushing to `main` triggers the `docker-build-no-cache.yml` workflow on the backend (and `deploy.yml` on the frontend) — see [[CI-CD Pipeline]].
|
||||
- That workflow builds the image and pushes both `:<version>` and `:latest` to `git.manko.yoga/manawenuz/escrow-backend`.
|
||||
- **Watchtower** on the production host (see [[Deployment]]) polls the registry every interval, detects the new `:latest`, and rolls the production container.
|
||||
|
||||
### Manual builds
|
||||
|
||||
If you want to push a specific version without going through main, use:
|
||||
|
||||
```bash
|
||||
# Backend
|
||||
npm run release:patch # commits + tags + pushes; CI handles the rest
|
||||
./scripts/build-and-push.sh # build locally and push dev tag
|
||||
|
||||
# Frontend
|
||||
./scripts/deploy.sh # local build + push :latest
|
||||
```
|
||||
|
||||
See [[Scripts]] for details.
|
||||
|
||||
---
|
||||
|
||||
## 6. Versioning
|
||||
|
||||
Semantic versioning, automated where possible.
|
||||
|
||||
- `package.json` `version` is the source of truth.
|
||||
- The AI version scripts (`backend/scripts/ai-enhanced.sh`, `frontend/scripts/ai-enhanced.sh`) classify the last commit:
|
||||
- `feat:` → minor
|
||||
- `fix:` → patch
|
||||
- `feat!:` or `BREAKING CHANGE:` → major
|
||||
- `docs:`/`chore:`/`[skip-version]` → skip
|
||||
- `auto-version.sh` applies the bump, commits, tags `v<version>`, and (with the npm wrappers) pushes.
|
||||
|
||||
Confidence levels (`high`/`medium`/`low`/`very-low`) gate the action — low confidence asks for a manual decision rather than auto-applying.
|
||||
|
||||
The CI workflows tag built images with both the `package.json` version and the moving tag (`:latest` for main, `:dev` for development).
|
||||
|
||||
---
|
||||
|
||||
## 7. Hotfix flow
|
||||
|
||||
```bash
|
||||
# Branch from main
|
||||
git checkout main && git pull --rebase
|
||||
git checkout -b hotfix/critical-payment-bug
|
||||
|
||||
# Fix, test, commit
|
||||
git commit -m "fix(payment): correct rounding on payout amount"
|
||||
|
||||
# Push + PR into main
|
||||
git push -u origin hotfix/critical-payment-bug
|
||||
# (open PR targeted at main; merge after review)
|
||||
|
||||
# After merge, port the fix back to development:
|
||||
git checkout development && git pull --rebase
|
||||
git merge --no-ff main
|
||||
git push
|
||||
```
|
||||
|
||||
Bump the patch version on `main` before merging so the new image gets a real tag, not just `:latest`.
|
||||
|
||||
---
|
||||
|
||||
## 8. SSH access on port 222
|
||||
|
||||
Gitea SSH listens on **222**, not 22, so the URL is always `ssh://git@git.manko.yoga:222/...`. Add this once to `~/.ssh/config`:
|
||||
|
||||
```ssh
|
||||
Host git.manko.yoga
|
||||
HostName git.manko.yoga
|
||||
Port 222
|
||||
User git
|
||||
IdentityFile ~/.ssh/id_ed25519
|
||||
```
|
||||
|
||||
Then `git clone git@git.manko.yoga:nick/backend.git` "just works" without the explicit `:222`.
|
||||
|
||||
Container registry uses standard ports — `git.manko.yoga/manawenuz/escrow-backend:latest` over HTTPS — authenticated by a personal access token (`GITEATOKEN` secret in CI).
|
||||
|
||||
---
|
||||
|
||||
## 9. Rules of thumb
|
||||
|
||||
> [!tip] Keep PRs small. Anything > 500 LOC of net change is a candidate for splitting.
|
||||
|
||||
> [!warning] Never commit `.env*` files containing real secrets. The repos do already have committed `.env.development` / `.env.production` with **public** values — if you add a real secret, treat it as leaked and rotate.
|
||||
|
||||
> [!warning] Never force-push `main` or `development`. If you absolutely must rewrite history, coordinate with the team and re-tag the affected versions.
|
||||
Reference in New Issue
Block a user