Contributing

Public contributions in this documentation scope belong to:

• Pinchana/pinchana-api and its public submodules;
• Pinchana/pinchana-web;
• Pinchana/pinchana-docs.

Private or closed-source clients are intentionally outside this documentation and contribution guide.

API contributions

Clone the parent repository with submodules and make service code changes inside the owning submodule.

git clone --recurse-submodules https://github.com/Pinchana/pinchana-api.git

Run that submodule’s tests/checks, then commit and push the submodule before updating its parent pointer. A parent PR must not point at a commit unavailable from the submodule’s public remote.

When changing a module’s URL coverage, runtime port, environment, image, or networking, update every coordinated parent location (config/modules.yaml, Compose, .env.example, workflow mappings, and docs) in the same change set.

Keep API v1 normalized. New platform fields should not automatically become top-level public schema additions if they can be represented by the existing source/content/author/media/music/engagement/safety/link model.

Web contributions

git clone https://github.com/Pinchana/pinchana-web.git
cd pinchana-web
bun install --frozen-lockfile
bun run test
bun run lint
bun run build

Preserve the server/client trust boundaries:

• API origin and session bearer stay server-side;
• no machine API key in browser code;
• custom origins require verified project certificates;
• Cookie Vault plaintext stays inside the browser/ephemeral worker boundary;
• monitoring remains deployment-gated and performance telemetry opt-in;
• authenticated media stays behind same-origin routes.

Pinchana Web is AGPL-3.0-only; contributions are made under that repository’s license.

Translation contributions

Translation changes are ordinary PRs to pinchana-web. Do not modify the English source strings inside translated entries. Preserve ICU variables/tags exactly and edit only translated values unless the source English message itself is intentionally changing.

See Translation guide.

Documentation contributions

git clone https://github.com/Pinchana/pinchana-docs.git
cd pinchana-docs
bun install --frozen-lockfile
bun run check
bun run build

Verify behavior from current API/Web implementation before writing commands/defaults. Avoid duplicating long configuration instructions across multiple pages; link to the canonical environment/operations reference.

Security-sensitive changes

Do not put real secrets, cookies, user-submitted URLs from private reports, access/refresh tokens, rendered production Compose environments, or private keys into issues/PRs/tests/docs.

For vulnerabilities that would expose credentials, bypass browser/custom-instance trust, escape DLP isolation, or permit arbitrary server-side requests/commands, use the project’s private security-reporting path rather than publishing exploit details in a normal issue.

Pull request notes

A useful PR description states:

• affected project/service;
• user-visible or API-contract impact;
• configuration/deployment changes;
• security/trust-boundary changes;
• exact verification commands run;
• whether live-platform testing was performed or intentionally skipped.

For API parent PRs, also call out updated submodule pointers. For release-related changes, do not manually invent a tag/version workflow that conflicts with scripts/version.py and scripts/publish_release.py.