Contributing to n2words

Quick Start

git clone https://github.com/YOUR_USERNAME/n2words.git
cd n2words
npm install
npm test

Requirements: Node.js >=22, Git

Package manager: examples use npm, but pnpm and bun work too — scripts run through node --run, so pnpm run <script> / bun run <script> behave the same. package-lock.json is the committed lockfile; pnpm/bun/yarn lockfiles are gitignored.

Pull Request Process

1. Create a feature branch: git checkout -b feat/add-pt-BR
2. Make changes, then run npm run lint && npm test
3. Commit using Conventional Commits: git commit -m "feat(ko-KR): add Korean"
4. Push and open PR targeting main

Common commit formats:

• feat(pt-BR): add Brazilian Portuguese — new language
• fix(en-US): correct thousand handling — language-specific fix
• perf(ja-JP): optimize BigInt handling — performance improvement
• refactor(core): simplify exports — code refactoring
• docs: update README — documentation

Scopes use BCP 47 language codes — one (en-US), comma-separated (az-AZ,tr-TR), or a bare primary subtag for a variant family (en, es) — or project areas (core, types, umd). See .commitlintrc.mjs for details.

Adding a New Language

npm run lang:add -- <code>   # e.g., ko-KR, sr-Cyrl-RS, fr-BE

This scaffolds the language file and test fixture, and regenerates LANGUAGES.md. A language can implement one, two, or all three forms — start with whichever you can do well and others can be added later:

Form	Function	Example
Cardinal	toCardinal()	"forty-two"
Ordinal	toOrdinal()	"forty-second"
Currency	toCurrency()	"forty-two dollars"

Then:

1. Implement your form(s) in src/<code>.js — including each form's range declaration (cardinalMax etc., scaffolded as UNBOUNDED placeholders; see docs/range-contract.md) and, if a form takes options, its options contract (see docs/options-contract.md)
2. Add test cases to test/fixtures/<code>.js
3. Run npm test — the suite's gates verify everything automatically and tell you exactly what's missing; green means done

Code Style

• JavaScript: ESLint — npm run lint:fix
• Markdown: markdownlint — npm run lint:md -- --fix

Testing

npm test              # Run unit tests + build types
npm run coverage      # With coverage report
npm run bench         # Performance benchmarks

Release Process (Maintainers)

Releases are triggered manually via GitHub Actions using git-cliff for changelog generation:

1. Go to Actions → Release → Run workflow
2. Select bump type: patch, minor, or major
3. The workflow runs tests and build first — tagging only happens if both pass
4. On success: package.json is bumped, CHANGELOG.md is updated, commit + tag + GitHub Release are created, and the package is published to npm

Version bumps: feat: → minor, fix:/perf: → patch, feat!: → major

Security

Report vulnerabilities via GitHub Security Advisories, not public issues. See SECURITY.md.

License

By contributing, you agree to license your contributions under the MIT License.