3.3 KiB
Contributor instructions
Project baseline
Read README.md and docs/codebase-index.md before editing. This is a static, bilingual portfolio using native ES modules, CSS and JSON, with no npm dependencies. Use Node 22 or newer and run commands from the repository root.
Source ownership
- Edit projects in
content/projects/*.jsonand shared settings incontent/settings.json. Followdocs/content-editing.md. - Generate
content.jswithnpm run content,npm testornpm run build. Commit generated changes alongside their source; never hand-edit the module. - Keep Dutch and English text complete, project IDs stable, and repository links pinned to a reviewed revision.
- Projects default to the school repository in settings. For another repository, use the validated
repositoryobject and pass the project tosource(path, directory, project)in every renderer. Supported hosts aregithub.comandcodealvin.xyz; pins must be full lowercase commit SHAs. - Set bilingual
settingexplicitly for projects outside school year 2. Usechallenge: "—"for personal projects; the scaffold still defaults to school repository paths and does not supply a context override. - Record repository selections, reviewed pins and exclusions in
docs/repository-review.md. Keep unmapped source links separate from claims of exam evidence, and preserve recorded user exclusions when refreshing the selection. - Preserve explicit evidence gaps. Do not invent personal contributions, assessment results, test outcomes or deployment claims. Only change the source review date after actually reviewing the sources.
- UI copy and shared contribution/reflection placeholders also live in
app.js; metadata lives inindex.html. JSON is not a complete CMS. - Keep the static publication boundary: five public assets, no public editor or write API. If assets change, update the build, preview allowlist, Docker inputs and Nginx allowlist together.
- Do not commit
.env,dist/, logs, dependencies or private material. The build validates and stages exactly five public assets before replacingdist/; never add private files to publication output.
Checks and documentation
Run npm test, npm run build and git diff --check before committing. Use node --check for edited JavaScript files. For Docker changes, validate docker compose config --quiet; build and test the container when an engine is available. Report unavailable checks explicitly.
For rendering changes, check both languages, navigation, all project routes, evidence filtering, keyboard focus, mobile overflow and printing when affected. Existing unit tests use a minimal DOM stub and do not replace browser checks.
Keep README, content reference, codebase index and hosting instructions aligned with changes. Record actual checks and their date in docs/verification.md; distinguish historical results from checks repeated now. Existing PNG previews are historical references, not proof of current behavior.
Git and deployment
Inspect the working tree and preserve unrelated user changes. Review the diff and stage intended paths explicitly. Fetch before pushing; rebase unpublished commits only if needed and rerun affected checks after conflicts. Do not force-push shared history. Push when requested by the user; deployment is a separate operation and must not be reported as completed merely because a push succeeds.