02 — Git, branches, and pull requests¶

How code gets from your laptop to production.

1. The branch model (every repo)¶

   feature-branch
        │
        │  PR + review
        ▼
   ┌─────────────┐
   │   dev_*     │   ← integration / CI deploys here automatically
   └─────┬───────┘
         │  merge (QA gate)
         ▼
   ┌─────────────┐
   │   uat_*     │   ← QA / customer success verifies here
   └─────┬───────┘
         │  merge (release)
         ▼
   ┌─────────────┐
   │    main     │   ← production
   └─────────────┘

The three long-lived branches are dev_*, uat_*, and main. You do not commit to any of them directly. You commit to a feature branch and open a pull request into dev_*.

Per-repo branch names¶

Repo	dev	uat	prod
`someli-api`	`dev_api`	`uat_api`	`main`
`someli-platform`	`dev_app`	`uat_app`	`main`
`Someli-Designer`	`dev_des_app`	`uat_des_app`	`main`
`designer-api`	`dev`	`uat`	`main`
`Someli-admin-api`	`dev`	`uat`	`main`
`admin_console_R`	`dev`	`uat`	`main`

Verify with the team which branch is the current target. The repos with dev_api / dev_app / dev_des_app are special — don't guess.

2. A typical feature workflow¶

You've been assigned, say, "add a 'Send test email' button to the customer-app account settings page". This will touch someli-platform and probably also someli-api. Treat the two repos as independent — one feature branch per repo, one PR per repo, both ideally merged together.

Step-by-step¶

cd ~/src/someli/someli-platform
git fetch origin
git checkout dev_app
git pull origin dev_app                  # update local dev_app
git checkout -b feature/send-test-email  # branch off dev_app
# ... edit code, commit ...
git push -u origin feature/send-test-email
# Open PR on GitHub: feature/send-test-email  →  dev_app

Do the same in the BE repo:

cd ~/src/someli/someli-api
git fetch origin
git checkout dev_api
git pull origin dev_api
git checkout -b feature/send-test-email
# ... edit code, commit ...
git push -u origin feature/send-test-email
# Open PR on GitHub: feature/send-test-email  →  dev_api

Branch naming¶

The team's convention is informal. Common patterns:

feature/<short-description>
fix/<short-description>
<jira-or-issue-id>/<short-description>

Verify with the team if there is a stricter convention. When in doubt, use feature/... or fix/... and link the issue ID in the PR description.

Commit messages¶

The team does not enforce Conventional Commits. Look at the recent git log of the branch you're targeting and match the style. Default to imperative-mood, present-tense ("Add test-email button", not "Added" or "Adds").

3. Pull requests¶

Where to open the PR¶

Always in the canonical repo on GitHub (github.com/Someli-ai/<repo>), targeting the dev_* branch for that repo. Not main. Not uat_*.

What a good PR looks like¶

Title: short, imperative. "Add 'Send test email' button to account settings."
Description: what changed, why, links to ticket/issue.
Screenshots for any UI change. (For the customer-app and designer, two screenshots: before and after.)
Manual test steps the reviewer can copy-paste to reproduce.
Schema changes: call them out at the top of the description. Schema changes need DBA / lead sign-off — they don't have a framework, they get applied by hand.

Reviewers¶

Verify with the team who owns each repo and should be the default reviewer. Typically there's one senior engineer per product pair. Add them as a reviewer on every PR.

CI / status checks¶

someli-api has both Jenkins (the operational one) and GitHub Actions. The GHA check will run on the PR and must pass.
someli-platform has Jenkins only — there is no GitHub Actions check on the PR. Verify locally before pushing.
The other repos (designer-api, Someli-Designer, Someli-admin-api, admin_console_R, someli-dashboard-be) have no in-repo CI at all. There's no automated check on the PR; deploys are run by processes outside the repo.

Consequence for you: in the four repos with no CI, you are the CI. Run the dev server, hit the changed code path, and confirm it works before requesting review. "It builds" is not a quality bar.

4. Snapshot repos — DO NOT COMMIT¶

There are three repos that look like product repos but are read-only snapshots:

someli-dashboard-be — a drifting fork of someli-api/dashboard/; the in-process copy inside someli-api is what runs in production. Edits here have no effect on production.
someli-mono-repo — an aggregated snapshot of someli-api + someli-platform. Decays over time.
someli-project — an aggregated snapshot of all six product repos. Decays over time.

Rule: never commit to these three. If you accidentally branch from one of them, your work is invisible to production and will be silently overwritten on the next snapshot refresh.

Always sanity-check before committing:

git remote -v   # confirm the remote is github.com/Someli-ai/<actual-product-repo>

The mono/project snapshots have remotes like …someli-mono-repo.git or …someli-project.git. If you see that, you're in the wrong directory — cd to the canonical product repo and try again.

5. Cross-repo changes¶

A surprising number of changes touch two or three repos at once. The platform has no monorepo / multi-repo tooling, so you have to coordinate by hand.

Typical pairs¶

Customer feature → someli-platform + someli-api
Designer feature → Someli-Designer + designer-api
Admin feature → admin_console_R + Someli-admin-api
Schema change → potentially all four backends, because they share the database

How to coordinate¶

Open the BE PR first. Get it reviewed. Don't merge yet.
Open the FE PR pointing at the BE preview/dev environment. Get it reviewed.
Merge BE first (into dev_api etc.), wait for the dev deploy.
Merge FE second.

This sequence avoids a window where the FE expects an endpoint that doesn't exist yet.

Shared-helper file changes¶

If you change helper/aiLogics.js in someli-api, decide whether the same change is needed in Someli-admin-api/helper/aiLogics.js (these have drifted but the files exist in both). See ../audit/CODE-OVERLAP-MATRIX.md.

The same applies to: - helper/tokenGenerator.js, helper/revokeToken.js, helper/ragProcess.js, helper/webScraping.js — currently byte-identical between someli-api and Someli-admin-api. If you edit one, edit the other in the same PR pair. - helper/helper.js, helper/constants.js, helper/basic.js, helper/index.js, helper/stockImage.js — drifted; manual reconciliation needed.

6. Hotfixes to production¶

If something is on fire in production and you cannot wait for the dev → uat → main path:

Branch from main: git checkout -b hotfix/<description> main.
Make the smallest possible change.
PR into main. Get emergency review.
Cherry-pick or back-merge the same change into dev_* and uat_* so the next release doesn't regress it.

Verify with the team what the hotfix policy actually is. Some teams require hotfixes to still go through uat_*; others allow direct main PRs with an extra reviewer.

7. Things that are easy to get wrong¶

Pitfall	Why it bites you	Fix
Branching from `main` instead of `dev_*`	Your PR will diff against unreleased dev work	Always `git checkout dev_X && git pull` before branching
Committing to a snapshot repo	Work is silently lost	`git remote -v` before committing
Pushing schema changes without telling anyone	Breaks another team's job at 2 AM	Mention schema in the PR; ping the team channel
Editing `someli-api/helper/X.js` and forgetting `Someli-admin-api/helper/X.js`	Bug fixed in one place, still present in the other	Check `../audit/CODE-OVERLAP-MATRIX.md` for any shared-lineage file
Editing the customer Polotno editor and assuming the designer one was updated too	Same bug appears in the other product six weeks later	Edits to one Polotno editor must be ported by hand
Merging FE before BE	Customers see a broken feature for the gap between deploys	Merge BE first, wait for deploy, then FE
Pushing a feature branch from the wrong product repo directory	You commit FE changes to the BE repo	Always `pwd` and `git remote -v` before push

8. Commands worth memorising¶

# Where am I?
pwd
git remote -v
git status -sb

# Stay current
git fetch origin
git checkout dev_X && git pull origin dev_X

# Start a feature
git checkout -b feature/<short-name>

# Push and open a PR
git push -u origin feature/<short-name>
# Then go to github.com/Someli-ai/<repo>/compare/dev_X...feature/<short-name>

# When the team asks "what changed?"
git log --oneline dev_X..HEAD
git diff dev_X..HEAD -- <path>

# Update your branch with new dev work (preferred: rebase, only if you're alone on the branch)
git fetch origin
git rebase origin/dev_X
# If others are on the branch, use:
git merge origin/dev_X

Next¶

You are now set up to work in any of the six repos. Open the module you'll work on first:

Customer app FE → someli-platform/
Customer app BE → someli-api/
Designer FE → Someli-Designer/
Designer BE → designer-api/
Admin FE → admin_console_R/
Admin BE → Someli-admin-api/