Skip to content

Commit 4b1419b

Browse files
gilmoreorlessgilmoreorless
committed
docs: Update contributing guide to reflect the latest data process
1 parent 8b39cdc commit 4b1419b

File tree

1 file changed

+98
-77
lines changed

1 file changed

+98
-77
lines changed

‎contributing.md

+98-77
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ demonstrating the issue before opening a ticket on GitHub.
66
## Contributing
77

88
Fork the library, install grunt, and install dependencies.
9-
Note that all pull requests will require a CLA.
9+
Note that all pull requests will require a signed [CLA (Contributor License Agreement)](https://openjsf.org/about/the-openjs-foundation-cla/).
1010

1111
```
1212
npm install -g grunt-cli
@@ -19,9 +19,10 @@ Additions to `moment-timezone.js` or `moment-timezone-utils.js` should have matc
1919
## Running tests
2020

2121
```sh
22-
grunt nodeunit # run all tests
23-
grunt nodeunit:core # run all core tests
24-
grunt nodeunit:zones # run all zone tests
22+
grunt nodeunit # run all tests (includes the 3 commands below)
23+
grunt nodeunit:core # run all core tests
24+
grunt nodeunit:zones # run all zone tests
25+
grunt nodeunit:countries # run all country tests
2526
```
2627

2728
If all the tests are passing, submit a pull request.
@@ -40,13 +41,20 @@ dependencies.
4041
which curl tar zic zdump
4142
```
4243

43-
To compile the latest iana release, run `grunt data`.
44+
To compile the latest IANA release, run `grunt data`.
4445

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

48-
The compilation process involves 7 steps. For each of the steps, a tag name can
49-
be passed to grunt. If no tag name was passed, it defaults to the latest release.
49+
The compilation process involves 8 steps, each of which can be run separately.
50+
For each of the steps, a tag name can be passed to grunt. If no tag name was passed,
51+
it defaults to the latest release.
52+
53+
Some tasks create files within the `temp` directory. These are only used by other
54+
parts of the process and are ignored by git.
55+
56+
Other tasks create files in the `data` or `tests` directories. These files should
57+
be committed to git.
5058

5159
### 1. Download data from iana.org/time-zones.
5260

@@ -57,7 +65,64 @@ grunt data-download:2014d
5765
This downloads the data to `temp/curl/2014d/data.tar.gz` and unzips into
5866
`temp/download/2014d`.
5967

60-
### 2. Compile the data to a binary format using `zic(8)`
68+
### 2. Extract zone & country meta data
69+
70+
```
71+
grunt data-meta:2014d
72+
```
73+
74+
This task creates a JSON file containing a list of timezones and countries.
75+
The extracted meta data can be used to list all timezones, list all countries, and filter zones by a country.
76+
77+
The output is saved in `data/meta/2014d.json`
78+
79+
Sample output:
80+
81+
```
82+
{
83+
"countries": {
84+
"AD": {
85+
"name": "Andorra",
86+
"abbr": "AD",
87+
"zones": [
88+
"Europe/Andorra"
89+
]
90+
},
91+
"AE": {
92+
"name": "United Arab Emirates",
93+
"abbr": "AE",
94+
"zones": [
95+
"Asia/Dubai"
96+
]
97+
},
98+
...
99+
},
100+
"zones": {
101+
"Europe/Andorra": {
102+
"name": "Europe/Andorra",
103+
"lat": 42.5,
104+
"long": 1.5167,
105+
"countries": [
106+
"AD"
107+
],
108+
"comments": ""
109+
},
110+
"Asia/Dubai": {
111+
"name": "Asia/Dubai",
112+
"lat": 25.3,
113+
"long": 55.3,
114+
"countries": [
115+
"AE",
116+
"OM"
117+
],
118+
"comments": ""
119+
},
120+
...
121+
}
122+
}
123+
```
124+
125+
### 3. Compile the data to a binary format using `zic(8)`
61126

62127
```
63128
grunt data-zic:2014d
@@ -66,7 +131,13 @@ grunt data-zic:2014d
66131
This compiles each of the source files in the `temp/download/2014d` folder to
67132
`temp/zic/2014d`.
68133

69-
### 3. Dump the changes from the binary format into a text format using `zdump(8)`.
134+
An alternative path to the `zic` binary can be provided using the `--zic-path` option.
135+
136+
```
137+
grunt data-zic:2014d --zic-path=/path/to/custom/zic
138+
```
139+
140+
### 4. Dump the changes from the binary format into a text format using `zdump(8)`.
70141

71142
```
72143
grunt data-zdump:2014d
@@ -82,7 +153,14 @@ This dumps a list of timezone changes for each zone in `temp/zic/2014d` to
82153
>
83154
> via `man zdump`
84155
85-
### 4. Collect the changes into a single JSON file.
156+
An alternative path to the `zdump` binary can be provided using the `--zdump-path` option.
157+
158+
```
159+
grunt data-zdump:2014d --zdump-path=/path/to/custom/zdump
160+
```
161+
162+
163+
### 5. Collect the changes into a single JSON file.
86164

87165
```
88166
grunt data-collect:2014d
@@ -113,7 +191,7 @@ to `temp/collect/2014b.json`.
113191
...
114192
```
115193

116-
### 5. Remove duplicate entries.
194+
### 6. Remove duplicate entries.
117195

118196
```
119197
grunt data-dedupe:2014d
@@ -123,11 +201,9 @@ grunt data-dedupe:2014d
123201
each time discontinuity. In order to save space, we remove the
124202
_one second before_ entries.
125203

126-
The output is saved in `data/unpacked/2014d.json`. This is the first file in the
127-
process that is committed to git. Steps 1-4 are stored in an ignored `temp/`
128-
directory.
204+
The output is saved in `data/unpacked/2014d.json`.
129205

130-
### 6. Pack the data into the compressed format.
206+
### 7. Pack the data into the compressed format.
131207

132208
```
133209
grunt data-pack:2014d
@@ -148,85 +224,30 @@ Pack each zone in `data/unpacked/2014d.json` and save in `data/packed/2014d.json
148224
"America/Phoenix|MST MDT MWT|70 60 60|01010202010|-261r0 1nX0 11B0 1nX0 SgN0 4Al1 Ap0 1db0 SWqX 1cL0"
149225
```
150226

151-
### 7. Extract zone & country meta data
152-
153-
```
154-
grunt data-meta:2014d
155-
```
156-
157-
This task creates a JSON file containing 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.
158-
159-
The output is saved in `data/meta/2014d.json`
160-
161-
Sample output:
162-
163-
```
164-
{
165-
"countries": {
166-
"AD": {
167-
"name": "Andorra",
168-
"abbr": "AD",
169-
"zones": [
170-
"Europe/Andorra"
171-
]
172-
},
173-
"AE": {
174-
"name": "United Arab Emirates",
175-
"abbr": "AE",
176-
"zones": [
177-
"Asia/Dubai"
178-
]
179-
},
180-
...
181-
},
182-
"zones": {
183-
"Europe/Andorra": {
184-
"name": "Europe/Andorra",
185-
"lat": 42.5,
186-
"long": 1.5167,
187-
"countries": [
188-
"AD"
189-
],
190-
"comments": ""
191-
},
192-
"Asia/Dubai": {
193-
"name": "Asia/Dubai",
194-
"lat": 25.3,
195-
"long": 55.3,
196-
"countries": [
197-
"AE",
198-
"OM"
199-
],
200-
"comments": ""
201-
},
202-
...
203-
}
204-
}
205-
```
206-
207227
### 8. Build tests for each zone.
208228

209229
```
210230
grunt data-tests
211231
```
212232

213-
This task does not support tagged releases, and is only run on the latest
214-
timezone data.
215-
216233
Reads data from `temp/collect/latest.json` and constructs unit tests for each
217234
zone. This uses `temp/collect/latest.json` instead of `data/unpacked/latest.json`
218235
in order to test both the times _one second before_ and _exactly at_
219236
each time discontinuity.
220237

238+
Without a version, this will write files to the `tests` directory.
239+
If this is run with a specific version (`grunt data-tests:2014d`), the files will
240+
be written to `temp/tests/<version>` instead.
241+
221242
### All tasks
222243

223-
For sanity, all these tasks are bundled into one task. This is the preferred way
244+
For ease of use, all these tasks are bundled into one task. This is the preferred way
224245
to compile the data.
225246

226247
```
227248
grunt data # run tasks 1-8 on the latest release
228-
grunt data:2014c # run tasks 1-7 on the 2014c release
229-
grunt data:2014d # run tasks 1-7 on the 2014d release
249+
grunt data:2014c # run tasks 1-8 on the 2014c release
250+
grunt data:2014d # run tasks 1-8 on the 2014d release
230251
```
231252

232253

0 commit comments

Comments
 (0)