add workflow page — dev-flow centerpiece
New docs/workflow.md covering how we actually work day to day: - why git / why WSL2 (our reasons, links out for generic install) - signing up on our Gitea (self-serve register, SSH + deploy-key model) - our git vs public git: per-repo identity, signed commits, develop->main - our-flavored git basics (everyday loop, commit small/often, gl graph) - the dev workflow: plan-in-chat / build-in-Claude-Code, tmux split, claudedo voice control, the .claude/ project convention, AI-assist habits (git diff | clip.exe) - recommended setup (WSL + VS Code + Claude Code, pyenv, flake8) - handy .zshrc/.bashrc snippets with prose on the high-value ones Claude-first but soft: any AI works, we recommend Claude, and the .claude/ structure is built on that preference. Sanitized with placeholders throughout. Nav: Home / Libraries / Standards / Workflow / Deploy; landing card grid updated. Verified: mkdocs build --strict clean. Signed-off-by: disqualifier <dev@disqualifier.me>
This commit is contained in:
parent
d3c85acd1e
commit
5e787edbb0
@ -25,6 +25,13 @@ out of it; examples use placeholders like `<dev>`, `<project>`, and `/srv/...`.
|
||||
House coding standards — file hygiene, docstrings, type hints, linting, and
|
||||
how we handle errors.
|
||||
|
||||
- :material-sitemap: __[Workflow](workflow.md)__
|
||||
|
||||
---
|
||||
|
||||
How we actually work day to day — our Gitea, git habits, and the
|
||||
plan-in-chat / build-in-Claude-Code flow, plus shell setup.
|
||||
|
||||
- :material-rocket-launch: __[Deploy](deploy.md)__
|
||||
|
||||
---
|
||||
|
||||
231
docs/workflow.md
Normal file
231
docs/workflow.md
Normal file
@ -0,0 +1,231 @@
|
||||
# Workflow
|
||||
|
||||
How we actually work day to day at Rethink Studios — where code lives, how we use
|
||||
git, the AI-assisted dev flow we recommend, and the shell setup that ties it
|
||||
together. This is the **our-flavored** version: why *we* do it this way and how
|
||||
*our* setup is wired. For the truly generic parts (installing WSL, learning git),
|
||||
we link the official docs rather than reteach them.
|
||||
|
||||
!!! info "Public, sanitized"
|
||||
Examples use placeholders — `<you>`, `<key>`, `dev@<you>`, `/mnt/c/<your>/...`.
|
||||
Swap in your own real values locally; never commit personal paths, key names,
|
||||
or emails.
|
||||
|
||||
## Why git, why WSL
|
||||
|
||||
**Git** is the backbone of everything here. Version history and branching are the
|
||||
obvious part, but our whole deploy model is built on git too: we `pip install`
|
||||
libraries straight from git by tag, servers pull via per-repo deploy keys, and
|
||||
changes flow `develop → main` before they ship. If you know git, you already
|
||||
understand how our code moves from your machine to production.
|
||||
|
||||
**WSL2 (Ubuntu)** is where we develop — a real Linux toolchain on a Windows
|
||||
desktop. You get native Linux tooling (the same environment our servers run) plus
|
||||
the Windows apps you actually use day to day. Install WSL2 from Microsoft's docs;
|
||||
this page documents the *our-setup* layer that goes on top.
|
||||
|
||||
- [Install WSL (Microsoft)](https://learn.microsoft.com/windows/wsl/install)
|
||||
- [VS Code Remote — WSL](https://code.visualstudio.com/docs/remote/wsl)
|
||||
|
||||
## Signing up on our Gitea
|
||||
|
||||
Our code lives on **Gitea** at
|
||||
[git.rethinkstudios.io](https://git.rethinkstudios.io). Two orgs you'll use:
|
||||
|
||||
- **[rethink-public](https://git.rethinkstudios.io/rethink-public)** — public
|
||||
libraries, resources, and assets.
|
||||
- **[rethink-software](https://git.rethinkstudios.io/rethink-software)** — our
|
||||
applications.
|
||||
|
||||
**Get an account:**
|
||||
|
||||
1. Register at [git.rethinkstudios.io](https://git.rethinkstudios.io) and verify
|
||||
your email.
|
||||
2. Add your **SSH public key** under *Settings → SSH / GPG Keys* so you can clone
|
||||
and push over SSH.
|
||||
3. For servers, we use a **per-repo deploy-key** model rather than your personal
|
||||
key — see the [Deploy guide](deploy.md) for how a box gets read access to just
|
||||
the repos it needs.
|
||||
|
||||
## Our git vs. public git (GitHub / GitLab)
|
||||
|
||||
It's the same git — just a different host. The thing most devs trip on is
|
||||
**identity and keys per host**: you may have a GitHub identity *and* a Gitea
|
||||
identity on one machine, and commits need to be attributed (and signed/pushed)
|
||||
with the right one per project.
|
||||
|
||||
We solve that with **per-repo local git config** — run a small alias inside a repo
|
||||
to set its local user and the SSH key it pushes with (see
|
||||
[per-project git identity](#per-project-git-identity) below). No global identity
|
||||
juggling.
|
||||
|
||||
Our conventions, in short:
|
||||
|
||||
- **Signed commits** — `git commit -s`.
|
||||
- **No AI co-author trailer** on your own work. (Intern/dev work you're crediting
|
||||
gets that dev's `Co-Authored-By` — nothing else.)
|
||||
- **`develop` is staging**, merge to **`main`** via MR when it's ready to ship.
|
||||
- **Libraries install from git by tag** — pin a version in your deps, bump the
|
||||
tag when the lib releases.
|
||||
|
||||
## Git basics (our-flavored)
|
||||
|
||||
Not a git tutorial — just how the everyday loop looks against our Gitea. For the
|
||||
generic command reference, keep the
|
||||
[Git cheat sheet](https://training.github.com/downloads/github-git-cheat-sheet/)
|
||||
or the [Pro Git book](https://git-scm.com/book) handy.
|
||||
|
||||
**Clone** over SSH (the alias maps to a key — see the shell setup):
|
||||
|
||||
```bash
|
||||
git clone git@<alias>:rethink-public/<repo>.git
|
||||
```
|
||||
|
||||
**The everyday loop:**
|
||||
|
||||
```bash
|
||||
git switch -c <feature> # branch off
|
||||
# ...make a logical change...
|
||||
git commit -s -m "..." # commit, signed
|
||||
git push -u origin <feature> # push
|
||||
# open an MR: develop -> main
|
||||
```
|
||||
|
||||
**Commit small and often** — one commit per logical change, not a giant
|
||||
end-of-day dump. Small commits are easier to review, revert, and `git bisect`
|
||||
when something breaks.
|
||||
|
||||
**Read history** as a graph with the `gl` alias below:
|
||||
|
||||
```bash
|
||||
gl # git log --graph, oneline, decorated
|
||||
```
|
||||
|
||||
## The dev workflow
|
||||
|
||||
This is the part that's distinctly *ours*. AI is a force multiplier, but only with
|
||||
discipline around it — the two habits that matter most are **plan before you
|
||||
build** and **verify by executing, not asserting**.
|
||||
|
||||
You can use whatever AI you like — but we **recommend Claude** (via
|
||||
[Claude Code](https://docs.claude.com/en/docs/claude-code/overview), in the
|
||||
terminal or VS Code). The whole project structure we recommend below — the
|
||||
`.claude/` folder, `CLAUDE.md` instructions, numbered specs — is built on that
|
||||
preference: it's designed around how Claude Code reads project context and takes
|
||||
handoffs. Other tools can read these files too, but the convention assumes
|
||||
Claude-first.
|
||||
|
||||
**Plan here, build in Claude Code.** Do the thinking in chat — plan, write the
|
||||
spec, make the decisions. Then hand that spec to a Claude Code agent that does the
|
||||
build: it implements, **verifies by running**, and pushes. The chat plans; the
|
||||
agent implements.
|
||||
|
||||
**tmux + Claude Code split.** In practice that's a Claude Code agent running in a
|
||||
tmux pane doing the build work while you plan/review in another. One spec in, a
|
||||
verified change out.
|
||||
|
||||
**claudedo (optional, hands-free).** Voice control for Claude Code over tmux: a
|
||||
wake-word plus local Whisper speech-to-text drives your tmux session without the
|
||||
keyboard — handy when you're fullscreen or away from the desk. It's available
|
||||
here:
|
||||
[git.rethinkstudios.io/rethink-software/claudedo](https://git.rethinkstudios.io/rethink-software/claudedo).
|
||||
|
||||
**The `.claude/` project convention.** Every project has a top-level `.claude/`
|
||||
folder (always gitignored — nothing under it is committed):
|
||||
|
||||
- **`CLAUDE.md`** — project-specific instructions for the agent (stack, layout,
|
||||
conventions). Layered on top of your global instructions.
|
||||
- **`compact.md`** — a running state log (done / decided / in-flight), updated at
|
||||
checkpoints so a fresh session catches up fast.
|
||||
- **`commands.log`** — an append-only record of shell commands run.
|
||||
- **`spec/`** — numbered, per-change specs named `NN-<type>-<short>.md`
|
||||
(e.g. `01-feature-logging.md`).
|
||||
|
||||
Tell the agent to **"setup project"** to scaffold all of that (and add `.claude/`
|
||||
to `.gitignore`) in a new repo.
|
||||
|
||||
**AI-assist habits.** When you're stuck, give the AI the *exact* context instead
|
||||
of describing it — the WSL clipboard bridge makes this trivial:
|
||||
|
||||
```bash
|
||||
git diff | clip.exe # then paste the diff straight into the chat
|
||||
```
|
||||
|
||||
Use AI for the plan and the spec, let the agent build, and always **prove it
|
||||
works by running it** — don't accept "this should work."
|
||||
|
||||
## Recommended setup
|
||||
|
||||
- **WSL2 (Ubuntu) + VS Code + Claude Code.** Develop in WSL, edit in VS Code over
|
||||
[Remote — WSL](https://code.visualstudio.com/docs/remote/wsl), and run
|
||||
[Claude Code](https://docs.claude.com/en/docs/claude-code/overview) as your
|
||||
agent (terminal or the VS Code extension).
|
||||
- **[pyenv](https://github.com/pyenv/pyenv)** for Python versions — per-project
|
||||
versions, we target Python **3.10+**.
|
||||
- **[flake8](https://flake8.pycqa.org/)** with a shared config — max line length
|
||||
**120** (see the alias below).
|
||||
|
||||
## Handy shell setup
|
||||
|
||||
Copy-paste these into your `.zshrc` / `.bashrc`. Replace every placeholder with
|
||||
your real values. The high-value ones are explained underneath.
|
||||
|
||||
```bash
|
||||
# --- WSL <-> Windows bridges ---
|
||||
alias explorer="explorer.exe ." # open current dir in Windows Explorer
|
||||
# pipe to the Windows clipboard (great for pasting context into AI):
|
||||
# git diff | clip.exe -> paste the diff straight into a chat
|
||||
# auto-alias Windows .exe tools on PATH (e.g. adb/platform-tools):
|
||||
export PATH="$PATH:/mnt/c/<your>/platform-tools"
|
||||
for exe in /mnt/c/<your>/platform-tools/*.exe; do
|
||||
alias "$(basename "${exe}" .exe)"="${exe}"
|
||||
done
|
||||
|
||||
# --- pyenv (Python version management) ---
|
||||
export PYENV_ROOT="$HOME/.pyenv"
|
||||
export PATH="$PYENV_ROOT/bin:$PATH"
|
||||
eval "$(pyenv init --path)"
|
||||
eval "$(pyenv init -)"
|
||||
eval "$(pyenv virtualenv-init -)"
|
||||
|
||||
# --- flake8 with a shared config ---
|
||||
alias flake8='flake8 --config ~/.config/flake8'
|
||||
|
||||
# --- per-project git identity (switch identity per repo) ---
|
||||
# set the LOCAL (per-repo) user + the key to sign/push with:
|
||||
alias gitsetup='git config --local user.name "<you>"; \
|
||||
git config --local user.email "dev@<you>"; \
|
||||
git config --local core.sshCommand "ssh -i $HOME/.ssh/<key>"'
|
||||
# a second identity for a different account, same pattern:
|
||||
alias gitea='git config --local user.name "<alt>"; \
|
||||
git config --local user.email "<alt>@<host>"; \
|
||||
git config --local core.sshCommand "ssh -i $HOME/.ssh/<alt-key>"'
|
||||
|
||||
# --- git log graph ---
|
||||
alias gl='git log --graph --abbrev-commit --pretty=oneline --decorate'
|
||||
|
||||
# --- local bins on PATH ---
|
||||
export PATH="$HOME/.local/bin:$PATH"
|
||||
export PATH="$HOME/.npm-global/bin:$PATH"
|
||||
```
|
||||
|
||||
```bash
|
||||
# cherry-pick a commit onto master/main quickly
|
||||
gitcs() {
|
||||
if [ -z "$1" ]; then echo "Usage: gitcs <commit>"; return 1; fi
|
||||
git checkout master && git cherry-pick "$1"
|
||||
}
|
||||
```
|
||||
|
||||
**The ones worth understanding:**
|
||||
|
||||
- **`git diff | clip.exe`** — the killer WSL trick for AI-assisted dev. Pipe your
|
||||
working changes straight to the Windows clipboard and paste them into the chat
|
||||
so the AI sees *exactly* what changed instead of your paraphrase of it.
|
||||
- **`gitsetup` / `gitea`** — per-repo identity. One machine, multiple Gitea
|
||||
identities and keys; run the alias inside a repo to set its **local** user and
|
||||
signing/push key, so commits attribute correctly without touching your global
|
||||
config.
|
||||
- **`gl`** — a readable branch graph for understanding history at a glance.
|
||||
- **`pyenv`** — per-project Python versions, so each repo builds against the
|
||||
version it targets.
|
||||
@ -59,4 +59,5 @@ nav:
|
||||
- Home: index.md
|
||||
- Libraries: libraries.md
|
||||
- Standards: standards.md
|
||||
- Workflow: workflow.md
|
||||
- Deploy: deploy.md
|
||||
|
||||
Loading…
Reference in New Issue
Block a user