Docs: update CONTRIBUTING.md for Node 22+/pnpm 11+ requirements and modular namespace i18n architecture
Open
Beginner friendly
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 59.6k
- Forks
- 5.8k
- Avg merge
- 1d 22h
- Merged PRs (30d)
- 49
Description
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 rootpackage.jsonspecifies"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.apispecifiespython:3.12.10-alpine. - Package Manager:
pnpm(version 11+ via Corepack) is not listed inRequirements, despite being the required package manager for the monorepo. - Setup instructions: The step-by-step instructions omit
pnpm installbeforepnpm dev, causing missing binary/module errors if contributors run steps manually or ifsetup.shencounters issues.
- Node.js: Listed as
-
Translation & i18n Contribution Guide (
packages/i18n):- The docs describe an obsolete architecture where translations live in a single monolithic
translations.jsonalongside acore.json. - In reality, translations are organized into 28 feature-based namespace files (e.g.,
common.json,auth.json,work-item.json,project.json) governed byNAMESPACESinpackages/i18n/src/constants/namespaces.ts. - Step 3 instructs contributors to modify a nonexistent
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.
- The docs describe an obsolete architecture where translations live in a single monolithic
Proposed Changes
- Update
CONTRIBUTING.mdRequirements to specify Node.js>=22.22.0, Python 3.12+, andpnpm >=11(orcorepack enable pnpm). - Clarify manual setup steps to explicitly include
pnpm installprior to runningpnpm dev. - Update the i18n architecture guide in
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).
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with CONTRIBUTING.md, then verify the requirements against root package.json and apps/api/Dockerfile.api. Read packages/i18n/src/constants/namespaces.ts and packages/i18n/src/core/instance.ts to confirm the namespace files and dynamic loading guidance. Done means CONTRIBUTING.md accurately documents setup requirements, pnpm install, the namespace architecture, and the language-addition steps.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- django, node.js, python, typescript
- Domain
- developer-experience, documentation, internationalization
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 86/100