doxa-life/doxa-maps
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README: describe how the work actually lands, and today's map counts

Browse source 
PR branches start from the pilot and take in the latest pilot by merging, never rebasing; a second
agent, usually the repository's agent, reads the change (and looks at it where it shows). In the lock
the pilot is merged once more, gates:pre and gates:post run with the landing checks
(internal/landing-preconditions.mjs), and the branch is pushed only if nothing fails. There is no
single build owner: each change rebuilds the bundles it reaches, then the tree and SRI. Publishing
tags the outgoing release as a rollback point, runs both gate sets on the exact commit, and builds the
landing demo from the release tag. The counts follow the code: the Research Gallery composes nine maps
(plus Country Posters and Poster Design, both in Prayer Mobilization, so they leave the Experimental
list), ten maps are in production with the country map, and Posterverse brings six poster plugins
together. The glossary's "merge" row matches.
This commit is contained in:
Doxa Maps 2026-10-03 06:32:00 +00:00
parent 9c170fd143
commit 8a90eb5000
1 changed files with 46 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

80
README.md
View file

@ -37,8 +37,9 @@ Built with love, with the prayer that these maps bless the nations.
**A blessing for you.** These maps and posters are given to bless the people who bless the nations.
We love you, and we are thankful for your work. We bless you in Jesus' name.
Every poster is in Posterverse (`plugin-designs/posterverse/`): UPG100 Posters, Country Posters,
Poster Design and Wall of People Groups. They are all in the Plugin Studio (`bun run dev`) too.
Posterverse (`plugin-designs/posterverse/`) brings the six poster plugins together: UPG100 Posters, Country
Posters, Poster Design, Wall of People Groups, Bible Posters and Bless India Posters. They are all in the
Plugin Studio (`bun run dev`) too.
# dx-maps — one build, maps that embed everywhere
@ -125,9 +126,9 @@ people groups of the world. When you work here, the goal is one of these:
library and the checks.
- **One plugin per folder** in `plugin-designs/`; shared code goes in `library/` only if it stays reusable for
every other plugin.
- **Land on `development`**, one change at a time through the lock, with `bun run gates:pre` passing. `main` is
- **Land on `development`**, one change at a time through the lock, with `gates:pre`, `gates:post` and the landing checks passing. `main` is
production and moves only on a publish.
- These 8 maps are in production: the 7 in the gallery, plus the country map for DX Life's country pages. The
- These 10 maps are in production: the 9 in the gallery, plus the country map for DX Life's country pages. The
other maps are experimental: leave them as they are unless your task is one
of them.
@ -135,11 +136,12 @@ people groups of the world. When you work here, the goal is one of these:
---
## The 7 production maps
## The production maps
**Seven maps DX uses today** — each one a plugin you can embed on its own, and all seven together in
the Research Gallery, which DX Life publishes as **Deep Research**. An eighth production map, the country map
(`country-map`), draws DX Life's country pages; it isn't in the gallery.
**Nine maps DX uses today, all together in the Research Gallery**, which DX Life publishes as
**Deep Research**; each one is also a plugin you can embed on its own. The seven below plus Country Posters
and Poster Design (see Posterverse). A tenth production map, the country map (`country-map`), draws DX Life's
country pages; it isn't in the gallery.
<table>
<tr>
@ -152,7 +154,7 @@ the Research Gallery, which DX Life publishes as **Deep Research**. An eighth pr
<td width="25%" valign="top"><img src="documentation/readme-images/cap4-upg100-mfe.png" alt="UPG100 Posters"><br><b>UPG100 Posters</b><br><sub>prayer lists of 100 people groups, with posters to print</sub></td>
<td width="25%" valign="top"><img src="documentation/readme-images/prod-cities-internet.png" alt="Cities with Internet"><br><b>Cities with Internet</b><br><sub>internet access where unreached people groups live</sub></td>
<td width="25%" valign="top"><img src="documentation/readme-images/prod-gospel-resources.png" alt="Gospel Resources"><br><b>Gospel Resources</b><br><sub>which people groups have scripture, film or audio — and which have nothing</sub></td>
<td width="25%" valign="top"><img src="documentation/readme-images/cap5-doxa-maps-spa.png" alt="Research Gallery"><br><b>Research Gallery</b><br><sub>all seven in one app — capability 5</sub></td>
<td width="25%" valign="top"><img src="documentation/readme-images/cap5-doxa-maps-spa.png" alt="Research Gallery"><br><b>Research Gallery</b><br><sub>all nine in one app — capability 5</sub></td>
</tr>
</table>
@ -325,7 +327,7 @@ improvement on the next build.
</details>
<details>
<summary><b>What the Research Gallery is made of — seven production maps, an Experimental shelf, all five capabilities in one plugin</b></summary>
<summary><b>What the Research Gallery is made of — nine production maps, an Experimental shelf, all five capabilities in one plugin</b></summary>
```text
Research Gallery <doxa-maps-spa> capability 5
@ -340,10 +342,12 @@ Research Gallery <doxa-maps-spa> capability 5
│ ├─ regions list regions-list capability 1
│ └─ region dashboards region-dashboards capability 1
├─ Prayer Mobilization
│ ├─ Prayer Progress doxa-simple-map capability 2
│ ├─ UPG100 Posters upg-100-mfe capability 4
│ │ ├─ zoned map upg-100-list capability 1
│ │ └─ poster wall poster-wall capability 1
│ └─ Prayer Progress doxa-simple-map capability 2
│ ├─ Country Posters country-posters-mfe capability 4
│ └─ Poster Design poster-design-mfe capability 4
├─ Gospel Research
│ ├─ Cities with Internet connectivity-map capability 1
│ └─ Gospel Resources resources-map capability 1
@ -351,7 +355,6 @@ Research Gallery <doxa-maps-spa> capability 5
├─ prayer walk planner prayer-walk-planner capability 1
├─ UPG neighbor upg-neighbor capability 3
├─ all people groups all-people-groups capability 1
├─ country posters country-posters capability 4
├─ vision card doxa-vision-card capability 2
├─ PPLR data maps pplr-data-maps capability 3
└─ Wall of People Groups wall-of-people-groups capability 3
@ -741,8 +744,9 @@ has one agent that owns it, and the work moves through three kinds of branch:
with hot reload follows it, so each change that joins can be seen there within about 15 seconds.
- **The landing branch (`main`)** is what ships. It moves only when a person approves a publish, and
the landing server rebuilds from it.
- **PR branches** hold one plugin or feature each. They start from the landing branch and join the
pilot branch, one at a time, after the checks pass and the repo agent has read the change.
- **PR branches** hold one plugin or feature each. They start from the pilot branch, take in the latest
pilot by merging (never rebasing), and join it one at a time, after the checks pass and a second agent,
usually the repository's agent, has read the change.
**It scales by adding PR branches, not by sharing one.** Many people, each with several agents, can
work on many plugins at the same time: every plugin or feature gets its own PR branch, and each one
@ -766,11 +770,11 @@ these jobs to its agents.
```bash
git fetch origin && git switch -c development origin/main && git push -u origin development
```
3. **One PR branch and worktree per feature**, each started from the landing branch, then install
3. **One PR branch and worktree per feature**, each started from the pilot branch, then install
once in each:
```bash
git worktree add -b regions/work ../dx-maps-regions origin/main
git worktree add -b upg100/work ../dx-maps-upg100 origin/main
git worktree add -b regions/work ../dx-maps-regions origin/development
git worktree add -b upg100/work ../dx-maps-upg100 origin/development
cd ../dx-maps-regions && bun install --frozen-lockfile
```
4. **One preview server per agent on your own machine, each on its own port** (in the cloud, the one
@ -778,35 +782,43 @@ these jobs to its agents.
```bash
bun x vite --port 5301 --strictPort # the next agent uses 5302, and so on
```
5. **Join the pilot one at a time, through a lock that works like a merge queue.** Inside the lock, merge your PR branch into a
throwaway copy of the pilot branch, run the checks, and push that merge only if nothing fails
(`gates:pre` exits non-zero when a check fails, so the push never runs then). Your PR branch itself
stays one feature on the landing branch; only the pilot gets the merge:
5. **Join the pilot one at a time, through a lock that works like a merge queue.** First merge the
latest pilot into your PR branch (merge, never rebase) and fix any clash there. A second agent reads
the change, and looks at it on screen where it shows. Then, inside the lock, merge the pilot once more
in case it moved, run the checks (`gates:pre`, `gates:post`) and the landing checks (fresh bundles,
the tree, the integrity hashes, no conflict markers), and push only if nothing fails:
```bash
git fetch origin && git merge --no-edit origin/development # on your PR branch: the latest pilot
flock /tmp/dx-maps-development.lock sh -c '
git fetch origin && git switch --detach origin/development &&
git merge --no-edit regions/work &&
bun run gates:pre && git push origin HEAD:development
git switch regions/work'
git fetch origin && git merge --no-edit origin/development &&
bun run gates:pre && bun run gates:post &&
node internal/landing-preconditions.mjs &&
git push origin HEAD:development'
```
If the merge stops on a conflict, run `git merge --abort`, fix the clash on your PR branch and join
again. `flock` guards one machine. Agents on several machines need a shared lock, such as one your
harness provides.
6. **One agent owns the full build**; the others build only their own plugin:
6. **Each change rebuilds what it touches.** There is no single build owner: rebuild every bundle your
change reaches, then the tree and the integrity hashes, and commit them with the change. The landing
checks refuse a change whose bundles are stale:
```bash
BUILD_ALLOW=1 bun run build # the build owner: every plugin
BUNDLE=<name> bun x vite build && bun run tree && bun run fix:sri # everyone else: one plugin
BUNDLE=<name> bun x vite build # each bundle your change reaches
bun run tree && bun run fix:sri # then the tree and the integrity hashes
```
7. **Publish, when a person approves it:** fast-forward the landing branch to a pilot commit that
passed the checks, tag it, and deploy from the tag:
Only a change to the build itself (its config or its dependencies) reaches every bundle:
`BUILD_ALLOW=1 bun run build`.
7. **Publish, when a person approves it:** tag the release the landing branch is on now as the
rollback point, fast-forward the landing branch to a pilot commit that passed the checks, tag it, and
deploy from the tag:
```bash
git fetch origin && git switch main && git merge --ff-only origin/main
git tag -a rollback-v1.0.0 -m "Rollback point: the release before v1.0.0" && git push origin rollback-v1.0.0
git merge --ff-only <development-commit> # a commit that passed the checks
bun run gates:pre # the checks must pass on exactly this commit
bun run gates:pre && bun run gates:post # the checks must pass on exactly this commit
git tag -a v1.0.0 -m "Release v1.0.0" && git push origin main v1.0.0
```
The tag's `public/dx-maps/` folder is the built site: deploy that
([how to deploy](./documentation/DEPLOY.md)). Publish to a public host, such as GitHub, only from
The tag's `public/dx-maps/` folder is the built site: deploy that, and build the landing demo from
the same tag ([how to deploy](./documentation/DEPLOY.md)). To go back, deploy the rollback tag. Publish to a public host, such as GitHub, only from
the landing branch and only when it is ready.
### Developing in the cloud with a swarm
@ -864,7 +876,7 @@ That's how many plugins get built at the same time, in one project, without the
| **main** (the landing) | the version that ships: it moves only when a person approves publishing `development` |
| **worktree** | a private copy of the project for one agent to work in |
| **merge conflict** | two changes touched the same lines; someone has to decide how to combine them |
| **merge** | combining your branch with everyone else's latest work; here it happens inside the pilot lock, in a throwaway copy of the pilot |
| **merge** | taking everyone else's latest work into your branch: the latest pilot goes into your PR branch (never a rebase), before joining and once more inside the pilot lock |
| **pilot lock** | only one change merges onto `development` at a time; its holder catches up and runs every check first |
| **tag** | a fixed name for one release commit, such as `v1.0.0`, so you can always deploy exactly it |