# Contributing to kopular Kopular is a small component framework for [KopScript](https://github.com/TheKoppinator/kopscript) (`kopscript` on npm) — `Component`, `Router`, `Http`, `FormField`/`Validators`, structural directives, and the `kp new` scaffolding CLI. See `README.md` for the framework itself; this file is about working on Kopular's own source. ## Getting started ```bash npm install # pulls in kopscript as a devDependency npm run build # compiles src/*.ks -> src/*.js (compiled output is gitignored, not committed) npm test # runs test/*.test.ts against a real DOM via jsdom -- runs the build first (pretest) ``` `kopscript` is a real published dependency — you don't need `KopScript` checked out as a sibling directory to build or test this repo. If you *are* iterating on kopscript itself alongside a Kopular change, point `node_modules/kopscript` at your local `KopScript/dist` build to test against it before either side is published. ## What a good change looks like - **Almost everything in this framework is written in KopScript itself** (`src/*.ks`), not hand-written JS — the only hand-written files are `bin/kp.mjs`, `src/http_runtime.js`, and `src/testing.js`, each with a comment explaining why (filesystem/process orchestration, or a JS object-literal shape KopScript can't construct). Don't add a new hand-written `.js` file unless there's a similarly real reason — write it in `.ks` first. - **New hand-written `.js` files need their own `.gitignore` exception.** `.gitignore` ignores `*.js` broadly (compiled output isn't committed) with explicit `!src/whatever.js` entries for the real hand-written ones — a new hand-written file with no exception silently never gets committed. - **Real end-to-end tests, run against jsdom**, not just type-checked `.ks` — see `test/kopular.test.ts`'s `runKopularFixture` pattern. `kopular/testing`'s exported helpers (`runKopularApp`/`runKopularFixture`) are the same harness Kopular's own tests and KopularDemo's use; changes to framework behavior should be provable through them. - **Update `README.md` and `LLM.md` in the same change.** `LLM.md` is a dense, example-verified reference meant to be loaded directly into an LLM's context — every sample in it should compile today. - **Bump `package.json`'s version on every change that ships**, including docs-only ones — publishing is automatic on push to `main`, gated on the local version differing from what's published to npm. If a change needs a newer `kopscript` than what's currently published, bump the `devDependencies.kopscript` range as a tracked TODO and sync `package-lock.json` once that version is actually live (`npm ci` will fail loudly until then — that's expected, not a bug in the change itself). - **Real semver, as of 1.0.0** — see `CHANGELOG.md`'s own header for the full policy. In short: a bug fix is a patch, new/additive surface is a minor, anything that changes what already-working code does (or removes/renames something public) is a major and needs a real conversation first, not a same-PR decision. ## Before opening a PR ```bash npm test # must be green (builds first automatically via pretest) npm run build # must compile clean ``` ## Looking for something to work on? See `GOOD_FIRST_ISSUES.md` — real, verified gaps with file:line pointers to where each one lives, not a generic wishlist. ## Reporting bugs / proposing features Open an issue in this repo (or email the address in `SECURITY.md`). A minimal `.ks` repro (or a failing test) is the fastest path to a fix — this project doesn't have a formal triage process yet.