1 | # Contributing to Auspice development
|
2 |
|
3 | Thank you for helping us to improve Nextstrain!
|
4 |
|
5 | > **To get started, please see [the contributing guide](https://github.com/nextstrain/.github/blob/master/CONTRIBUTING.md) for useful information about how to pick an issue, submit your contributions, and so on.**
|
6 |
|
7 | This project strictly adheres to the [Contributor Covenant Code of Conduct](https://github.com/nextstrain/.github/blob/master/CODE_OF_CONDUCT.md).
|
8 |
|
9 | Please see the [project boards](https://github.com/orgs/nextstrain/projects) for currently available issues.
|
10 |
|
11 | ## Contributing code
|
12 |
|
13 | Code contributions are welcomed! [Please see the main auspice docs](https://nextstrain.github.io/auspice/introduction/install) for details on how to install and run auspice from source.
|
14 |
|
15 | Please comment on an open issue if you are working on it.
|
16 | For changes unrelated to an open issue, please make an issue outlining what you would like to change/add.
|
17 |
|
18 | Where possible, **please rebase** your work onto master rather than merging changes from master into your PR.
|
19 |
|
20 | From a fork: `git pull --rebase upstream master`
|
21 |
|
22 | ### Make sure tests are passing
|
23 |
|
24 | We use the following libraries for all kinds of testing, so it'd help to read the docs to get familiar with their APIs and features:
|
25 |
|
26 | 1. [`Jest`](https://github.com/facebook/jest)
|
27 | 2. [`Puppeteer`](https://github.com/puppeteer/puppeteer/)
|
28 | 3. [`Jest-Puppeteer`](https://github.com/smooth-code/jest-puppeteer)
|
29 | 4. [`Jest-Image-Snapshot`](https://github.com/americanexpress/jest-image-snapshot)
|
30 |
|
31 | When you submit a pull request to the auspice repository, a variety of integration and unit tests will need to pass before it can be merged.
|
32 |
|
33 | You will likely want to run these tests locally before submitting:
|
34 |
|
35 | First, install the dependencies with `npm i`, then:
|
36 |
|
37 | #### For unit tests
|
38 |
|
39 | Run `npm test`.
|
40 |
|
41 | #### For linting
|
42 |
|
43 | Run `npm run lint`. If there are issues run `npm run lint:fix`.
|
44 |
|
45 | #### For integration tests
|
46 |
|
47 | > For integration tests to work, you'll need to have `git-lfs` installed (see below) as it stores the images that the snapshot tests will use.
|
48 |
|
49 | 1. Fetch the datasets with `npm run get-data`.
|
50 | 2. Ensure you are **not** currently running the site locally, then run `npm run integration-test:ci`.
|
51 |
|
52 |
|
53 | #### How to update test snapshots
|
54 |
|
55 | 1. Unit tests: `npm run test -- -u`
|
56 | 2. Integration tests `npm run integration-test -- -u`
|
57 |
|
58 |
|
59 | #### For smoke tests
|
60 |
|
61 | 1. Fetch the datasets with `npm run get-data`.
|
62 | 2. Ensure you are **not** currently running the site locally, then run `npm run smoke-test:ci`.
|
63 |
|
64 |
|
65 | #### Test Tips
|
66 |
|
67 | 1. Run a single `describe()`, `it()`, or `test()` **within a file**, add `.only()`:
|
68 |
|
69 | E.g., `describe.only()`, `it.only()`, or `test.only()`
|
70 |
|
71 | 2. Run a single test file, append the following to your test command `-- relative_or_absolute_path/to/file`:
|
72 |
|
73 | E.g., `npm run integration-test -- test/integration/zika.test.js`
|
74 |
|
75 | 3. Run integration tests in headful mode, prepend `HEADLESS=false` to your command:
|
76 |
|
77 | E.g., `HEADLESS=false npm run integration-test`
|
78 |
|
79 | 4. For integration tests, please try to use [`expect-puppeteer`](https://github.com/smooth-code/jest-puppeteer/blob/master/packages/expect-puppeteer/README.md#api) as much as possible, and only resort to `puppeteer`'s native API when we can't do it with `expect-puppeteer`. The reason is because `expect-puppeteer` has better DX, as explained [here](https://github.com/smooth-code/jest-puppeteer/blob/master/packages/expect-puppeteer/README.md#why-do-i-need-it)
|
80 |
|
81 | 5. How to add a new integration image test:
|
82 |
|
83 | 1. Wrap your image test with helper function `toMatchImageSnapshot()` from `test/integration/helpers.js`, and it will take a screenshot every `100ms` until it matches the expected snapshot or timeout (default: `10s`)
|
84 |
|
85 | 2. Temporarily add `page.waitFor(__ENOUGH__MS__)` before taking the new snapshot to give the browser enough time to render a complete image
|
86 |
|
87 | 3. Example: `test/integration/zika.test.js`
|
88 |
|
89 |
|
90 | ## git-lfs
|
91 |
|
92 | We use [Git Large File Storage](https://github.com/git-lfs/git-lfs) to manage certain assets.
|
93 | Currently these are limited to images within the `./test` directory (which we use for snapshot integration testing) but this may change in the future.
|
94 | If you are not using these images, you don't need to have `git-lfs` installed; however **will not be able to run integration tests without it**.
|
95 | See [here](https://git-lfs.github.com/) for installation instructions.
|
96 |
|
97 | Helpful commands:
|
98 | ```bash
|
99 | git lfs status
|
100 | git lfs ls-files # list LFS tracked tiles
|
101 | ```
|
102 |
|
103 |
|
104 | ## Contributing to Documentation
|
105 |
|
106 | The main Nextstrain documentation is available at [docs.nextstrain.org](https://docs.nextstrain.org/en/latest/index.html). That documentation is built from the [docs.nextstrain.org GitHub repo](https://github.com/nextstrain/docs.nextstrain.org/) -- see the [contributing page for docs.nextstrain.org](https://docs.nextstrain.org/en/latest/guides/contribute/documentation.html) for more details on how to contribute to that documentation.
|
107 |
|
108 | The Auspice technical reference guide is available at [docs.nextstrain.org/projects/auspice](https://docs.nextstrain.org/projects/auspice/en/latest/index.html). That documentation is built from the Auspice GitHub repo -- see the [docs/README](https://github.com/nextstrain/auspice/tree/master/docs#auspice-read-the-docs-documentation) within the `docs` directory for more details and on how to contribute to that documentation.
|
109 |
|
110 | ## Contributing to Internationalization and Localization (i18n/l18n)
|
111 |
|
112 | If you can assist in efforts to translate the Auspice interface to more languages your assistance would be very much appreciated.
|
113 | The currently available languages are displayed via a drop-down at the bottom of the sidebar.
|
114 |
|
115 | ## Adding a new language
|
116 |
|
117 | 1) Add the language to the `getlanguageOptions` function in [this file](https://github.com/nextstrain/auspice/blob/master/src/components/controls/language.js#L24)
|
118 | 2) If this is a new language, copy the folder (and the JSONs within it) `src/locales/en` and name it to match the language code for the new translation -- e.g. for Spanish this would be `src/locales/es`
|
119 | 3) For each key-value in the JSONs, translate the english phrase to the new locale. (Do not modify the strings within `{{...}}` sections.)
|
120 |
|
121 | For example, a spanish translation would change the English:
|
122 |
|
123 | ```json
|
124 | "sampled between {{from}} and {{to}}": "sampled between {{from}} and {{to}}",
|
125 | "and comprising": "and comprising",
|
126 | ```
|
127 |
|
128 | to
|
129 |
|
130 | ```json
|
131 | "sampled between {{from}} and {{to}}": "aislados entre {{from}} y {{to}}",
|
132 | "and comprising": "y compuesto de",
|
133 | ```
|
134 |
|
135 | ## Helper script to check what parts of a translation are out-of-date or missing
|
136 |
|
137 | Run `npm run diff-lang -- X`, where `X` is the language you wish to check, for instance `es`.
|
138 | This will display the strings which:
|
139 |
|
140 | * need to be added to the translation
|
141 | * are present but should be removed as they are no longer used
|
142 | * are present but are simply a copy of the English version & need to be translated
|
143 |
|
144 | > Running `npm run diff-lang` will check all available languages.
|
145 |
|
146 | ## Improving an existing translation
|
147 |
|
148 | If a translation of a particular string is not yet available, then auspice will fall-back to the english version.
|
149 |
|
150 | 1) Find the relevant key in the (EN) JSONs [in this directory](https://github.com/nextstrain/auspice/tree/master/src/locales/en)
|
151 | 2) Add the key to the JSON with the same name, but in the directory corresponding to the language you are translating into (see above for an example).
|
152 |
|
153 | ## Releases & versioning
|
154 |
|
155 | New versions are released via the `./releaseNewVersion.sh` script from an up-to-date `master` branch. It will prompt you for the version number increase, push changes to the `release` branch and, as long as Travis-CI is successful then a new version will be automatically published to [npm](https://www.npmjs.com/package/auspice).
|