mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-09-30 12:39:42 +02:00
Aamer Akhter
e60b5a8a2c
resolveGitHooksDir now returns a directory only when it is the repo's own <git-common-dir>/hooks (compared on canonical paths), so a core.hooksPath elsewhere, global or repo-local, is never written to by postinstall, while a core.hooksPath pointing back at the repo's own .git/hooks still resolves. The pre-push hook skips with a one-line notice when a pushed ref is not the checked-out HEAD (tags peeled) or when git status shows uncommitted or untracked changes under a path the checks read (src, config, scripts, test, package.json, package-lock.json, install.sh), since the checks read the working tree rather than the pushed commit. Also: honest timing (~10-40s instead of ~15s), CLAUDE.md Session Safety note on CODEMAN_SKIP_PREPUSH for another session's WIP, 14 (not 9) Playwright tests, and a note that the browser-excludes check only sees direct imports.
126 lines
5.9 KiB
Markdown
126 lines
5.9 KiB
Markdown
# Contributing
|
|
|
|
The full guide lives in
|
|
[CONTRIBUTING.md](https://github.com/Ark0N/Codeman/blob/master/.github/CONTRIBUTING.md).
|
|
This page is the short orientation, plus how to fix a page in this wiki.
|
|
|
|
## Where things go
|
|
|
|
| You have | Send it to |
|
|
| --------------------------- | ---------------------------------------------------------------------------------------------- |
|
|
| A bug | An [issue](https://github.com/Ark0N/Codeman/issues), with OS, install method, browser, and which CLI the session was running. |
|
|
| A question or setup problem | [Discussions](https://github.com/Ark0N/Codeman/discussions). |
|
|
| An idea | [Ideas](https://github.com/Ark0N/Codeman/discussions/categories/ideas), where it gets voted on. |
|
|
| A small fix | Straight to a PR. |
|
|
| A bigger feature | An issue or Discussion first, then build once the design has a nod. |
|
|
| A security problem | Never a public issue. See [SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md). |
|
|
|
|
Issues usually get a response within a day, and every release credits its contributors and
|
|
bug reporters by name.
|
|
|
|
## Dev setup
|
|
|
|
```bash
|
|
git clone https://github.com/Ark0N/Codeman.git
|
|
cd Codeman
|
|
npm install # postinstall builds the vendored xterm addon bundles
|
|
npm run dev # http://localhost:3000
|
|
```
|
|
|
|
Requirements: Node 22+, tmux, and at least one agent CLI on your PATH.
|
|
|
|
The frontend is plain JavaScript with no bundler in dev: edit a `.js` or `.css` file and
|
|
reload. The exception is `index.html`, which is read once at server start, so markup changes
|
|
need a restart.
|
|
|
|
## Before you push
|
|
|
|
CI runs all of these, so running them locally saves a round trip:
|
|
|
|
```bash
|
|
npm run typecheck
|
|
npm run lint
|
|
npm run format:check
|
|
npm run check:frontend-syntax
|
|
npm run check:browser-excludes
|
|
npm test -- test/<file>.test.ts # one file, the normal way
|
|
npm run test:ci # the full CI sweep
|
|
```
|
|
|
|
`npm install` installs a `pre-push` git hook that runs the static checks above (about 10-40s,
|
|
machine-dependent) and blocks a push that would fail them. It skips itself when you push
|
|
something other than the checked-out HEAD, or when the tree has uncommitted changes the
|
|
checks would read. Skip it once with `CODEMAN_SKIP_PREPUSH=1 git push`; a
|
|
`pre-push` hook of your own is never overwritten.
|
|
|
|
**Never run bare `npm test`.** The default configuration includes browser-driven Playwright
|
|
suites that need a live server, Chromium, and environment-specific baselines; they hang or
|
|
fail on a normal machine. `test:ci` is the honest "run everything".
|
|
|
|
Tests are tmux-safe by design: under vitest the tmux layer becomes an in-memory mock, so
|
|
tests cannot touch real sessions. If you add a test that binds a port, pick a unique one at
|
|
3150 or above, and never 3000.
|
|
|
|
## Finding your way around
|
|
|
|
- Every source file opens with a `@fileoverview` block. Read it before the file; it is the
|
|
map.
|
|
- [`CLAUDE.md`](https://github.com/Ark0N/Codeman/blob/master/CLAUDE.md) at the repo root is
|
|
the densest architecture primer there is. It is written for AI coding agents, but its
|
|
invariants apply identically to humans, and most review feedback traces back to something
|
|
already written there.
|
|
- [`docs/architecture-invariants.md`](https://github.com/Ark0N/Codeman/blob/master/docs/architecture-invariants.md)
|
|
holds the deep mechanisms and the history behind each rule.
|
|
|
|
## Good first contributions
|
|
|
|
- **A theme skin.** A skin is four things kept in sync, and a static test checks the sync, so
|
|
if the test passes your skin works.
|
|
- **A language.** The i18n module is dependency-free, English is canonical, and Simplified
|
|
Chinese is a complete example to copy.
|
|
- **Docs.** If you got stuck and then figured it out, the sentence that would have unstuck
|
|
you is a pull request.
|
|
- Anything labelled
|
|
[good first issue](https://github.com/Ark0N/Codeman/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
|
|
|
|
Worth discussing first: new CLI backends, and real-device testing reports, especially
|
|
mobile, which always find things emulation cannot.
|
|
|
|
## PR expectations
|
|
|
|
- One change per PR. Small and focused reviews fast; a grab bag stalls.
|
|
- Target `master`.
|
|
- **Keep your branch mergeable.** A PR with conflicts silently gets no CI runs at all, which
|
|
is a GitHub quirk rather than a Codeman one. Rebase when conflicts appear.
|
|
- Include or update tests when you change behaviour.
|
|
- Do not bump versions or edit the changelog; releases are handled after merge.
|
|
- AI-assisted contributions are welcome, with one condition: understand what you are
|
|
submitting, and actually run it. "The model said it works" is not a test.
|
|
|
|
## Fixing this wiki
|
|
|
|
These pages are generated from
|
|
[`docs/wiki/`](https://github.com/Ark0N/Codeman/tree/master/docs/wiki) in the main
|
|
repository, and pushed here automatically when master changes.
|
|
|
|
**Editing a page in the browser will be overwritten by the next sync.** Send a pull request
|
|
against `docs/wiki/` instead. It is plain markdown, and a documentation PR is a genuinely
|
|
useful contribution.
|
|
|
|
Conventions for wiki pages:
|
|
|
|
- Links between pages use the wiki form: `[Remote Access](Remote-Access)`, no `.md`.
|
|
- Links into the repository are absolute `https://github.com/Ark0N/Codeman/blob/master/...`
|
|
URLs.
|
|
- Images are referenced from the main repository over raw URLs rather than being copied into
|
|
the wiki.
|
|
- Say what the default is, especially when it is off. Most of Codeman is opt-in.
|
|
- Label Claude-only behaviour every time it appears. Nine of the ten run modes are not
|
|
Claude.
|
|
|
|
## Conduct
|
|
|
|
Be kind, be direct, assume good faith. Report unacceptable behaviour privately via the
|
|
contact in
|
|
[SECURITY.md](https://github.com/Ark0N/Codeman/blob/master/.github/SECURITY.md).
|