CONTRIBUTING.md

Contributing Guide

⚠⚠⚠ Please contribute new code in TypeScript ⚠⚠⚠

Read more about migration to TypeScript

Table of Contents

• How to Help?

• Contribution Guidelines

• Getting Started

• Testing

  • Unit tests
  • REPL
  • Test build

• Code Style Guide

  • Lint the Code

• Documentation

  • JSDoc

How to Help?

Help is always welcome. There are areas where you can help:

• The core functionality (performance improvements, bug fixes, new features, etc.).

• Documentation (markdown documents, JSDoc annotations in source code).

• Test suite & development environment improvements.

• The website.

If you see a gap, but don't have time, experience, or you just need help with the library, don't hesitate to start a discussion or open a new issue.

The date-fns functionality is comprehensive and covers most of the use cases, however it doesn't have an extended time zone support. Please leave a comment to the Extended time zones support issue if you are interested in the functionality or want to help with development.

If you are interested in Elm/ClojureScript/etc. wrappers, please file an issue.

Contribution Guidelines

Due to the modular nature of date-fns, it's more than open to new features. However, when a new function duplicates the existing functionality, native API or causes significant build size increase, a PR might be rejected or the author can be asked to move the code to a new or another package.

Please follow the main contributing rules, to maintain date-fns' top quality:

• Follow style guides:

  • Lint the code.

• Write tests.

• Write documentation.

• Don't update the changelog.

• Don't change the library version.

Getting Started

1. Install Node.js 14 or greater (LTS recommended)

2. Install or upgrade to the latest Yarn classic (v1) by running npm install -g yarn@latest

3. Fork the project, and clone your fork of the repo

4. Run yarn to install the dev dependencies

Testing

Unit tests

Karma + Mocha (Chrome):

# all tests in watch mode
yarn test

# all tests once
yarn test --single-run

Jest (Node.js):

# all tests in watch mode
yarn jest --watch

# all tests once
yarn jest

REPL

To test functions in a REPL, use babel-node located in ./node_modules/.bin (mind the -x flag to also support TypeScript files):

yarn babel-node -x .ts,.js

and then require invididual functions:

> const toDate = require('./src/toDate')
undefined
> toDate(1392098430000).toString()
'Tue Feb 11 2014 01:00:30 GMT-0500 (Eastern Standard Time)'
>

or all functions (slower):

> const fns = require('./src')
undefined
> fns.toDate(1392098430000).toString()
'Tue Feb 11 2014 01:00:30 GMT-0500 (Eastern Standard Time)'
>

Test build

Build date-fns from source to test in your project. The ouput is equivalent to what gets published on npm with each release.

# replace {YOUR-PROJECT-PATH} with an absolute or relative path to your project root
env PACKAGE_OUTPUT_PATH="{YOUR-PROJECT-PATH}/node_modules/date-fns" ./scripts/build/package.sh

Code Style Guide

Lint the Code

The project follows Prettier code style and uses ESLint as the linter. To lint the code, run:

yarn lint

Documentation

JSDoc

• JSDoc is used for the code documentation. Along with the standard JSDoc tags, date-fns uses @category tag that allows to group functions.

• jsdoc-to-markdown is used to parse JSDoc annotations.