Skip to content

Commit 8d60956

Browse files
flyingrobotsflyingrobots
authored
Merge pull request #71 from git-stunts/slice-5-collapse-runway
feat!: prepare git-warp v15 public API and docs surface
2 parents 2a12523 + 4fa3100 commit 8d60956

306 files changed

Lines changed: 26359 additions & 9240 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

CODE_OF_CONDUCT.md renamed to .github/CODE_OF_CONDUCT.md

File renamed without changes.

‎.github/CONTRIBUTING.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# Contributing to @git-stunts/git-warp
2+
3+
## Planning Sources Of Truth
4+
5+
Do not duplicate the repo's "active plan" inside `CONTRIBUTING.md`.
6+
That information drifts too easily here.
7+
8+
Instead, use these sources:
9+
10+
- `BACKLOG/README.md` for the currently active cycle and promotable pre-design
11+
slices
12+
- `ROADMAP.md` for committed release and milestone inventory
13+
- `CHANGELOG.md` for what has already landed on the branch or in released
14+
versions
15+
- `docs/design/` for the governing design notes promoted from active backlog
16+
items
17+
18+
If these artifacts disagree, reconcile them as part of the cycle close instead
19+
of letting `CONTRIBUTING.md` become a second planning registry.
20+
21+
## Development Loop
22+
23+
This repo follows the same disciplined cycle used by higher-layer products built
24+
on git-warp:
25+
26+
1. design docs first
27+
2. tests as executable spec second
28+
3. implementation third
29+
4. playback, retrospective, and reconciliation after the slice lands
30+
31+
Tests are the spec. Design docs define intent and invariants. Implementation
32+
follows.
33+
34+
When a `BACKLOG/` item is selected for active work, promote it into
35+
`docs/design/` before writing tests.
36+
37+
For non-trivial work, use IBM Design Thinking style framing:
38+
39+
- sponsor actors
40+
- hills
41+
- playbacks
42+
- explicit non-goals
43+
44+
Keep that vocabulary in the design method. Do not leak it into the runtime
45+
ontology unless the substrate truly needs a first-class concept.
46+
47+
## Retrospectives
48+
49+
Retrospectives are not optional cleanup. Every closed slice should leave behind
50+
an explicit retrospective, and that retrospective must audit the landed changes
51+
against the intended design.
52+
53+
At minimum, every retrospective should include:
54+
55+
1. governing design docs and backlog IDs
56+
2. what actually landed
57+
3. a `Design Alignment Audit` section
58+
4. any observed drift
59+
5. whether the drift is accepted, rejected, or deferred
60+
61+
The `Design Alignment Audit` should check the implemented slice against the
62+
intended invariants and label each major point as:
63+
64+
- `aligned`
65+
- `partially aligned`
66+
- `not aligned`
67+
68+
If implementation drift occurred, the retrospective must say why:
69+
70+
- deliberate tradeoff
71+
- implementation shortcut
72+
- hidden pre-existing constraint
73+
- test gap
74+
- design ambiguity
75+
76+
And it must say how the repo resolves that drift:
77+
78+
- update the design docs
79+
- add a follow-on `BACKLOG/` item
80+
- immediately fix the implementation in the next slice
81+
82+
Do not treat a passing test suite as proof that the design was honored. The
83+
retro is where we verify that the code matches the intended architecture, not
84+
just the executable spec that happened to be written.
85+
86+
## Checkpoints
87+
88+
Most slices should pass through four checkpoints:
89+
90+
1. doctrine
91+
2. spec
92+
3. semantic
93+
4. surface
94+
95+
For git-warp, "surface" often means public API, CLI, or documentation surface
96+
rather than a GUI.
97+
98+
Local red while iterating is acceptable. Shared branches, pushes intended for
99+
review, and merge submissions should be green.
100+
101+
## Getting Started
102+
103+
1. Clone the repository
104+
2. Install dependencies: `npm install`
105+
3. Set up git hooks: `npm run setup:hooks`
106+
4. Run tests: `npm test`
107+
108+
## Git Hooks
109+
110+
This project uses custom git hooks located in `scripts/hooks/`. Run `npm run setup:hooks` to enable them.
111+
- Hooks are also auto-configured on `npm install` (no-op if not a git repo).
112+
- `pre-commit` runs eslint on staged JS files.
113+
- `pre-push` runs `npm run lint`, `npm test`, `npm run benchmark`, and the Docker bats CLI suite (`git-warp` commands).
114+
115+
### Pre-commit Hook
116+
117+
The pre-commit hook runs ESLint on all staged JavaScript files. If linting fails, the commit is blocked.
118+
119+
To fix lint errors:
120+
```bash
121+
npx eslint --fix <files>
122+
```
123+
124+
To bypass temporarily (use sparingly):
125+
```bash
126+
git commit --no-verify
127+
```
128+
129+
## Code Style
130+
131+
- ESLint enforces code style. Run `npx eslint .` to check.
132+
- Use template literals instead of string concatenation
133+
- Always use curly braces for if/else blocks
134+
- Keep functions focused and avoid deep nesting
135+
136+
## Running Tests
137+
138+
```bash
139+
npm test # Run all unit tests (Docker)
140+
npm run test:local # Run unit tests without Docker
141+
npm test -- <pattern> # Run specific tests
142+
143+
# Multi-runtime test matrix (Docker)
144+
npm run test:node22 # Node 22: unit + integration + BATS CLI
145+
npm run test:bun # Bun: API integration tests
146+
npm run test:deno # Deno: API integration tests
147+
npm run test:matrix # All runtimes in parallel
148+
```
149+
150+
### No-Coordination Invariant
151+
152+
The no-coordination regression suite is non-negotiable for multi-writer safety.
153+
Ensure `test/unit/domain/WarpGraph.noCoordination.test.js` passes before submitting changes.
154+
155+
## Pull Requests
156+
157+
1. Create a feature branch from `main`
158+
2. Make your changes with clear commit messages
159+
3. Keep commits documentation-atomic: when a change affects shipped behavior, public surface, or backlog status, update `CHANGELOG.md` and the roadmap/backlog docs in the same commit.
160+
4. When a `BACKLOG/` item becomes active, promote it into `docs/design/` before implementation. When roadmap work completes, reconcile `ROADMAP.md` and `docs/ROADMAP/COMPLETED.md` in the same commit.
161+
5. Ensure all tests pass: `npm test`
162+
6. Ensure linting passes: `npx eslint .`
163+
7. Submit a PR with a clear description

SECURITY.md renamed to .github/SECURITY.md

File renamed without changes.

‎.github/maintainers/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Maintainer docs
2+
3+
This directory contains contributor-facing process and governance docs for
4+
`git-warp`.
5+
6+
Use these docs when you are working on the repository itself rather than
7+
evaluating or using the product API.
8+
9+
## Maintainer entrypoints
10+
11+
- [Contributing guide](../CONTRIBUTING.md)
12+
Development workflow, release expectations, and repo operating rules.
13+
- [Documentation style guide](documentation/style-guide.md)
14+
Writing standards, audience model, and documentation information
15+
architecture.
16+
- [Security policy](../SECURITY.md)
17+
Reporting path and supported-version security expectations.
18+
19+
## Related project artifacts
20+
21+
- [Backlog](../../BACKLOG/README.md)
22+
Active and promoted work tracked as repo-operating artifacts.
23+
- [Design notes](../../docs/design/)
24+
Governing design docs for promoted backlog items and active cycles.
25+
- [Retrospectives](../../docs/retrospectives/)
26+
Slice close-out records and design-alignment audits.

0 commit comments

Comments
 (0)