Skip to content

Latest commit

 

History

History
81 lines (67 loc) · 3.93 KB

contributing.md

File metadata and controls

81 lines (67 loc) · 3.93 KB
Raw

Contributing definitions

Contributing library definitions is as easy as sending a pull request!

All definitions sit under the /definitions directory. They all must follow the following directory structure and naming format:

└ definitions/npm/
  ├ yargs_v4.x.x/           # <-- The name of the library, followed by _v<VERSION>
  | |
  | ├ flow_v0.83.x/         # <-- A folder containing libdefs tested against the
  | | |                     #     specified version(s) of Flow (v0.83.x in this
  | | |                     #     case).
  | | |
  | | └ yargs_v4.x.x.js     # <-- The libdef file meant for the Flow version
  | |                       #     specified by the containing directory's name.
  | |                       #     Must be named `<LIB>_v<VERSION>.js`.
  | |
  | ├ flow_v0.85.x-v0.91.x/ # <-- A folder containing libdefs tested against a
  | | |                     #     different range of Flow versions:
  | | |                     #     Anything from v0.85.x to v0.91.x (inclusive)
  | | |
  | | ├ yargs_v4.x.x.js     # <-- The libdef file for versions of Flow from
  | | |                     #     v0.85.x to v0.91.x (inclusive)
  | | |
  | | └ test_yargs.js       # <-- Tests in this directory only apply to the
  | |                       #     adjacent libdef (and thus, are specific to
  | |                       #     the libdefs for this specific Flow version)
  | |
  | └ test_yargs.js         # <-- Tests in this directory apply to libdefs for
  |                         #     all versions of Flow.
  ├ color_v0.7.x/
  ├ ...

Versions are semantically versioned (semver) with some restrictions:

  • All of MAJOR, MINOR, and PATCH versions must be specified. It's acceptable to specify x in place of a number for MINOR and PATCH, but MAJOR cannot be x.
  • Library versions cannot specify a semver range, but Flow versions can of the following forms:
    • flow_v0.83.x-: Flow v0.22.x and above
    • flow_v0.85.x-v0.91.x: Flow versions v0.22.x up to v0.28.x (inclusive)
    • flow_-v0.106.x: Every version under (and including) Flow v0.22.x

We structure files this way to enable automated testing and tooling. Tests ensure that library definitions continue to work as expected and the flow-typed tooling ensures that it's as easy as possible to find and install library definitions.

Writing tests

When you contribute a new library definition (or make a change to an existing one), you must include tests with your change.

Tests are simply test_*.js files that sit next to the library definition file. They are normal @flow-ified .js files that import from and use the types declared in the libdef in a way they are expected to be used. Flow-typed CI will then run all applicable versions of Flow against the test file to be sure that only expected errors occur.

In order to write code where you expect an error, you can put // $FlowExpectedError with a suppression code on the line above one of the lines listed in the error. This tells the test runner to ignore errors that mention that line. We require at least 1 // $FlowExpectedError in each test. This helps to ensure that the test is actually exercising types like the author expects it to be.

Partial/definitions definitions

We welcome contributions of partial, incomplete or work-in-progress definitions! When submitting a partial definition, please stub out the missing parts with any. If the definition was generated from create-stub, those parts should already be stubbed.

A note on flowgen

flowgen is a CLI tool that generates flowtype definitions from TypeScript types. While it supports most of the TypeScript syntax, in some cases manual changes may be needed before use. You can check out supported syntax constructs in thier section on the state of the converter.