DEVX-167: docs: add dependency-graph, deployment-coordination, and skill-creation skills

Co-authored-by: emil User <emil.simeonov@tutanota.com>
2026-09-05 14:16:52 +00:00
parent c6bd4e8f63
commit 4638e334b5
4 changed files with 431 additions and 0 deletions
@@ -0,0 +1,90 @@
+# deployment-coordination
+
+How devx releases propagate to downstream repos. devx is the base
+package — all other repos pin it. A devx release must complete before
+consumers can bump.
+
+## When to Invoke
+
+Invoke this skill when:
+- Changes to devx affect downstream repos (grm, sso-bridge, infra)
+- Preparing a devx release that other repos depend on
+- Verifying downstream repos have bumped to the latest devx version
+- Coordinating a multi-repo change that starts in devx
+
+## Prerequisites
+
+- devx repo at `/home/emo/dev/ideas/oblachno/devx`
+- `.env` with `DEVELOPER_GITEA_API_TOKEN`
+- See `dependency-graph` skill for the full ecosystem map
+
+## What devx Produces
+
+devx publishes a Python package to the Gitea PyPI registry. Downstream
+repos pin it:
+```toml
+"devx @ git+https://git.oblachno.oblachno.fyi/oblachno-oss/devx.git@vX.Y.Z"
+```
+
+## Release Flow
+
+1. PR merged to master
+2. Post-merge workflow runs `devx.ci.release` — classifies changes
+3. If user-facing changes: git-cliff bumps version, creates tag, pushes
+4. `devx.ci.publish` builds and publishes to Gitea PyPI registry
+5. Downstream repos must bump their pinned devx version
+
+## Downstream Consumers
+
+| Repo | Pin location | Auto-bump? |
+|------|-------------|------------|
+| grm | `pyproject.toml` | No — manual |
+| sso-bridge | `pyproject.toml` | No — manual |
+| infra | `pyproject.toml` | No — manual |
+
+devx does NOT auto-create dependency PRs in downstream repos. Bumping
+is manual: create a PR in each downstream repo to update the pinned
+version.
+
+## Coordinating a devx Change
+
+When a change to devx affects downstream repos:
+
+1. **Merge devx PR** — wait for post-merge publish to complete
+2. **Verify publish** — check the new tag exists:
+   ```bash
+   curl -sS -H "Authorization: token $DEVELOPER_GITEA_API_TOKEN" \
+     https://git.oblachno.oblachno.fyi/api/v1/repos/oblachno-oss/devx/releases/latest \
+     | python3 -c "import json,sys; print(json.load(sys.stdin).get('tag_name','?'))"
+   ```
+3. **Bump downstream repos** — for each repo (grm, sso-bridge, infra):
+   - Update `devx @ ...@vX.Y.Z` in `pyproject.toml`
+   - Run `make setup` to install the new version
+   - Run `make pytest-cov` to verify compatibility
+   - Create and merge a PR
+4. **Verify infra deploys** — after infra bumps, verify staging deploy
+   picks up the new devx version
+
+## State Verification
+
+Before starting a devx change, verify current state:
+```bash
+# Current devx version
+grep '__version__' /home/emo/dev/ideas/oblachno/devx/src/devx/__init__.py
+
+# What each repo pins
+for repo in grm sso-bridge infra; do
+  echo -n "$repo pins: "
+  grep 'devx @' /home/emo/dev/ideas/oblachno/$repo/pyproject.toml | grep -oP 'v[\d.]+'
+done
+```
+
+If pins are inconsistent across repos, bump them to the latest published
+version before starting new work.
+
+## Common Mistakes
+
+- Merging a devx PR and immediately merging downstream PRs without
+  waiting for the publish job to complete
+- Forgetting to bump infra (it has the most complex deploy pipeline)
+- Bumping only one downstream repo when the change affects all three