Skip to content

Latest commit

 

History

History
155 lines (111 loc) · 7.36 KB

CONTRIBUTING.md

File metadata and controls

155 lines (111 loc) · 7.36 KB
Raw

Contributing

lerna

Getting Started

Check out the code and go into the moment-holiday directory:

git clone https://github.com/nesto-software/moment-holiday.git
cd moment-holiday

Install the dependencies and bootstrap the monorepo:

npm run dev-install
npm run compile

The code for individual packages of this monorepo is in packages/*. Within any of the packages in this monorepo you'll generally use the npm package scripts to manage the project, E.g. npm run test or npm run lint. Run npm run for a list of available commands. Because of the monorepo structure some of the commands only work from monorepo root using lerna run instead of npm run.

Running Tests

To run the test suite, from the root directory run:

npm test

If you want the tests to be rerun when any changes are made to the src or test files use:

npm test -- --watch

If you use vscode and you want to debug your test code, use the Debug Unit Tests run configuration.

Running Docs

All the docsify documentation can be found in the root level docs directory. Running the following command will stand up the docs server which will watch for changes.

npm run docs:serve

Creating Typescript Docs

As we use typescript, we want to provide an additional documentation for public modules - the so called API docs.
The following command is used to create the typedocs:

npm run typedoc:create

The typedoc documentation is based on your tsdoc comments. So make sure to comment public methods properly!

Packages

Core

This package contains core entities which describe holidays. Some of the important ones are:

docs

API

This package is the entry point for using the moment-holiday API.
You should import its factory method as default import.
Important entities contain:

There are two similar moment-holiday APIs.
The synchronous ('simplified') moment-holiday API does not use database modules and thus does not support client specific holiday definitions. The synchronous API does not use Promises at all.
The asynchronous ('database') moment-holiday API uses database modules. Its methods return a promise.

docs

Locales

This folder contains multiple packages with holiday definitions for different countries.
You should never depend on a locale package directly. The locale's public entities are exposed through the API package.

Database

MongoDB (Mongoose)

This package provides a MongoDB database plugin for moment-holiday.
It depends on the Mongoose ODM.

You can use it to store holiday definitions in a database. The library loads definitions from the mongo database.

docs

Development Notes

The project is maintained by lerna. In order to make it easier for people who are not familiar with lerna, there are root level npm scripts to use.

  • npm run dev-install: classic npm install for every package which installs peer dependencies as dev dependencies
  • npm run ci-install: the same as the above command but (a) removes present node_modules and (b) needs a package-lock.json
  • npm run compile: runs tsc in every package in order to create the dist directory for node
  • npm run compile:browser: runs tsc in every package in order to create the dist.browser directory for webpack
  • npm run clean: cleans all packages, i.e. removes node_modules
  • npm run lint: runs the linter for all packages
  • npm run test: runs tests in each package
  • npm run publish: publish packages which changed
  • npm run dev: compile all packages and invoke the client.js file in the dev package
  • npm run typedoc:create: create typedoc documentation
  • npm run docsify:serve: serve the docsify documentation locally
  • npm run toc: update the table of contents in this README file
  • npm run snyk:[monitor|protect|test]: runs the respective snyk command - monitor and test in subpackages

Different Compile Targets

We create two build directories: dist and dist.browser. This library is optimized for backend usage with node. Thus, we focus on the dist distribution of the library.

However, we want to provide basic support for the browser via the webpack bundler. Thus, we compile with the ES5 and CommonJS target for the dist.browser distribution. Webpack automatically recognizes and references the browser distribution.

New NPM Package Linking

Npm now uses so called 'file-specifiers'.
That is why we should put all dev-dependencies and peer-dependencies for packages in the package.json file at the root.
The packages in the packages folder then use the contents of the root node_modules folder along with their respective node_modules folder. They get effectively merged.

Here is an issue which explains the recent changes and why lerna bootstrap is not used anymore: lerna/lerna#1587.

It is a very fast JavaScript world we live in. ;)

VSCode Issues

Sometimes it is necessary to close and reopen vscode again in order for all imports to be resolved correctly. This issue was observed for local package imports that use symlinks.

Submitting a PR

If you want to report a bug or propose an enhancement, please fill an issue. If you want to add a locale package, please use the skeleton provided in the repository. If you want to do something else, you can place a pull request directly or contact the maintainer.

Commits

We use conventional commits and Semantic Versioning. Please structure your commit messages and package.json files accordingly.