CremindContributing to Cremind
How the Cremind monorepo is organized, the two maintainer roles, and the path from a clean checkout to a merged PR.
Cremind is open source, early (version 0.0.1), and community-driven. Contributions of every size are welcome — bug fixes, new Agent Skills, docs corrections, and larger features. This section walks you from a clean checkout through development, testing, and the release pipeline.
Cremind is at 0.0.1. The architecture is settling, interfaces still move between versions, and there are sharp edges. That is exactly when contributions have the most leverage — if something is confusing or broken, fixing it helps everyone who arrives after you.
One repo, one branch, one PR
Cremind's Python backend and its Vue 3 + Electron UI live together in a single repository. A feature that touches both halves ships from one branch and one PR — you don't coordinate across repos, and the backend and UI versions can never drift apart.
| Path | What lives here |
|---|---|
app/ | Python backend — Starlette server, CLI, agent, tools, skills, channels. |
app/__version__.py | The single source of truth for the project version. |
app/static/ui/ | Built SPA artifact (gitignored). Populated by scripts/build_ui.sh. |
ui/ | Vue 3 + Vite + Electron source. |
ui/src/ | Vue components, stores, services. |
ui/electron/ | Electron main process + preload. |
scripts/build_ui.sh | Builds the SPA into app/static/ui/ so the wheel ships with it. |
scripts/sync_ui_version.py | Mirrors app/__version__.py into ui/package.json. |
.github/workflows/ | pr.yml, release-rc.yml, release-prod.yml. |
pyproject.toml | Python deps + hatch config. |
Two maintainer roles
Releases are coordinated by two roles. Most contributors interact with them rather than holding them.
- Core Maintainer — owns the version line. Decides which PRs land in the next release, assigns each one a release-candidate index (
rc1,rc2, …), and ultimately bumpsapp/__version__.pyand cuts the production tag. - Component Maintainer — owns the per-PR work. Cuts test (dev-channel) releases from the PR branch tip, iterates until the change is validated on a real machine, and pushes fixes to the PR branch.
For a single PR the two collapse naturally: one person assigns rc1, ships dev releases until validated, merges, then bumps and tags. See Releasing for the full worked example.
The contribution loop
git checkout main ; git pull
git checkout -b my-feature
# edit anywhere under app/ or ui/src
git push -u origin my-featureOpen a pull request against main. The PR CI (pr.yml) runs three jobs in parallel — backend (pytest), ui (vue-tsc + web bundle), and smoke-build (a wheel plus a Linux Electron AppImage, uploaded as artifacts so reviewers can install and try the build). All three must pass before merge.
Cremind uses merge-commit for every PR — not rebase, not squash. This keeps the original feature commits reachable from main, which the release pipeline depends on. Releasing explains why.
Where to go next
Dev setup
The two-terminal loop: backend on :1112, Vite on :1515, with hot reload.
Testing & CI
The three commands the PR CI runs, and how to run them locally.
Dev-channel install
Exercise the real installer scripts against your checkout.
Releasing
RC dev tags, merge-commit, and the production release gates.
Versioning
The single source of truth and how it flows to PyPI, npm, and Docker.
Schema migrations
Autogenerate, hand-review, and the additive-then-destructive rule.
The canonical, always-current versions of the developer docs live in the repo at CONTRIBUTING.md and RELEASING.md. These pages summarize and explain them; when in doubt, the repo wins.