Problem Description
In CONTRIBUTING.md, two key sections contain outdated guidance that causes friction for new contributors:
-
Environment Requirements & Local Setup:
- Node.js: Listed as
Node.js version 20+, but root package.json specifies "engines": { "node": ">=22.22.0" }. Attempting setup on Node 20 triggers engine mismatch warnings or failures.
- Python: Listed as
Python version 3.8+, but Python 3.8 is end-of-life and unsupported by modern Django; apps/api/Dockerfile.api specifies python:3.12.10-alpine.
- Package Manager:
pnpm (version 11+ via Corepack) is not listed in Requirements, despite being the required package manager for the monorepo.
- Setup instructions: The step-by-step instructions omit
pnpm install before pnpm dev, causing missing binary/module errors if contributors run steps manually or if setup.sh encounters issues.
-
Translation & i18n Contribution Guide (packages/i18n):
- The docs describe an obsolete architecture where translations live in a single monolithic
translations.json alongside a core.json.
- In reality, translations are organized into 28 feature-based namespace files (e.g.,
common.json, auth.json, work-item.json, project.json) governed by NAMESPACES in packages/i18n/src/constants/namespaces.ts.
- Step 3 instructs contributors to modify a nonexistent
private importLanguageFile(language: TLanguage) method; packages/i18n/src/core/instance.ts uses resourcesToBackend to dynamically import ../locales/${language}/${namespace}.json, requiring zero import code changes when adding a new language.
Proposed Changes
- Update
CONTRIBUTING.md Requirements to specify Node.js >=22.22.0, Python 3.12+, and pnpm >=11 (or corepack enable pnpm).
- Clarify manual setup steps to explicitly include
pnpm install prior to running pnpm dev.
- Update the i18n architecture guide in
CONTRIBUTING.md to reflect the 28 namespace JSON files, explain how keys map to namespaces, and provide the correct steps for adding a new language (updating TLanguage, SUPPORTED_LANGUAGES, and creating the namespace JSON files without needing nonexistent import methods).
Problem Description
In
CONTRIBUTING.md, two key sections contain outdated guidance that causes friction for new contributors:Environment Requirements & Local Setup:
Node.js version 20+, but rootpackage.jsonspecifies"engines": { "node": ">=22.22.0" }. Attempting setup on Node 20 triggers engine mismatch warnings or failures.Python version 3.8+, but Python 3.8 is end-of-life and unsupported by modern Django;apps/api/Dockerfile.apispecifiespython:3.12.10-alpine.pnpm(version 11+ via Corepack) is not listed inRequirements, despite being the required package manager for the monorepo.pnpm installbeforepnpm dev, causing missing binary/module errors if contributors run steps manually or ifsetup.shencounters issues.Translation & i18n Contribution Guide (
packages/i18n):translations.jsonalongside acore.json.common.json,auth.json,work-item.json,project.json) governed byNAMESPACESinpackages/i18n/src/constants/namespaces.ts.private importLanguageFile(language: TLanguage)method;packages/i18n/src/core/instance.tsusesresourcesToBackendto dynamically import../locales/${language}/${namespace}.json, requiring zero import code changes when adding a new language.Proposed Changes
CONTRIBUTING.mdRequirements to specify Node.js>=22.22.0, Python 3.12+, andpnpm >=11(orcorepack enable pnpm).pnpm installprior to runningpnpm dev.CONTRIBUTING.mdto reflect the 28 namespace JSON files, explain how keys map to namespaces, and provide the correct steps for adding a new language (updatingTLanguage,SUPPORTED_LANGUAGES, and creating the namespace JSON files without needing nonexistent import methods).