贡献

¥Contributing

🐛如何报告错误

¥🐛 How to report a bug

请备注

¥Please note

Turf 的高级结构正在 #1428 进行讨论。目前（2018 年 6 月），部分代码已转换为 Typescript，贡献文档并未完全反映当前状态。

¥The high-level structure of Turf is undergoing discussion at #1428. Currently (June 2018), there is a partial conversion to Typescript, and the contribution documentation does not completely reflect the current status.

如何贡献

¥How To Contribute

• 大多数工作在子模块中进行。这些文件位于以 "turf-" 为前缀的 packages 目录中。

  ¥Most work happens in sub modules. These are found in the packages directory prefixed with "turf-".

• 如果你想提出新功能，请在 Turfjs/turf 中提交一个问题。

  ¥If you would like to propose a new feature, open an issue in Turfjs/turf.

• 始终包含测试。我们使用 tape。

  ¥Always include tests. We use tape.

• Turf 模块很小，只包含一个导出函数。

  ¥Turf modules are small, containing a single exported function.

• GeoJSON 是 Turf 的通用语言。它应该用作任何可以表示为地理信息的数据结构。

  ¥GeoJSON is the lingua franca of Turf. It should be used as the data structure for anything that can be represented as geography.

• 不惜一切代价避免过度依赖。

  ¥Avoid large dependencies at all costs.

• Turf 的应用非常广泛。请确保你的代码可以在浏览器中运行（例如：不要调用外部服务、不要访问文件系统等）。

  ¥Turf is used in a wide range of places. Make sure that your code can run in the browser (ie: don't make calls to external services, don't hit the filesystem, etc.).

• packages/turf-<module> 中的 README.md 文件是从 index.js 的 JSDocs 文件自动生成的。请修改 JSDocs，而不是直接修改 README.md 文件。然后，通过执行 ./scripts/generate-readmes 或从 TurfJS 根目录运行 npm run docs 来更新/创建 README.md。

  ¥The README.md files in packages/turf-<module> are automatically generated from the JSDocs of the index.js. Please modify the JSDocs instead of modifying the README.md files directly. Then update/create the README.md executing ./scripts/generate-readmes or runing npm run docs from the root TurfJS directory.

• 最后，从项目根文件夹运行 npm test，以运行部署项目所需的所有测试。

  ¥Finally run npm test from the project root folder to run all the tests required for deploying the project.

代码风格

¥Code Style

为确保代码风格，请在 turf 根目录下运行

¥To ensure code style, at the turf root level run

$ npm run lint

• 遵循 AirBNB JavaScript 代码风格。

  ¥Follow the AirBNB JavaScript code style.

• Turf 旨在在合理的情况下使用 ES5 特性。我们不使用 ES6 特性。

  ¥Turf aims to use ES5 features where rational. We do not use ES6 features.

Turf 模块结构

¥Structure of a turf module

turf-<MODULE NAME>
│   index.js
│   index.d.ts
│   bench.js
│   test.js
│   types.ts
│   package.json
│   README.md
│   LICENSE
│
└───test
    │
    ├───in
    │   points.geojson
    │
    └───out
        points.geojson

要开始使用新模块，请导航至根目录并运行

¥To get started with a new module navigate to the root directory and run

$ node ./scripts/create-new-module <MODULE NAME>

=​​=== 它将在 packages 中创建一个新文件夹，其中包含模块的简单样板文件。

¥it will create a new folder inside packages with a simple boilerplate for your module.

• index.js - 此文件按顺序包含你需要导入的各种模块、JSDocs 文档以及模块提供的单个导出函数。有关文档支持的类型的更多信息，请参阅……

  ¥index.js - This file contains, in order, the various modules you need to import, the JSDocs documentation, and, finally, the single exported function that the module provides. For more on the types supported in the documentation, see…

• index.d.ts - 这是一个描述函数签名的 TypeScript 文件。有关 TypeScript 支持的类型的更多信息，请参阅……

  ¥index.d.ts - This is a TypeScript file that describes your function’s signature. For more on the types supported in TypeScript, see…

• bench.js - 此文件使用 基准 为你的函数计时。

  ¥bench.js - This file uses Benchmark to time your function.

• test.js - 此文件包含你的 tape 测试。我们倾向于使用 GeoJSON 文件构建动态测试，这些文件放置在 ./test/in 中，如果你的 REGEN、环境变量已设置 到 true 存在问题，则随后会写入 ./test/out。如果 REGEN 设置为不同的值，则运行 npm t 会将测试的输出与 ./test/out 中已有的文件进行比较。

  ¥test.js - This file includes your tape tests. We prefer dynamic testing built from GeoJSON files placed in ./test/in that are subsequently written to ./test/out if your REGEN environment variable is set to true. If REGEN is set to a different value, then running npm t will compare the output of the tests to the files already present in ./test/out.

• types.ts - 列出 index.d.ts 中使用的自定义 TypeScript 类型的文件。

  ¥types.ts - A file that lists the custom TypeScript types used in index.d.ts.

• package.json - node 元数据容器文件。在 index.js 中导入的模块应列在 dependencies 下，在 test.js 和/或 bench.js 中使用的模块应列在 devDependencies 下。npm install 使用此文件在 ./node_modules 中安装依赖。

  ¥package.json - The node metadata container file. Modules imported in index.js should be listed here under dependencies, and modules used in test.js and/or bench.js should be listed under devDependencies. npm install looks to this file to install dependencies in ./node_modules.

• README.md - 此 README 文件是通过从项目根目录运行 npm run docs 自动生成的。请勿编辑此文件。

  ¥README.md - This README is generated automatically by running npm run docs from the project root level. DO NOT edit this file.

• LICENCE - 与 README 文件一样，此文件不可编辑。

  ¥LICENCE - Like the README, this file should not be edited.

• test/ - 此目录包含 GeoJSON 文件，这些文件为动态测试（在 ./test/in 中）提供数据，并为测试结果（在 ./test/out 中）提供数据。./test/out 中的文件不应手动编辑。它们应该由 设置环境变量、REGEN 到 true 动态生成，然后通过将 REGEN 设置为其他值来针对这些文件检查测试。生成的输出文件可以拖放到 geojson.io 中，直观地查看模块是否正常运行。

  ¥test/ - This directory holds the GeoJSON files that provide data for dynamic tests (in ./test/in) and the results of the tests (in ./test/out). The files in ./test/out should not be edited by hand. They should be generated dynamically by setting the environment variable REGEN to true, and then the tests should be checked against these files by setting REGEN to some other value. The resulting out-files can be drag-dropped into geojson.io to see, visually, if the module is behaving appropriately.

发布

¥Publishing

安装 lerna:

¥Install lerna:

$ npm install -g lerna@2.0.0-beta.34

发布测试版本：

¥Publish a test release:

$ lerna publish --canary

文档

¥Documentation

要更新 TurfJS 文档 (README.md)，请使用以下 npm run docs：

¥To update TurfJS's Documentation (README.md) use the following npm run docs:

• 模块内部：将仅生成该模块的文档。

  ¥inside a module: will only generate the docs of that module.

• 主文件夹：将为所有模块生成文档。

  ¥main folder: will generate docs for all modules.

示例

¥Examples

仅为 @turf/center 构建文档

¥Only builds docs for @turf/center

$ cd ./turf/packages/turf-center
$ npm run docs

> @turf/center@5.0.4 docs /Users/mac/Github/turf/packages/turf-center
> node ../../scripts/generate-readmes

Building Docs: @turf/center

为所有模块构建文档

¥Builds docs for all modules

$ cd ./turf
$ npm run docs
> @5.0.0 docs /Users/mac/Github/turf
> node ./scripts/generate-readmes

Building Docs: @turf/along
Building Docs: @turf/area
Building Docs: @turf/bbox-clip
Building Docs: @turf/bbox-polygon
Building Docs: @turf/bbox
Building Docs: @turf/bearing
Building Docs: @turf/bezier-spline
Building Docs: @turf/boolean-clockwise
....

其他依赖

¥Other Dependencies

• Turf 在测试、打包和发布过程中使用 Yarn 和 lerna。

  ¥Turf uses Yarn and lerna during the testing, packaging and publishing process.

  • 在根目录中运行 npm install 时，Lerna 将自动安装。

    ¥Lerna will be automatically installed when you run npm install in the root directory.

  • 你的计算机上需要安装 Yarn，安装程序可通过 Yarn 网站获取。

    ¥Yarn will need to be installed on your computer, installers are available via the yarn website.

资金贡献

¥Financial contributions

我们也欢迎对 开放集合 进行完全透明的财务贡献。任何人都可以提交费用。如果该支出对社区发展有意义，核心贡献者将在我们开放集体的账本中将其标记为 "merged"，提交该支出的人员将获得报销。

¥We also welcome financial contributions in full transparency on our open collective. Anyone can file an expense. If the expense makes sense for the development of the community, it will be "merged" in the ledger of our open collective by the core contributors and the person who filed the expense will be reimbursed.