Contribution Guide

Thank you for your interest in contributing to the Nepali Date (Bikram Sambat) Ecosystem! This open-source project is built and maintained to provide synchronized, robust, zero-dependency calendar tools across JavaScript/TypeScript, Python, and PHP.

Whether you are fixing a typo, adding calendar tests, improving performance, or porting new features across languages, your contributions are warmly welcomed.

Ecosystem RepositoriesCopy Anchor Link

The ecosystem consists of four main projects:

Core Contribution PrinciplesCopy Anchor Link

Before proposing changes, please keep our core architectural principles in mind:

1. Zero External Runtime Dependencies: All three language packages (nepali-date-library) MUST maintain zero external dependencies at runtime. Do not add runtime packages.

2. Standardized Cross-Language Semantics: The API surface across Node.js, Python, and PHP is intentionally synchronized. Method names, formatting tokens (e.g. YYYY-MM-DD, dddd), fiscal year quarters, and edge case handling should match across all implementations.

3. Annual Calendar Verification & Range Coverage (1976 – 2100 BS): Dates up to the current active calendar year are verified against official Government of Nepal publications (Nepal Panchanga Nirnayak Samiti). Every year around the month of Ashwin (Ashoj), when the official government calendar is released for the upcoming year, the mapping tables are audited and updated with exact solar ingress corrections. Test suites must pass across all supported years (1976/01/01 to 2100/12/31 BS).

4. Deterministic Timezone Isolation: Date arithmetic, weekday getters, and day start/end calculations must execute deterministically regardless of the host machine's local timezone.

Development Environment SetupCopy Anchor Link

Select your target language below for environment setup and test commands:

# Clone repository
git clone https://github.com/SandipGhimire/Nepali-Date-Library-NodeJS.git
cd Nepali-Date-Library-NodeJS

# Install dependencies
pnpm install

# Build ESM and CJS bundles
pnpm run build

# Run tests (Vitest)
pnpm run test

# Run legacy Node compatibility tests (Node 8-17)
pnpm run test:compat

# Lint and formatting
pnpm run lint
pnpm run format

Pull Request GuidelinesCopy Anchor Link

1. Fork & Branch: Fork the target repository and create a descriptive branch:

   Copy Text

   git checkout -b feat/devanagari-weekday-tokens

2. Write Tests: Accompany every bug fix or feature with clear unit tests verifying the behavior.
3. Run CI Checks: Verify that all test suites, linters, and type checkers pass without errors.
4. Descriptive Commits: Use conventional commits (e.g., feat:, fix:, docs:, chore:).
5. Submit PR: Open a Pull Request referencing any related issues with reproduction steps or rationale.

Community & Code of ConductCopy Anchor Link

We are dedicated to providing a welcoming, inclusive, and respectful environment for all contributors. Please treat fellow maintainers and contributors with professionalism, kindness, and constructive feedback.

Made with ❤️ by Sandip Ghimire.