Skip to content

Latest commit

 

History

History
303 lines (224 loc) · 8.33 KB

contributing.md

File metadata and controls

303 lines (224 loc) · 8.33 KB
Raw

Bugs

If you are submitting a bug, please create a jsfiddle demonstrating the issue before opening a ticket on GitHub.

Contributing code

⚠️ Before you begin, note that Moment Timezone is in maintenance-only mode. Bug fixes and performance improvements will still be accepted, and IANA data updates will continue to be released via a semi-automated process.

However, new features or API changes are unlikely to be accepted as pull requests.

For other types of code improvements, the process below should be followed.

Fork the library, install grunt, and install dependencies. Note that all pull requests will require a signed CLA (Contributor License Agreement).

npm install -g grunt-cli
npm install

Additions to moment-timezone.js or moment-timezone-utils.js should have matching tests in /tests/moment-timezone/.

Running tests

grunt nodeunit           # run all tests (includes the 3 commands below)
grunt nodeunit:core      # run all core tests
grunt nodeunit:zones     # run all zone tests
grunt nodeunit:countries # run all country tests

If all the tests are passing, submit a pull request.

Compiling data

⚠️ NOTE: These instructions are for anyone who wants to create a custom data build for their own purposes. Official data updates are created by an automated workflow to ensure consistency (the behaviour of tools like zdump can vary wildly across platforms).

Therefore, contributor pull requests for data updates will not be accepted.

There are several steps to compiling the timezone data. These have all been bundled into one grunt task to make updates easy.

Besides the node, npm, and grunt dependencies, there are also a few unix dependencies.

curl, tar, zic, and zdump are all required.

which curl tar zic zdump

To compile the latest IANA release, run grunt data.

To compile a specific tagged release, run grunt data:2014d, replacing 2014d with the desired release tag.

The compilation process involves 8 steps, each of which can be run separately. For each of the steps, a tag name can be passed to grunt. If no tag name was passed, it defaults to the latest release.

Some tasks create files within the temp directory. These are only used by other parts of the process and are ignored by git.

Other tasks create files in the data or tests directories. These files should be committed to git.

1. Download data from iana.org/time-zones.

grunt data-download:2014d

This downloads the data to temp/curl/2014d/data.tar.gz and unzips into temp/download/2014d.

2. Extract zone & country meta data

grunt data-meta:2014d

This task creates a JSON file containing a list of timezones and countries. The extracted meta data can be used to list all timezones, list all countries, and filter zones by a country.

The output is saved in data/meta/2014d.json

Sample output:

{
    "countries": {
        "AD": {
            "name": "Andorra",
            "abbr": "AD",
            "zones": [
                "Europe/Andorra"
            ]
        },
        "AE": {
            "name": "United Arab Emirates",
            "abbr": "AE",
            "zones": [
                "Asia/Dubai"
            ]
        },
        ...
    },
    "zones": {
        "Europe/Andorra": {
            "name": "Europe/Andorra",
            "lat": 42.5,
            "long": 1.5167,
            "countries": [
                "AD"
            ],
            "comments": ""
        },
        "Asia/Dubai": {
            "name": "Asia/Dubai",
            "lat": 25.3,
            "long": 55.3,
            "countries": [
                "AE",
                "OM"
            ],
            "comments": ""
        },
        ...
    }
}

3. Compile the data to a binary format using zic(8)

grunt data-zic:2014d

This compiles each of the source files in the temp/download/2014d folder to temp/zic/2014d.

An alternative path to the zic binary can be provided using the --zic-path option.

grunt data-zic:2014d --zic-path=/path/to/custom/zic

4. Dump the changes from the binary format into a text format using zdump(8).

grunt data-zdump:2014d

This dumps a list of timezone changes for each zone in temp/zic/2014d to temp/zdump/2014d.

For each zone, print the time at the lowest possible time value, the time one day after the lowest possible time value, the times both one second before and exactly at each detected time discontinuity, the time at one day less than the highest possible time value, and the time at the highest possible time value.

via man zdump

An alternative path to the zdump binary can be provided using the --zdump-path option.

grunt data-zdump:2014d --zdump-path=/path/to/custom/zdump

5. Collect the changes into a single JSON file.

grunt data-collect:2014d

The output from zdump(8) looks like this.

America/Los_Angeles  Sun Mar  9 09:59:59 2014 UTC = Sun Mar  9 01:59:59 2014 PST isdst=0
America/Los_Angeles  Sun Mar  9 10:00:00 2014 UTC = Sun Mar  9 03:00:00 2014 PDT isdst=1
America/Los_Angeles  Sun Nov  2 08:59:59 2014 UTC = Sun Nov  2 01:59:59 2014 PDT isdst=1
America/Los_Angeles  Sun Nov  2 09:00:00 2014 UTC = Sun Nov  2 01:00:00 2014 PST isdst=0

The data-collect task takes all the dumped zones, converts them to moment-timezone's unpacked format, collects them into one object, and saves them to temp/collect/2014b.json.

    ...
}, {
    "name": "America/Los_Angeles",
    "abbrs": [..."PST", "PDT", "PDT", "PST"...],
    "untils": [...1604221199000, 1604221200000, 1615715999000, 1615716000000...],
    "offsets": [...480, 420, 420, 480...]
}, {
    "name": "America/Louisville",
    ...

6. Remove duplicate entries.

grunt data-dedupe:2014d

zdump(8) prints a line for the times one second before and exactly at each time discontinuity. In order to save space, we remove the one second before entries.

The output is saved in data/unpacked/2014d.json.

7. Pack the data into the compressed format.

grunt data-pack:2014d

Pack each zone in data/unpacked/2014d.json and save in data/packed/2014d.json.

// unpacked
{
    "name"    : "America/Phoenix",
    "abbrs"   : ["MST", "MDT", "MST", "MDT", "MST", "MWT", "MST", "MWT", "MST", "MDT", "MST"],
    "untils"  : [-1633273200000, -1615132800000, -1601823600000, -1583683200000, -880210800000, -820519140000, -812653140000, -796845540000, -84380400000, -68659200000, null],
    "offsets" : [420, 360, 420, 360, 420, 360, 420, 360, 420, 360, 420]
}

// packed
"America/Phoenix|MST MDT MWT|70 60 60|01010202010|-261r0 1nX0 11B0 1nX0 SgN0 4Al1 Ap0 1db0 SWqX 1cL0"

8. Build tests for each zone.

grunt data-tests

Reads data from temp/collect/latest.json and constructs unit tests for each zone. This uses temp/collect/latest.json instead of data/unpacked/latest.json in order to test both the times one second before and exactly at each time discontinuity.

Without a version, this will write files to the tests directory. If this is run with a specific version (grunt data-tests:2014d), the files will be written to temp/tests/<version> instead.

All tasks

For ease of use, all these tasks are bundled into one task. This is the preferred way to compile the data.

grunt data       # run tasks 1-8 on the latest release
grunt data:2014c # run tasks 1-8 on the 2014c release
grunt data:2014d # run tasks 1-8 on the 2014d release

Steps to release a new version

  1. Create a new branch like release_0.X.X from master and do this:

grunt data

  1. Change version in:
  • package.json
  • composer.json
  • moment-timezone.js
  • moment-timezone-utils.js
  1. Do this:
grunt build
grunt uglify
npm run test
  1. Open pull request from your branch into develop
  2. Merge changes from your branch into develop branch
  3. Merge changes from develop into master branch
  4. Create a new release here https://github.com/moment/moment-timezone/releases
  5. Do npm publish to publish changes to NPM
  6. Also, you should update version of moment-timezone in package.json file of this repository https://github.com/moment/momentjs.com to the latest version. It will change version on the website https://momentjs.com/timezone/