Every analytics tool wants a subscription. And your data. I built Twiligent instead. YouTube stats. Instagram stats. One dashboard. Runs locally on your machine.
Git Workflow
Repository
- URL: https://github.com/spacesdrive/twiligent
- Author name: spacesdrive
- Author email: [email protected]
- Default branch: main
Commits must use the spacesdrive author identity. The local git config is set to this. Never override it per-commit with a different author.
Do not add "Co-Authored-By" lines referencing AI tools. Commits should show only the project author.
Commit Cadence
Commit as soon as one small change works, however small: a fixed message, a new prop, one renamed function, one migration. Don't wait to collect several changes; a commit made right away is easy to track, review, revert and search. This follows how experienced teams work:
- Git's own guide (
gitworkflows, "Separate changes"): split work into small logical steps from the start and commit each one, each working independently and passing the tests, because squashing small commits later is easier than splitting a big one. - Google's engineering practices ("Small CLs"): the right size is one self-contained change that does just one thing, usually part of a feature rather than all of it, and "it's better to err on the side of" too small.
- GitHub's engineering blog ("Write better commits"): each commit small and atomic, so the repository still builds and passes its tests at that exact commit;
git bisectand reverting both depend on it.
What one commit holds
| Rule | In practice |
|---|---|
| One logical change | The subject says it in one sentence with no "and". If it needs "and", make two commits |
| Small means focused, not few lines | A rename across 20 files is one commit; a 30-line change that fixes a bug and tidies a helper is two |
| Refactors on their own | Moving, renaming or reshaping code that keeps the behaviour goes in its own commit, before the change that needs it. A one-word variable rename inside a fix may stay |
| Tests and docs travel with the change | The test for the new behaviour and the doc line that describes it go in the same commit as the code |
| Every commit works | npm run typecheck passes, and the tests for the touched area pass, before each commit; main uses rebase merges, so every commit lands there on its own |
| Order builds up | Shared types before the backend that uses them, the backend before the screen that calls it, so each commit stands on the ones before |
| Stage on purpose | Add the files of this change by path, never git add -A over unrelated edits; split a file's changes with git add -p when it holds two |
Examples of commits that are each one change:
fix(publish): use the local day for the schedule date pickerrefactor(frontend): move fieldHintId and fieldErrorId to lib/fieldIdsfeat(api): accept ?fresh=1 on the Instagram media readtest(frontend): cover engagement sorting as a numberdocs(routing): describe the /publish and /instagram redirects
Never commit work that breaks the build or the type check, and never leave work uncommitted at the end of a session: commit the last working step, and note what remains in the issue. Push the branch after each few commits so the work is not only on one machine.
Commit Message Format
Use Conventional Commits with an optional scope:
type(scope): short description in present tense
Optional body explaining WHY, not WHAT. Wrap at 72 characters.
Reference which docs were updated if any.
Refs #12
Issue reference
Every commit ends with a reference to the GitHub issue that tracks the work (see docs/workflows/ISSUES.md):
Refs #N- the commit is part of the work; the issue stays openCloses #N- the commit completes the issue; GitHub closes it when the commit reachesmain
A commit that finishes several issues lists each one: Closes #3, closes #4. A commit on a branch that closes an issue only takes effect when it is merged to main.
Types
| Type | When to use |
|---|---|
feat |
New feature or capability |
fix |
Bug fix |
docs |
Documentation only |
refactor |
Code restructuring, no behavior change |
style |
Formatting or whitespace, no logic change |
perf |
Performance improvement |
chore |
Maintenance, dependency updates, tooling |
release |
Version bump and changelog update |
Scope (optional)
Use scope to name the area affected:
feat(instagram):fix(scheduler):docs(routing):chore(deps):
Subject line rules
- Present tense: "add" not "added", "fix" not "fixed"
- No period at the end
- Under 72 characters total including type and scope
- Lowercase after the colon
- No emojis
Examples
feat(analytics): show uploads by month or week on the Videos page
fix(scheduler): strip non-ASCII characters from env vars to prevent ByteString error
docs(architecture): document dual-scheduler mutex pattern in SCHEDULING.md
refactor(instagram): extract token refresh into standalone service function
chore(deps): update @supabase/supabase-js to latest
release: v1.4.0 - Intent UI charts and uploads card
What to Commit Together
Always group these in a single commit:
- A new route + its controller, service and repository methods + its api.ts method
- A new page + its route in App.tsx + its Sidebar entry
- A bug fix + updated docs if the fix changes documented behavior
- A new feature + CHANGELOG.md update + relevant architecture doc updates
- A dependency change + the workspace
package.jsonit touches + the rootpackage-lock.json
Never commit:
backend/.dev.varsbackend/data/node_modules/backend/package-lock.jsonorfrontend/package-lock.json(only the root lockfile is committed; a lockfile inside a workspace meansnpm installran in the wrong folder).envfiles with real credential values- Cloudflare API tokens or Supabase service keys
- Editor or OS metadata files (
.DS_Store,Thumbs.db)
Documentation in Commits
Every feature commit must include documentation updates. A feature is not complete until:
CHANGELOG.mdis updated (Unreleased section)- Relevant architecture docs reflect the change (see
CLAUDE.mdDocumentation Maintenance Policy)
Include in the commit body which docs were updated:
feat(schedule): add bulk CSV post scheduling
Users can now upload a CSV file to schedule multiple posts at once.
Each row in the CSV maps to one scheduled_post record.
Docs updated: ROUTES.md, SCHEDULING.md, CHANGELOG.md.
Closes #42
Release Tagging
Every pull request that changes what a user or an instance owner sees is a release, however small: a fix, a feature, a changed message, a UI adjustment. It carries its own version. Pull requests that change only docs, tests, CI or code structure with identical behaviour are not releases; their notable entries wait under ## [Unreleased] and ship with the next version.
Version numbering
Choose the number from the largest change in the pull request.
| Change type | Version bump | Example |
|---|---|---|
| Bug fix, copy or styling change, small UI adjustment, performance or accessibility fix | Patch: x.x.N+1 | v1.3.0 -> v1.3.1 |
| New feature, page, setting, route, environment variable or migration (old setups keep working, even if the owner must run an upgrade step) | Minor: x.N+1.0 | v1.3.1 -> v1.4.0 |
| Breaking change: an instance stops working until the owner acts, a public route or API is removed, or stored data must be migrated by hand | Major: N+1.0.0 | v1.4.0 -> v2.0.0 |
Release process
main only accepts pull requests (see Branch Strategy), so the version is set inside the change's own pull request, and the tag is made on main after the merge, because a rebase merge gives the commit a new hash.
- In the pull request, add the entries to
CHANGELOG.mdunder a new heading## [X.Y.Z] - YYYY-MM-DD(moving anything waiting under Unreleased into it), and set the rootpackage.jsonversiontoX.Y.Z - The last commit of the pull request is
release: vX.Y.Z - short description of release; merge once CI passes - Tag the merged commit and push only the tag (tags are not protected)
- Publish a GitHub Release page for the tag, with notes in the format below
# Example: the last commit on the change's own branch
git add CHANGELOG.md package.json package-lock.json
git commit -m "release: v1.4.0 - Intent UI charts and uploads card"
git push
gh pr create --fill
# after the pull request is merged
git fetch origin
git tag -a v1.4.0 origin/main -m "v1.4.0 - Intent UI charts and uploads card"
git push origin v1.4.0
gh release create v1.4.0 --verify-tag --title "v1.4.0 - Intent UI charts and uploads card" --notes-file release-notes.md --latest
Write the notes file outside the repository; it is not committed.
Release notes
Every tag gets a GitHub Release page at https://github.com/spacesdrive/twiligent/releases. Its notes explain the release in plain words to someone who uses or runs Twiligent; CHANGELOG.md keeps the full detail. The notes follow docs/WRITING_STANDARDS.md: no emojis, no em or en dashes, no exclamation marks, no marketing words.
| Part | What it holds |
|---|---|
| Title | The tag and the release commit's description: v1.1.1 - Docs home fix and scheduler recovery |
| Summary | One or two sentences on what the release changes for the person using it, before any heading |
## Added, ## Changed, ## Fixed |
Only the sections that have entries. One short line per change, in the user's words: what now works, not how the code changed. A handful of lines, not every changelog entry |
## Upgrading |
Only when an instance owner must act: SQL to run, a secret or setting to add or change. Give the exact SQL or name, say when to do it (before or after deploying), and link the docs page that has the same steps |
| Last line | Full list of changes: [CHANGELOG.md](https://github.com/spacesdrive/twiligent/blob/vX.Y.Z/CHANGELOG.md), linked at the tag |
The newest release is marked --latest; publishing an older tag later uses --latest=false. Fix a mistake in published notes with gh release edit vX.Y.Z --notes-file release-notes.md.
Branch Strategy
main is protected by the repository ruleset Protect main (Settings, Rules, Rulesets). Every change, however small, goes through a branch and a pull request, and GitHub Actions deploys both apps when it lands on main.
| Rule | Effect |
|---|---|
| Restrict deletions | main cannot be deleted |
| Block force pushes | History on main cannot be rewritten |
| Require a pull request before merging | Direct pushes to main are refused; no approval is required, so the owner can merge their own pull request |
| Require status checks to pass | The CI job Type check, lint, test, build (.github/workflows/ci.yml) must pass on the pull request, and the branch must be up to date with main |
| Require linear history | Pull requests merge with Rebase and merge (preferred, keeps one commit per change with its Refs #N) or Squash and merge; merge commits are refused |
Nobody bypasses the ruleset, including administrators. Renaming the CI job breaks the status check rule: update the ruleset in the same pull request (see docs/architecture/cloudflare/CI_CD.md).
git switch -c fix/scheduler-timezone
# work, commit with Refs #N
git push -u origin fix/scheduler-timezone
gh pr create --fill # body lists Closes #N, following .github/pull_request_template.md
gh pr checks --watch # wait for CI
gh pr merge --rebase --delete-branch # once CI passes; this deploys both apps
If main moved on since the branch was made, the merge is refused until the branch is updated: gh pr update-branch --rebase, then wait for CI again.
A pull request can be stacked on another branch when it depends on unmerged work. Set its base to that branch, merge the lower pull request first, then change the upper one's base to main (gh pr edit <n> --base main) and rebase it before merging.
Delete the local branch after merging:
git switch main && git pull
git branch -d fix/scheduler-timezone
Pre-Commit Checklist
Run before every commit:
Run the commands from the repository root:
npm run typecheck- every TypeScript project must type-check (Vite and Wrangler do not check types)npm run build- frontend must build without errorsnpm test- backend and frontend unit tests must passnpm run lint- no new lint errors (one run covers backend, frontend, tests and scripts)git status- verify only intended files are stagedgit diff --staged- review the full diff before committing- Check no secrets or credentials appear in the diff
- Check no lockfile appears inside
backend/orfrontend/; the rootpackage-lock.jsonis the only lockfile - Verify CHANGELOG.md is updated if the commit adds a feature or fix
- Verify the commit body ends with
Refs #NorCloses #Nfor the tracking issue
Post-Commit
After pushing to main, monitor GitHub Actions:
backend/changes triggerdeploy-backend.ymlfrontend/changes triggerdeploy-frontend.ymlshared/,tsconfig.base.json, rootpackage.jsonorpackage-lock.jsonchanges trigger both- Every pull request and every push to another branch runs
ci.yml(type check, lint, test, build, Worker dry-run) scripts/changes do not trigger automatic deployment
If a deployment workflow fails:
- Read the failure log at https://github.com/spacesdrive/twiligent/actions
- Open a
bugissue for the failure, or comment on the issue the push was for - Fix the issue locally
- Create a new commit (never amend a published commit) that references the issue
- Push the fix
After the push, check that every issue the work finished is closed (gh issue list --state open). Close any that a Closes #N line did not close, with a comment naming the commit.