Contributing to InKCre
InKCre welcomes code, documentation, design, and ecosystem contributions. Start by identifying the owner of the change; then follow that owner's current development and review contract.
If you want to connect another service without changing InKCre itself, use the ecosystem developer guide instead. Your Extension can live in your own repository; it does not need to become a Core contribution.
There is no copied, universal setup or contribution procedure. Toolchains and commands
belong to the repository that runs and verifies them.
Find a useful change
Use the organization searches for good first issue and help wanted. An empty result means no task has currently been qualified for that label; it is not an invitation to guess at an untracked change. For another proposal, open an issue in the owning repository before a large implementation and describe the user outcome, affected area, and how it could be verified. Report suspected vulnerabilities privately through that repository's SECURITY.md instead.
Choose the change owner
| Change | Start here |
|---|---|
| Product purpose, behavior, or shared vocabulary | InKCre/docs → 10-prd/** |
| Cross-unit state, topology, or interoperability | InKCre/docs → 20-product-tdd/** |
| Hub/Spoke shared-document workflow | InKCre/docs → 00-meta/** |
| Core runtime, migrations, or database lifecycle | InKCre/impl-py |
| Web client or browser extension | InKCre/impl-ts |
| Design tokens or shared UI | InKCre/ui |
| Public website content or presentation | InKCre/docs → website/** |
If a change spans repositories, separate the shared contract from each repository's implementation instead of making one repository silently own the others.
Follow the selected repository
After choosing an owner:
- Fork the repository, branch from its current
main, and read its rootREADME.md,AGENTS.md, andCONTRIBUTING.mdwhen present. - Use the runtime and package manager pinned by that repository.
- Run its own formatter, checks, and tests.
- Push the branch to your fork and open a pull request against the owning repository.
- Follow its pull-request and review requirements until checks pass and conversations are resolved.
Useful entry points:
Setup and access boundaries
| Repository | First setup gate | Complete local evidence |
|---|---|---|
impl-py | Python and PDM versions checked by pdm run doctor; integration suites need a disposable PostgreSQL runtime | pdm run check, plus the repository-local integration or acceptance command for changed behavior |
impl-ts | pnpm install reads the private @inkcre/ui-web GitHub Package. Local contributors need a classic PAT with read:packages and package read access; follow the authentication instructions before install | pnpm check, plus the relevant browser E2E command |
ui | Install from the repository root; generated tokens, metadata, and skills must be current | pnpm check, plus visual or interaction review for affected Stories or a real consumer |
docs | Use the website toolchain pinned in website/ | The website contract, including link and build checks |
For impl-ts, a 401 or 403 during install is an access failure, not a source or lockfile defect. Do not commit a package token or add it to the repository .npmrc. Contributors who do not have package access cannot currently complete the normal local impl-ts setup; ask a maintainer to confirm whether the proposed task is suitable before investing in that path.
Submit a reviewable change
Use type(scope): summary for commit subjects and pull-request titles. The repository guide owns its stable scopes; choose the primary implementation area, not every package touched. A cross-project change may use a repository-level scope such as extensions, while the pull-request body and the repository's fragment or Changeset mechanism list every affected release project precisely.
Complete the pull-request template with the intended outcome, actual verification evidence, risk and rollback, delivery effects, and any stacked pull requests. External fork workflows require maintainer approval before read-only CI starts and receive no preview or production credentials. A maintainer may therefore need to approve CI or perform a trusted preview; do not work around that boundary by adding credentials to the branch. Passing review makes a change eligible to merge, but canonical publication and production delivery occur only from protected main.
Changes to shared truth
The docs repository is the Hub for durable product and cross-unit truth used across InKCre repositories. For a shared-truth change:
- Update and publish the canonical Hub owner.
- Update each consuming Spoke's shared reference.
- Apply Spoke-local implementation or documentation changes.
Keep those steps in separate commits so ownership and rollback remain visible. The Hub/Spoke operations contract contains the repository-specific workflow.
Website contributions
This website is a reader-oriented projection, not a second owner for product or cross-unit contracts. Public-only About facts belong here; product and architecture summaries must continue to agree with their Hub owners.
The website README owns its route, authoring, build, and publication contract.