Development

Canonical repository: https://github.com/codepetca/zero, integration branch main. Publish through a reviewed feature PR only with user authorization. Never deploy, push, publish or change account credentials without explicit authorization. There is no required external service or private environment file for local app work. Keep one writer per component and inspect changes before integration.

Use Node.js 22+ for developer tooling. Students use a supported JDK 17+ and VS Code; Git 2.31+ is needed for authenticated uploads. Students do not need Node.js or global Maven.

npm ci
npm run prepare:starter
npm run check
npm test
python3 scripts/verify-examples.py
npm run package
npm run verify:kit
npm run verify:framework

Java build and finite GUI checks are documented in the student starter. Builds use the pinned project wrapper; do not require students to install Maven or Gradle globally. Packaging creates local artifacts in dist/ and does not publish them. A published kit version is immutable: packaging refuses to overwrite it. Set a new local kit/extension version before building the next release. Existing public asset URLs/checksums remain pinned to their release. See release preparation and publication for the one-command publisher and its read-only CI preparation workflow.

Framework contributors edit framework/src/main/java/zero/. Prepare assembles ignored readable copies into the starter; checks/packaging prepare them too. An edited generated copy is preserved and stops preparation rather than being silently overwritten. Move intended upstream edits into the canonical framework or save them elsewhere before preparing again. The extracted student kit needs no preparation tooling. verify:framework uses a disposable starter and the maintainer harness in framework/checks/.

The selected front-page design is recorded in design/WEBSITE.md. The Next.js package has its own pinned dependencies and lockfile:

npm ci --prefix website
npm run typecheck --prefix website
npm test --prefix website
npm run build --prefix website

The current published kit uses verified GitHub release links. To preview a new local version, set its release metadata to local, run npm run package, then start the website from the root with:

ZERO_LOCAL_DOWNLOADS=1 npm run dev --prefix website

An unpublished asset without the local preview flag leads to its availability explanation on Learn more. Published assets keep their verified public links even with the flag enabled. No guessed public release URL is shown. The website prepares canonical docs/release content before development and build; generated snapshots and caches are ignored. Start here before later Vercel setup: Root Directory website/, with repository sources outside that directory included for build preparation. See the website plan.

Open this repository in VS Code and launch the Zero Extension debug configuration (F5) to use an extension development host. The host opens student-template/. Use Zero: Show Sidebar if needed. Test a local VSIX in an isolated VS Code user-data/extensions directory before normal installation.

Check the two startup paths, useful lifecycle errors, JavaFX event/state behavior, explicit object updates, drawing/input and shutdown. Preserve text control input when a sketch includes controls. Check that quiz and practice copy the canonical ScoreDisplay unchanged and that the caption constructor preserves existing apps. Study checks should exercise retries, duplicate scoring, advance/completion and restart, including a second run. Keep question data in ordinary Java objects.

Test project resolution, Git URL parsing/root guards, simulation side effects, native authentication states, review cancellation, account/session drift and credential isolation. Git/authentication tests use mocks and intercept transport; no real sign-in, upload or account/configuration changes are authorized by a local development check. Simulation stays the default. Signing in is separate from manually configuring per-repository Git commit identity.

The individual workflow adds reviewed start/finish plans. Test real local Git against injected disposable bare remotes: baseline, branch progress, main updates, pause/run/review after updates, preserved conflict state, failed push/retry and safe optional local branch deletion. Never redirect production transport through Git URL rewriting or introduce a real GitHub test. Simulation must skip saves, auth, network and Git mutations for Upload, Start and Finish. Native transport accepts only the exact reviewed HTTPS destination and narrow push/head-query/ SHA-pinned-fetch commands; session/root/rewrite checks remain required. UI tests cover cancellation, operation serialization, source-control guidance and drift.

Run git diff --check before handoff. Record checks actually performed in VERIFICATION.md; configuration/ZIP checks alone do not prove editor behavior or a real upload. Physical Windows/Linux and novice pilots remain pending. Use CLASSROOM-PILOT.md for a teacher-authorized trial.

Pin JavaFX, Maven wrapper/distribution and npm tooling; commit the npm lockfile. Keep generated artifacts and caches out of Git. The framework source ships inside the starter so students can inspect and edit it. SimpleApp builds ordinary JavaFX interfaces; SketchApp adds canvas animation. Keep explicit object updates and ordinary controls/layouts available rather than introducing a larger engine.

Start with one readable helper, example or useful error. Put alternative examples outside compiled src/ and document exactly which files students copy. For shared components, start from examples/shared/ScoreDisplay.java, test exact-copy reuse in quiz, practice and study, retaining the caption enhancement and existing no-argument constructor. Include meaningful behavior checks and a short explanation another student can follow; seek review before cohort adoption.

Advanced contributions may introduce Java packages, interfaces or JavaFX properties when a concrete app needs them. Versioned Maven libraries, the portable Workshop and contribution admission are documented in COMPONENTS.md. Public discovery and verified downloads are available at Zero Community. Original Zero code uses MIT; upstream wrapper licenses/notices retain their own terms.

The sibling ../zero-community checkout has its own source, Maven library, release-cycle proof and admission scripts. Its canonical source remote is codepetca/zero-community. From the directory containing your Zero checkout, obtain the sibling with git clone https://github.com/codepetca/zero-community.git. Use the actual local checkout path with the commands below. GitHub hosts source. Historical verification uses local artifacts; public preparation is a separate step below.

npm run prepare:starter
python3 ../zero-community/scripts/verify-release-cycle.py --zero-root "$PWD"
node scripts/prepare-component-workshop.mjs ../zero-community
node scripts/verify-components.mjs

verify-components.mjs checks add/update/revert with the actual extension engine and real Maven/JavaFX in a disposable project whose path includes spaces. It requires the release proof's cache for third-party downloads; tested community coordinates start absent. Generated evidence stays in .verification/. This historical preparation writes component-legacy-catalog.json only; it does not prepare the current Workshop. Prepare the public candidate below before running or packaging it.

Zero 0.5.1 and later support current MIT catalogs in the installed extension. The immutable published 0.5.0 VSIX predates MIT catalog support and continues to support historical UNLICENSED catalogs. Contributors can use the current extension source in a VS Code extension development host (F5).

Community catalog selection is explicit and local in Zero's view title (…) menu. The extension edits only managed POM blocks through the native undoable editor, refuses unsaved/drifted documents and preserves Java source. Add pins a version; Update/Revert confirm and run the app. Try uses trusted packaged example source and a separate temporary Maven cache, cleaned when its owned task ends. Maven remains the resolver; normal project runs use ordinary Maven settings/cache.

Candidate compilation runs trusted local Java in the Workshop process with normal permissions; it is not an untrusted-submission sandbox. Admission validates packets without executing code. GitHub CI builds/checks source PRs with read-only permissions. A trusted owner-side helper checks independent current-head human maintain/admin approval and matching CI; an exported packet cannot establish that authority. The AI advisory interface has no live provider configured. See the community contribution/AI docs.

Public discovery defaults to https://zero.codepet.ca/community/catalog.json. The authored download source is the generated, reviewed release/community.json snapshot copied from source-bound community receipts. The website's fixed Maven gateway accepts only manifest paths and verifies full bounded bytes before serving. Components remain pinned; HTTPS POMs work on another machine without account access. A remembered local catalog can be selected explicitly through the components menu.

Community maintainers prepare a clean committed 0.1.2 candidate with python3 scripts/prepare-public-release.py --zero-root ../zero in zero-community. The candidate preparer requires a clean committed community checkout and refuses to replace an existing candidate output. Reuse verified output for that exact revision, or use a fresh disposable checkout to verify preparation again. Then prepare, run and package the portable Workshop from Zero (the shipped Workshop files must also be committed):

node scripts/prepare-component-workshop.mjs ../zero-community --public
node scripts/run-component-workshop.mjs
npm run package:components

Run opens the native Workshop until you close it. Its -Dzero.workshopCheck=true JVM option runs the finite native-window harness. Packaging creates dist/zero-community-workshop-0.1.2.zip, containing source, Workshop and its pinned local artifacts/catalog. Extract the complete archive and open its component-workshop/ subfolder. Students use the bundled Maven wrapper; they do not need maintainer Node/Python tooling.

Preparation is local and cannot accept or publish. Verify source PRs, CI and independent review before intentionally publishing the exact release bytes. Import actual published asset URLs/sizes/SHA256s into the reviewed website snapshot; never replace an existing coordinate or rebuild historical fixtures with new notices. A public patch appends its version while retaining previously published records. Existing GitHub maintain/admin users own human acceptance; unreviewed work waits. No CI publishing credentials or AI acceptance is configured.