Allied Outdoor Solutions · Plain English Standard
Every change to an Allied app takes the same nine steps. This page names each one, and gives the one word we all use for it. Same words, every app, every person, so nobody has to guess what happened.
Any word, at any point, and you get a plain answer with no fuss. It is never a bother and it is not a setting. Not asking is the only thing that costs anything.
Say one of these to Claude and it sticks, in every app, on every computer. Everyone starts in the middle.
In order, and a change cannot skip one. The words in blue are locked: they never get swapped for a synonym, in any app, by anyone.
Agree what we are making and how it should behave, before anyone touches anything.
A spec is a short write-up of how it should work, put in front of people so they can argue with it while arguing is still cheap. Not a proposal, which is what we hand a customer.
Write it down where it can be found, assigned, and closed. Not in a document, not in a chat.
Always both words, GitHub Issue. An issue on its own is a problem on a job. Every one gets an Issue label, and there are exactly three: bug, future-work, decision-needed.
The work happens on your own computer, on a copy nobody else can see and nothing else depends on. Half-finished is fine here. Nothing you do can reach the app anyone is using.
Always git branch, never just "branch", because a branch here is an office. Main is the one git branch everyone has agreed is the real app, and it is what your work eventually joins.
Make the change itself.
An env variable is a saved setting, usually a password, kept out of the code so the browser never sees it.
Prove it works before anyone else sees it. Steps 4 and 5 go round and round until it holds up. That loop is the normal case, not a sign anything went wrong.
Validate is the automatic check that runs before anything can go out. A preview link is a private copy of the app you can click, which is the closest thing we have to a rehearsal.
A checkpoint, a note in plain English saying what changed, and straight up to GitHub in the same breath.
These are two separate acts underneath, and they are always done together on purpose. Work that exists only on one computer is work that can be lost. We say save, never persist, flush, or write through.
Somebody, or something, checks the work before it counts. Routine changes are approved by a bot. Anything touching a locked decision waits for a person.
Branch protection is the rule that stops any one person merging alone. The bot lane is the narrow set of changes safe enough to approve automatically, so routine work does not sit in a queue.
The private copy folds into main, and becomes the real app.
A merge conflict means two people changed the same line. Stop and ask; never guess which one wins.
It goes live. For most apps this happens by itself the moment the merge lands.
Continuous deploy means merging is what puts it live. There is no separate button and nobody to remind. Rollback puts the previous working version back.
These are the ones that cause real mistakes, because nobody feels confused. The Allied meaning wins every time, and the tech meaning finds another word.
| We say | Never | Because here, that word means |
|---|---|---|
| git branch | branch | an Allied office |
| live | production, prod | the department that builds the jobs |
| scheduled job | job | a customer's job |
| column | field | where the crews are |
| the deploy steps | pipeline | the sales pipeline |
| deploy | build, ship | building jobs, shipping materials |
| version | release | a lien release |
| library | package | the sold package |
| code review | review | a customer review |
| GitHub Issue | issue | a problem on the job |
| push to GitHub | push | moving a job to next week |
| pull request, git pull | pull | pulling a permit |
| fix | patch | patching concrete |
| waiting on | blocked | a concrete block |
| preview link | staging | materials staged on site |
| on your computer | local | the local office |
Six names you will hear constantly. This is the whole of what they are.
Where the code lives, along with every change ever made to it and who reviewed it.
Puts the apps on the internet, and puts a change live the moment it merges.
The data warehouse. Every piece of real Allied data ends up here.
Amazon's file storage, for photos, PDFs, and signed contracts. A bucket is a folder.
Sign-in for every app, plus the shared drive that holds reference files.
Small pieces of code that run on the server instead of in the browser, so they can hold passwords safely.
Ask what any word means, any time. Or say beginner, expert, nerd, or turn it off to change how much gets explained from here on.
The full standard, with every word and its meaning, is PLAIN_ENGLISH.md in the allied-app-standards repo.
Five words for “save” do not make us precise. They make it impossible to tell what happened.