archive-gh-me/turf
1
0
Fork 0
mirror of https://github.com/Turfjs/turf.git synced 2025-12-08 20:26:16 +00:00
Code Issues Projects Releases Wiki Activity

Revamped content and layout of project docs (README, CONTRIBUTING, etc) (#2770)

Browse Source 
* Moved "optional" project documentation files to docs/ subdir to minimise clutter in project root.

* Verbatim copy of Contributor Covenant v2.1. Updated code of conduct contact details, removing anyone who don't list obvious contact details (@lyzidiamond and @tcql).

* Split publishing topic out into a separate document. Only a small subset of contributors will ever publish so better to have CONTRIBUTING focus on coding and PR related activities.

* Updated issue and PR templates to read a bit better, ask for more meaningful details.

* Updating open collective stats, project goals for coming year.

* Split readme into a few pieces. Cut a lot of cut and paste commands (hard to guarantee currency). Removed REGEN references - think it's use should be discouraged, though probably differing opinions on that one!

Co-authored-by: mfedderly <24275386+mfedderly@users.noreply.github.com>
Co-authored-by: Tim Welch <tim.j.welch@gmail.com>

---------

Co-authored-by: mfedderly <24275386+mfedderly@users.noreply.github.com>
Co-authored-by: Tim Welch <tim.j.welch@gmail.com>
This commit is contained in:
James Beard 2024-12-28 14:34:02 +11:00 committed by GitHub
parent d1a2c5857f
commit a8cbea3a48
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
13 changed files with 522 additions and 566 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.github/ISSUE_TEMPLATE.md vendored
View File

@ -1,9 +1,10 @@
Please provide the following when reporting an issue:
- [ ] The version of Turf you are using, and any other relevant versions.
- [ ] GeoJSON data as a [gist file](https://gist.github.com/) or [geojson.io](http://geojson.io/) (filename extension must be `.geojson`).
- [ ] Snippet of source code or for complex examples use [jsfiddle](https://jsfiddle.net/).
- [ ] Verify this issue hasn't already been reported, or resolved in the latest alpha pre-release.
- [ ] Description of the problem, and how it differs from what you expected.
- [ ] Version of Turf you are using, and of any other relevant software.
- [ ] GeoJSON data as a [gist file](https://gist.github.com/) or [geojson.io](https://geojson.io/) (filename extension must be `.geojson`). Simple reproducible examples are preferrable.
- [ ] Snippet of source code for complex examples using [jsfiddle](https://jsfiddle.net/).
- [ ] Confirmation this issue hasn't already been reported, or is resolved and just hasn't been released yet.
<!-- Love turf? Please consider supporting our collective:
👉 https://opencollective.com/turf/donate -->

17
.github/PULL_REQUEST_TEMPLATE.md vendored
View File

@ -1,11 +1,8 @@
Please fill in this template. Use a meaningful title for the pull request. Include the name of the package modified.
Please provide the following when creating a PR:
- [ ] Is this a bug fix, new functionality, or a breaking change?
- [ ] Have read and followed the steps for [preparing a pull request](https://github.com/Turfjs/turf/blob/master/CONTRIBUTING.md#preparing-a-pull-request).
Submitting a new TurfJS Module.
- [ ] Overview description of proposed module.
- [ ] Include JSDocs with a basic example.
- [ ] Execute `./scripts/generate-readmes` to create `README.md`.
- [ ] Add yourself to **contributors** in `package.json` using "Full Name <@GitHub Username>".
- [ ] Meaningful title, including the name of the package being modified.
- [ ] Summary of the changes.
- [ ] Heads up if this is a breaking change.
- [ ] Any issues this [resolves](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests).
- [ ] Inclusion of your details in the `contributors` field of `package.json` - you've earned it! 👏
- [ ] Confirmation you've read the steps for [preparing a pull request](https://github.com/Turfjs/turf/blob/master/docs/CONTRIBUTING.md#preparing-a-pull-request).

75
CODE_OF_CONDUCT.md
View File

@ -1,75 +0,0 @@
# Code of Conduct
## Our Pledge
In the interest of fostering an open and welcoming environment, we as
contributors and maintainers pledge to making participation in our project and
our community a harassment-free experience for everyone, regardless of age, body
size, disability, ethnicity, gender identity and expression, level of experience,
nationality, personal appearance, race, religion, or sexual identity and
orientation.
## Our Standards
Examples of behavior that contributes to creating a positive environment
include:
* Using welcoming and inclusive language
* Being respectful of differing viewpoints and experiences
* Gracefully accepting constructive criticism
* Focusing on what is best for the community
* Showing empathy towards other community members
Examples of unacceptable behavior by participants include:
* The use of sexualized language or imagery and unwelcome sexual attention or
advances
* Trolling, insulting/derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or electronic
address, without explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Our Responsibilities
Project maintainers are responsible for clarifying the standards of acceptable
behavior and are expected to take appropriate and fair corrective action in
response to any instances of unacceptable behavior.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct, or to ban temporarily or
permanently any contributor for other behaviors that they deem inappropriate,
threatening, offensive, or harmful.
## Scope
This Code of Conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community. Examples of
representing a project or community include using an official project e-mail
address, posting via an official social media account, or acting as an appointed
representative at an online or offline event. Representation of a project may be
further defined and clarified by project maintainers.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported by contacting an organization admin: @morganherlocker, @lyzidiamond, @tcql, or @tmcw. All
complaints will be reviewed and investigated and will result in a response that
is deemed necessary and appropriate to the circumstances. The project team is
obligated to maintain confidentiality with regard to the reporter of an incident.
Further details of specific enforcement policies may be posted separately.
Project maintainers who do not follow or enforce the Code of Conduct in good
faith may face temporary or permanent repercussions as determined by other
members of the project's leadership.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
available at [http://contributor-covenant.org/version/1/4][version]
[homepage]: http://contributor-covenant.org
[version]: http://contributor-covenant.org/version/1/4/

337
CONTRIBUTING.md
View File

@ -1,337 +0,0 @@
## Getting Started
One of the most important things you can do is report bugs. Please reference [how to report a bug](http://polite.technology/reportabug.html) and when opening an [issue](https://github.com/Turfjs/turf/issues), follow the template.
To propose an enhancement for Turf, open an [issue](https://github.com/Turfjs/turf/issues), or start a [discussion](https://github.com/Turfjs/turf/discussions).
To make a code contribution, follow the steps for [how to contribute](#how-to-contribute).
## Architecture
- GeoJSON is the lingua franca of Turf. It should be used as the data structure for anything that can be represented as geography.
- Most work happens in sub modules. These are found in the `packages` directory prefixed with "turf-".
- Turf modules are small, containing a single exported function. This function is exported from a top-level index file.
- Many turf modules depend on other smaller Turf modules.
## How to contribute
If you don't have write access to the Turf repository (most will not), you will need to follow the [Github guidelines](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project) and fork the [Turf repo](https://github.com/Turfjs/turf) to your own account, create a feature branch, and open a Pull Request back to the main Turf repo.
If you do have write access to the Turf repo (core contributor), you can [clone](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) it locally. This is required for doing a [release](#release). You can also push feature branches directly to the Turf repo and open PR's against them. Consider prefixing your feature branch names with your initials (for example `tw/my-feature`).
If you'd like to become a core contributor, just start making contributions, and inquire.
### Local Setup
Once you've cloned a Turf repository, and have a terminal open and currenty in the top-level turf directory. Run the following:
- `git checkout master` (if not already)
- `corepack enable pnpm`
- enable pnpm as a package manager. Requires Node 16+. Alternatively just `npm install -g pnpm`.
- `pnpm install`
- install dependencies and build modules
- `pnpm test`
- run all tests and linters
You're now ready to contribute.
<details>
<summary>Structure of a Turf module</summary>
<br>
Turf modules are under the `packages` directory. For example `packages/turf-area`. Here's how they are structured.
```
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
```sh
$ node ./scripts/create-new-module <MODULE NAME>
```
it will create a new folder inside `packages` with a simple boilerplate for your module.
* `index.js` - This file contains, in order, the various modules you need to
import, the [JSDocs](http://usejsdoc.org) documentation, and, finally, the
single exported function that the module provides. For more on the types
supported in the documentation, see…
* `index.d.ts` - This is a [TypeScript](https://www.typescriptlang.org/) file
that describes your function’s signature. For more on the types supported in
TypeScript, see…
* `index.ts` - If you prefer to write Typescript instead of Javascript, use this
instead of index.js and index.d.ts.
* `bench.js` - This file uses [Benchmark](https://benchmarkjs.com/) to time
your function.
* `test.js` - This file includes your [tape](https://github.com/substack/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](https://askubuntu.com/a/58828) to `true`. If
`REGEN` is set to a different value, then running `pnpm t` will compare the
output of the tests to the files already present in `./test/out`.
* `types.ts` - A file that tests the custom TypeScript types declared in
`index.d.ts`.
* `package.json` - The [node](http://nodejs.org) 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`. `pnpm install` looks to this file to install dependencies
in `./node_modules`.
* `README.md` - This README is generated _automatically_ by running `pnpm run
docs` from the project root level. **DO NOT edit this file**.
* `LICENCE` - Like the README, this file should not be edited.
* `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](https://askubuntu.com/a/58828) `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](http://geojson.io) to see, visually, if the module is behaving
appropriately.
</details>
<details>
<summary>Development tips</summary>
<br>
Work in a feature branch when possible
- `git checkout -b my-feature`
- Create it right away off of master.
- This allows you to keep your local master branch clean and in sync with the official remote, for creating new branches at any time.
As you make code changes
- Run `npm test` from any submodule to make sure tests keep passing as you go. (for example `cd packages/turf-area` and `npm test`)
- Occasionally Run `npm test` at the top-level directory to run test for all modules.
- This will ensure that you haven't introduced errors affecting other turf modules.
</details>
<details>
<summary>Cleaning up</summary>
<br/>
To reset your current branch, throwing away any partial and uncommitted work
- `git reset --hard`
Merging branches, deleting branches and other management tasks are left for you to work out on your own.
</details>
<details>
<summary>Staying up to date</summary>
<br/>
To update your local master branch with the latest code for all branches from the Github remote `origin`.
- `git fetch remote`
</details>
## Preparing a pull request
A simple, complete pull request is more likely to get merged.
<details>
<summary>But I don't know how</summary>
<br>
If you don't know how to make a solid PR, just submit a draft PR, and ask for feedback. Then improve it and re-ask for feedback until it's ready.
</details>
### Pull Request Checklist
- Briefly summarize the need and solution. Link to the issue it's resolving if exists.
- Add tests. Even for bug fixes. Just a simple test case that reproduces the issue and demonstrates it's fixed.
- Update JSDoc comments if the function signature changes or docs need improvement (See for example `packages/turf-area/index.ts`)
- Run a full `npm test` at root level, confirming no cross-module issues. If you don't catch this now, the Github CI will.
### Guidelines
- Feel free to [ask](#getting-started) if a feature/enhancement is needed/wanted before doing the work.
- Keep pull requests small and focused.
- Avoid large dependencies at all costs.
- Make sure that your code can run in the browser (ie: don't make calls to external services, don't hit the filesystem, etc.).
### Doc generation
Know that module README.md files and https://turfjs.org API docs are auto-generated from JSDoc comments.
- As a contributor, all you need to do is update the JSDoc comments.
- For example if you change a top-level Turf functions signature (params, return type) or just want to improve the docs.
- JSDoc comments are found in the top-level index file for each module (for example `turf/packages/turf-area/index.ts`). For example look for `@name`, `@params`, `@returns`, `@example`.
## Code Style
We have lots of tooling dedicated to ensuring consistent code. We use [Prettier](https://prettier.io/), [Typescript](https://www.typescriptlang.org/), and [ESLint](https://eslint.org/) to help us deliver quality code. These are checked by the build system and should be enforced at commit time by [Husky](https://typicode.github.io/husky/#/).
Some of the modules are written in Typescript, others are still plain Javascript. In the javascript modules and any dependencies we include, it is important to only write ES5 code. This ensures good browser compatability for Turf users, and is checked at build time.
Making sure that the monorepo packages can be managed at scale, we use [Monorepolint](https://github.com/monorepolint/monorepolint) which allows us to programatically manage the various files in each package.
- Linters are run at commit time, using a pre-commit hook in `.husky/pre-commit`. See the package.json `lint:staged` section.
## Publishing
### Prerelease
A [prerelease](https://github.com/Turfjs/turf/blob/master/.github/workflows/prerelease.yml) action is available that publishes a canary release for every commit or PR merged to the master branch. However, this action is only [enabled](https://github.com/Turfjs/turf/actions/workflows/prerelease.yml) when needed.
When used, it publishes an alpha release to NPM (e.g. `7.0.0-alpha.116` where 116 is the number of commits to master since the last release tag).
- The version number is calculated by a combination of the output of `git describe` and the `publish:prerelease` script in the root package.json. It is typically setup to do a `minor` prerelease, but can be changed, such as prior to a `major` release.
### Release
A turf release is initiated from your local computer, and then built and published remotely via a github actions.
To make a release as a core contributor, you will need:
- Turf repository write permission
- Turf npm organization publish permission
- A clean local copy of the Turf Github repository (not a fork!). Starting with a fresh clone will ensure it's clean.
- Depending on your auth method
- `git clone git@github.com:Turfjs/turf.git turf-release`
- or `git clone https://github.com/Turfjs/turf.git turf-release`
- `cd turf-release` - start at the top-level of the repo
- `pnpm install`
- `pnpm test` - make sure everything is passing
- If you choose to clean up an existing copy instead, be very careful:
- `git remote -v` - verify your remote origin points to `https://github.com/Turfjs/turf.git`
- `git checkout master`
- `git reset --hard` - reset your local working copy, will lose any uncommitted or unstashed work!
- `git fetch origin` - fetch latest commits
- `git rev-list master...origin/master` - verify local master in sync with remote, command output should be empty
- `pnpm install`
- `pnpm test` - make sure everything is passing
Before release:
- If necessary, make and merge a PR with any last minute housekeeping items.
- Turf's documentation (README.md files) should already be up to date as it is generated automatically on commit from JSDoc comments in source files.
- Review PR's and decide the new version number to be published. See [semantic versioning](https://semver.org/).
Run the following release commands, replacing `7.0.0` with your version number:
- create a release branch and switch to it. All building, tagging and publishing will be done on the release branch, and then merged back into master in a later step.
- `git checkout origin/master -b release-7.0.0`
- increment the version number of all packages, and create a local commit, without pushing to origin. This will also create a release tag.
- `pnpm lerna version --no-commit-hooks --no-push 7.0.0`
- Push the release branch and the release tag.
- `git push origin release-7.0.0 --follow-tags`
- Pushing the tag will trigger the Github [release](https://github.com/Turfjs/turf/blob/master/.github/workflows/release.yml) action which you can view the status of at - https://github.com/Turfjs/turf/actions. If successful, a new [version](https://www.npmjs.com/package/@turf/turf?activeTab=versions) of all turf packages will have been published on NPM.
- If the release action was not successful
- commit any changes to master to fix it.
- Make a [prerelease](#prerelease) if helpful to make sure the release action is successful.
- Then reset by deleting your tag and branch locally and remotely.
- `git push --delete origin v7.1.0`
- `git tag --delete v7.1.0`
- `git push -d origin release-7.0.0`
- `git branch -d release-7.0.0`
- Now redo the steps above starting with creating "A clean local copy of the Turf Github repository"
- If the release action was successful, now create a Pull Request for the release to merge back to master.
- You may be given a link in the output of the branch/tag push command to create the PR.
- If you don't get this message, just go to https://github.com/Turfjs/turf/pulls and you should be prompted at the top to create a PR for this new branch you just pushed.
- If that prompt doesn't appear, then just create a new pull request from the PR page and make sure the title is the version number e.g. `v7.0.0` and that it is merging your release branch -> to master.
- Here is an example PR - https://github.com/Turfjs/turf/pull/2615.
- Get approval for the release PR, then "Squash and merge" it.
- Do not delete this branch in Github after merging, the release tag points to it. If you do, click "Restore branch" at the bottom of the merged PR.
#### Follow-on steps
- As part of the release action, a draft Github release will have been created at https://github.com/Turfjs/turf/releases with an auto-generated changelog.
- Edit and add to the release notes for readability and completeness, specifically noting any breaking changes. Use past releases as a guide.
- Be sure to "Save draft" each time, then ask for a review or edits from other contributors.
- Try not to leave the notes unpublished more than a day, people rely on these notes for upgrading.
- Once ready, click `Publish release`. This will make the release notes publicly accessible and notify all watchers of the project.
- You can edit and republish your release notes after this, but that will likely notify followers, so best to get it right the first time.
- Release a new version of the [API docs](https://github.com/Turfjs/turf-www/blob/master/CONTRIBUTING.md) for the https://turfjs.org website.
## Documentation
- API docs for each turf package are extracted from JSDoc comments in the source code into the top-level README.md files. README's are automatically updated on commit using via the pre-commit hook.
Should you want to generate new README files manually, use `pnpm run docs`:
- **inside a module:** will generate the docs for that module.
- **main folder:** will generate docs for all modules.
### Documentation - Examples
**Only build docs for `@turf/center`**
```bash
$ cd ./turf/packages/turf-center
$ pnpm 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**
```bash
$ cd ./turf
$ pnpm run docs
> @ docs /Users/mac/Github/turf
> tsx ./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
....
```
### Public website
The [turfjs.org](http://turfjs.org/) website is managed in a [separate repo](https://github.com/Turfjs/turf-www) with its own [contributing guide](https://github.com/Turfjs/turf-www/blob/master/CONTRIBUTING.md).
## Other Dependencies
- Turf uses [pnpm 8](https://pnpm.io/8.x) and [lerna](https://lernajs.io/) during the testing, packaging and publishing process.
- Lerna will be automatically installed when you run `pnpm install` in the root directory.
- Pnpm will need to be installed on your computer, installers are available via the pnpm website. When using [corepack](https://nodejs.org/api/corepack.html), this is automatically installed when running `pnpm`.
## Financial contributions
We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/turf).
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.
## Credits
### Contributors
Thank you to all the people who have already contributed to turf!
<a href="graphs/contributors"><img src="https://opencollective.com/turf/contributors.svg?width=890" /></a>
### Backers
Thank you to all our backers! [[Become a backer](https://opencollective.com/turf#backer)]
<a href="https://opencollective.com/turf#backers" target="_blank"><img src="https://opencollective.com/turf/backers.svg?width=890"></a>
### Sponsors
Thank you to all our sponsors! (please ask your company to also support this open source project by [becoming a sponsor](https://opencollective.com/turf#sponsor))
<a href="https://opencollective.com/turf/sponsor/0/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/1/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/2/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/3/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/4/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/5/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/6/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/7/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/8/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/9/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/9/avatar.svg"></a>

27
OPEN_COLLECTIVE.md
View File

@ -1,27 +0,0 @@
## About Turf.js
[TurfJS](http://turfjs.org/) is a modular geospatial analysis library for designed for use in the browser as well as Node.js.
We provide almost 150 modules for people to use freely in their applications.
Our most [popular module](https://www.npmjs.com/package/@turf/helpers) is downloaded 50,000 times a week via npm.
## Why we're looking for support
TurfJS is a community-driven project maintained by a small group of core contributors who work on the project in their spare time.
Time is spent supporting users, improving documentation, fixing bugs as well as creating new modules.
Your funding will directly go to development costs, marketing campaigns, promotional events & any other financial costs to operate & maintain TurfJS.
In particular, we're looking for corporate sponsors who use TurfJS in revenue-generating ways,
either by creating applications for clients, or through use in an app used by customers.
Of course individuals are welcome to support us as well if TurfJS has helped you :)
## 2017 Achievements
- Refactoring the codebase to support ES6 modules
- Adding approx 70 new modules/functions
- All new documentation
## Development goals for Turf.js in the coming year
- Removing our largest dependency (JSTS) to significantly reduce the size of our compiled code
- Add new modules to bring us closer to feature parity with other geospatial libraries

95
README.md
View File

@ -15,104 +15,33 @@
***A modular geospatial engine written in JavaScript***
[turfjs.org](https://turfjs.org/)
[Turf](https://turfjs.org) is a [JavaScript library](https://en.wikipedia.org/wiki/JavaScript_library) for [spatial analysis](https://en.wikipedia.org/wiki/Spatial_analysis). It includes traditional spatial operations, helper functions for creating [GeoJSON](https://geojson.org) data, and data classification and statistics tools. Turf can be added to your website as a client-side module, or you can [run Turf server-side](https://www.npmjs.com/package/@turf/turf) with [Node.js](https://nodejs.org/) (see below).
- - -
[Turf](https://turfjs.org) is a [JavaScript library](https://en.wikipedia.org/wiki/JavaScript_library) for [spatial analysis](https://en.wikipedia.org/wiki/Spatial_analysis). It includes traditional spatial operations, helper functions for creating [GeoJSON](https://geojson.org) data, and data classification and statistics tools. Turf can be added to your website as a client-side plugin, or you can [run Turf server-side](https://www.npmjs.com/package/@turf/turf) with [Node.js](https://nodejs.org/) (see below).
## Getting Started
## Installation
Read our [getting started guide](https://turfjs.org/docs/getting-started) to begin working with Turf.
### In Node.js
Or explore the Turf API and examples at [turfjs.org](https://turfjs.org/).
```bash
# get all of turf
npm install @turf/turf
## Runtime support
# or get individual packages
npm install @turf/helpers
npm install @turf/buffer
```
Turf is currently published to work with any reasonably modern Javascript runtime.
### In browser
Node is a first class citizen, and we recommend using an [Active or Maintenance LTS](https://nodejs.org/en/about/previous-releases) release.
Download the [minified file](https://npmcdn.com/@turf/turf/turf.min.js), and include it in a script tag. This will expose a global variable named `turf`.
```html
<script src="turf.min.js" charset="utf-8"></script>
```
You can also include it directly from a CDN:
```html
<script src="https://cdn.jsdelivr.net/npm/@turf/turf@6/turf.min.js"></script>
```
### TypeScript
Turf modules ship with type definitions packaged in each module. No DefinitelyTyped packages required.
The types defined in the GeoJSON specification are maintained separately (Geometry, Polygon, etc). To refer to these in your own code, install `@types/geojson` and import from there:
```typescript
import { type Polygon } from "geojson";
```
### Other languages
Ports of Turf.js are available in:
- [Java](https://github.com/mapbox/mapbox-java/tree/master/services-turf/src/main/java/com/mapbox/turf) (Android, Java SE)
- > [The current to-do list for porting to Java](https://github.com/mapbox/mapbox-java/blob/master/docs/turf-port.md)
- [Swift](https://github.com/mapbox/turf-swift/) (iOS, macOS, tvOS, watchOS, Linux)
- > Turf for Swift is **experimental** and its public API is subject to change. Please use with care.
- [Dart/Flutter](https://github.com/dartclub/turf_dart) (Dart Web, Dart Native; Flutter for iOS, Android, macOS, Windows, Linux, Web)
- > The Turf for Dart port is still in progress, the implementation status can be found in the [README](https://github.com/dartclub/turf_dart#components).
- - -
## Data in Turf
Turf uses <a href='https://geojson.org/'>GeoJSON</a> for all geographic data. Turf expects the data to be standard <a href='https://en.wikipedia.org/wiki/World_Geodetic_System'>WGS84</a> longitude, latitude coordinates. Check out <a href='https://geojson.io/#id=gist:anonymous/844f013aae8354eb889c&map=12/38.8955/-77.0135'>geojson.io</a> for a tool to easily create this data.
> **NOTE:** Turf expects data in (longitude, latitude) order per the GeoJSON standard.
Most Turf functions work with GeoJSON features. These are pieces of data that represent a collection of properties (ie: population, elevation, zipcode, etc.) along with a geometry. GeoJSON has several geometry types such as:
* Point
* LineString
* Polygon
Turf provides a few geometry functions of its own. These are nothing more than simple (and optional) wrappers that output plain old GeoJSON. For example, these two methods of creating a point are functionally equivalent:
```js
// Note order: longitude, latitude.
var point1 = turf.point([-73.988214, 40.749128]);
var point2 = {
type: 'Feature',
geometry: {
type: 'Point',
// Note order: longitude, latitude.
coordinates: [-73.988214, 40.749128]
},
properties: {}
};
```
Other runtimes, such as Deno or Bun, are not officially supported. We would be very interested to hear your experiences though.
## Browser support
Turf packages are compiled to target ES2017. However, the browser version of @turf/turf is transpiled to also include support for IE11. If you are using these packages and need to target IE11, please transpile the following packages as part of your build:
Turf uses Babel to transpile to a JavaScript version usable by most
modern browsers. Any browser that matches the following criteria as defined by [Browserslist](https://github.com/browserslist/browserslist):
```
@turf/*
robust-predicates
rbush
tinyqueue
```
[> 0.25%, last 2 versions, fully supports es5, not dead](https://browsersl.ist/#q=%3E+0.25%25%2C+last+2+versions%2C+fully+supports+es5%2C+not+dead)
## Contributors
This project exists thanks to all the people who contribute. If you are interested in helping, check out the [Contributing Guide](CONTRIBUTING.md).
This project exists thanks to all the people who contribute. If you are interested in helping, check out the [Contributing Guide](docs/CONTRIBUTING.md).
<a href="https://github.com/Turfjs/turf/graphs/contributors"><img src="https://opencollective.com/turf/contributors.svg?width=890&button=false" /></a>

30
SEE_ALSO.md
View File

@ -1,30 +0,0 @@
Geospatial analysis software has a few prominent strains:
* Esri & other closed-source, proprietary libraries
* Open source libraries in the lineage of JTS
# Python
* [Shapely](https://pypi.python.org/pypi/Shapely) is a friendly Python binding to GEOS
* [geopandas](http://geopandas.org/) is a layer on top of Shapely and Fiona for PostGIS-like tasks
# C++
* [GEOS](http://trac.osgeo.org/geos/) is a port of JTS to C++
# JavaScript
* [jsts](https://github.com/bjornharrtell/jsts) is a port of JTS to JavaScript
# Java
* [JTS](http://tsusiatsoftware.net/jts/main.html)
# Go
* [gogeos](http://paulsmith.github.io/gogeos/) is a Go binding to GEOS
* [go.geo](https://github.com/paulmach/go.geo) is a pure-Go implementation of some geometry operations and primitives
# Postgres
* [PostGIS](http://postgis.net/) provides geospatial operations within the Postgres database. Advanced operations rely on GEOS.

133
docs/CODE_OF_CONDUCT.md Normal file
View File

@ -0,0 +1,133 @@
# Contributor Covenant Code of Conduct
## Our Pledge
We as members, contributors, and leaders pledge to make participation in our
community a harassment-free experience for everyone, regardless of age, body
size, visible or invisible disability, ethnicity, sex characteristics, gender
identity and expression, level of experience, education, socio-economic status,
nationality, personal appearance, race, caste, color, religion, or sexual
identity and orientation.
We pledge to act and interact in ways that contribute to an open, welcoming,
diverse, inclusive, and healthy community.
## Our Standards
Examples of behavior that contributes to a positive environment for our
community include:
* Demonstrating empathy and kindness toward other people
* Being respectful of differing opinions, viewpoints, and experiences
* Giving and gracefully accepting constructive feedback
* Accepting responsibility and apologizing to those affected by our mistakes,
and learning from the experience
* Focusing on what is best not just for us as individuals, but for the overall
community
Examples of unacceptable behavior include:
* The use of sexualized language or imagery, and sexual attention or advances of
any kind
* Trolling, insulting or derogatory comments, and personal or political attacks
* Public or private harassment
* Publishing others' private information, such as a physical or email address,
without their explicit permission
* Other conduct which could reasonably be considered inappropriate in a
professional setting
## Enforcement Responsibilities
Community leaders are responsible for clarifying and enforcing our standards of
acceptable behavior and will take appropriate and fair corrective action in
response to any behavior that they deem inappropriate, threatening, offensive,
or harmful.
Community leaders have the right and responsibility to remove, edit, or reject
comments, commits, code, wiki edits, issues, and other contributions that are
not aligned to this Code of Conduct, and will communicate reasons for moderation
decisions when appropriate.
## Scope
This Code of Conduct applies within all community spaces, and also applies when
an individual is officially representing the community in public spaces.
Examples of representing our community include using an official email address,
posting via an official social media account, or acting as an appointed
representative at an online or offline event.
## Enforcement
Instances of abusive, harassing, or otherwise unacceptable behavior may be
reported to the community leaders responsible for enforcement at
[@morganherlocker](https://github.com/morganherlocker) or [@tmcw](https://github.com/tmcw).
All complaints will be reviewed and investigated promptly and fairly.
All community leaders are obligated to respect the privacy and security of the
reporter of any incident.
## Enforcement Guidelines
Community leaders will follow these Community Impact Guidelines in determining
the consequences for any action they deem in violation of this Code of Conduct:
### 1. Correction
**Community Impact**: Use of inappropriate language or other behavior deemed
unprofessional or unwelcome in the community.
**Consequence**: A private, written warning from community leaders, providing
clarity around the nature of the violation and an explanation of why the
behavior was inappropriate. A public apology may be requested.
### 2. Warning
**Community Impact**: A violation through a single incident or series of
actions.
**Consequence**: A warning with consequences for continued behavior. No
interaction with the people involved, including unsolicited interaction with
those enforcing the Code of Conduct, for a specified period of time. This
includes avoiding interactions in community spaces as well as external channels
like social media. Violating these terms may lead to a temporary or permanent
ban.
### 3. Temporary Ban
**Community Impact**: A serious violation of community standards, including
sustained inappropriate behavior.
**Consequence**: A temporary ban from any sort of interaction or public
communication with the community for a specified period of time. No public or
private interaction with the people involved, including unsolicited interaction
with those enforcing the Code of Conduct, is allowed during this period.
Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within the
community.
## Attribution
This Code of Conduct is adapted from the [Contributor Covenant][homepage],
version 2.1, available at
[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
Community Impact Guidelines were inspired by
[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
For answers to common questions about this code of conduct, see the FAQ at
[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
[https://www.contributor-covenant.org/translations][translations].
[homepage]: https://www.contributor-covenant.org
[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
[Mozilla CoC]: https://github.com/mozilla/diversity
[FAQ]: https://www.contributor-covenant.org/faq
[translations]: https://www.contributor-covenant.org/translations

219
docs/CONTRIBUTING.md Normal file
View File

@ -0,0 +1,219 @@
# Contributing to Turf
## Getting Started
One of the most important things you can do is report bugs. Please reference [how to report a bug](https://macwright.com/sites/polite.technology/reportabug) and when opening an [issue](https://github.com/Turfjs/turf/issues), follow the template.
To propose an enhancement for Turf, it's usually best to [start a discussion](https://github.com/Turfjs/turf/discussions) to work through the requirements. Unless you know exactly what you need! In which case [open an issue](https://github.com/Turfjs/turf/issues) to request it.
To make a code contribution, follow the steps for [how to contribute](#how-to-contribute).
## Architecture
- GeoJSON is the lingua franca of Turf. It should be used as the data structure for anything that can be represented as geography.
- Turf is broken into many submodules, or packages. These are found in the `packages` directory prefixed with "turf-".
- Turf packages are small, generally containing a single exported function.
- Many Turf packages depend on other lower level Turf packages.
## How to contribute
The best way for a new contributor to help with Turf is to find an open issue, fix it, and then share that back to the project via a pull request (PR). A maintainer will review your PR and get it merged with the rest of the code.
Here is a great article on how to fork a repo, and start contributing to Turf.
If you'd like to become a core contributor, just start making contributions, and inquire.
### Local Setup
Once you've cloned a Turf repository, and have a terminal open and currenty in the top-level turf directory. Run the following:
- `git checkout master` (if not already)
- `corepack enable pnpm`
- enable pnpm as a package manager. Requires Node 16+. Alternatively just `npm install -g pnpm`.
- `pnpm install`
- install dependencies and build packages
- `pnpm test`
- run all tests and linters
You're now ready to contribute.
<details>
<summary>Structure of a Turf package</summary>
<br>
Turf packages all live under the `packages` directory. For example `packages/turf-area`. Here's how they are structured.
```
turf-<PACKAGE NAME>
│ index.ts
│ bench.ts
│ test.ts
│ package.json
│ README.md
│ LICENSE
│
└───test
│
├───in
│ points.geojson
│
└───out
points.geojson
```
* `index.ts` - This file contains the definition of the function including [TypeScript](https://www.typescriptlang.org/) types, function implementation, the embedded [JSDocs](http://usejsdoc.org) documentation, and finally the single exported function that the package provides.
* `bench.ts` - This file uses [Benchmark](https://benchmarkjs.com/) to establish benchmark performance tests for your function.
* `test.ts` - This file includes your [tape](https://github.com/substack/tape)
unit tests. Tests can either be traditional code based tests, or tests that pull in data files and compare inputs to outputs (see below).
* `package.json` - The [node](http://nodejs.org) metadata container file.
Packages imported in `index.ts` should be listed here under `dependencies`,
and packages used in `test.ts` or `bench.ts` should be listed under
`devDependencies`.
* `README.md` - This README is generated _automatically_ by running `pnpm run
docs`. **DO NOT edit this file**.
* `LICENCE` - Like the README, this file should not be edited.
* `test/` - This directory holds the GeoJSON files that provide data for
dynamic tests. Input data in `./test/in`, and expected output data in `./test/out`.
</details>
<details>
<summary>Development tips</summary>
<br>
Work in a feature branch when possible
- `git checkout -b my-feature`
- Create it right away off of master.
- This allows you to keep your local master branch clean and in sync with the official remote. This will ease your ability to keep your local repo up to date with changes other people have made while you work on your feature.
As you make code changes
- Regularly run `pnpm test` in whatever package you are working in to avoid unintended bugs.
- Occasionally run `pnpm test` at the top-level directory to run test for all packages, to make sure you haven't introduced a problem that affects another package.
</details>
## Preparing a pull request
A simple, complete pull request is more likely to get merged.
<details>
<summary>But I don't know how</summary>
<br>
If you don't know how to make a solid PR, submit a draft PR and ask for feedback. Take on any feedback to improve the PR ready. There may be multiple rounds of feedback. While this seems tedious it greatly reduces the risk of someone else
having to revisit the same code any time soon.
</details>
### Pull Request Checklist
- Briefly summarize the need and solution. Link to the issue it's resolving if exists.
- Add tests. Even for bug fixes. A simple test case that reproduces the issue and demonstrates it's fixed.
- Update JSDoc comments if the function signature changes or docs need improvement (See for example `packages/turf-area/index.ts`)
- Run a full `npm test` at root level, confirming no cross-package issues. If you don't catch this now, the Github CI will.
### Guidelines
- Feel free to [ask](#getting-started) if a feature/enhancement is needed/wanted before doing the work.
- Keep pull requests small and focused.
- Avoid large dependencies at all costs.
- Make sure that your code can run in the browser (ie: don't make calls to external services, don't hit the filesystem, etc.).
### Documentation
The package README.md files and https://turfjs.org API docs are auto-generated from JSDoc comments in each packages' source file.
As a contributor, all you need to do is keep the JSDoc comments up to date, and the rest is automated. For example if you change a top-level Turf functions signature (params, return type) or just want to improve the descriptiveness of the docs.
JSDoc comments are found in the top-level index file for each package (for example `packages/turf-area/index.ts`). Look for the `@name`, `@params`, `@returns`, `@example` tags.
## Code Style
We have lots of tooling dedicated to ensuring consistent code. We use [Prettier](https://prettier.io/), [TypeScript](https://www.typescriptlang.org/), and [ESLint](https://eslint.org/) to help us deliver quality code. These are checked by the build system and should be enforced at commit time by [Husky](https://typicode.github.io/husky/#/).
Most packages are written in TypeScript, while a few plain Javascript still linger. You can generally use modern Javascript when modifying Turf itself as all exported code is transpiled to (currently es2017).
Code for consumption by browsers is transpiled by Babel as described in the README.
Making sure that the monorepo packages can be managed at scale, we use [Monorepolint](https://github.com/monorepolint/monorepolint) to programmatically ensure the individual packages remain consistent.
## Documentation
- API docs for each turf package are extracted from JSDoc comments in the source code into the top-level README.md files. README's are automatically updated on commit via a pre-commit hook.
Should you want to generate new README files manually, use `pnpm run docs`:
- **inside a package:** will generate the docs for that package.
- **from root folder:** will generate docs for all package.
### Documentation - Examples
**Build docs for only `@turf/center`**
```bash
$ cd ./turf/packages/turf-center
$ pnpm 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 packages**
```bash
$ cd ./turf
$ pnpm run docs
> @ docs /Users/mac/Github/turf
> tsx ./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
....
```
### Public website
The [turfjs.org](https://turfjs.org/) website is managed in a [separate repo](https://github.com/Turfjs/turf-www) with its own [contributing guide](https://github.com/Turfjs/turf-www/blob/master/CONTRIBUTING.md).
## Other Dependencies
- Turf uses [pnpm](https://pnpm.io/) and [lerna](https://lernajs.io/) during the testing, packaging and publishing process.
- Lerna will be automatically installed when you run `pnpm install` in the root directory.
- Pnpm will need to be installed on your computer, installers are available via the pnpm website. When using [corepack](https://nodejs.org/api/corepack.html), this is automatically installed when running `pnpm`.
## Financial contributions
We also welcome financial contributions in full transparency on our [open collective](https://opencollective.com/turf).
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.
## Credits
### Contributors
Thank you to all the people who have already contributed to turf!
<a href="graphs/contributors"><img src="https://opencollective.com/turf/contributors.svg?width=890" /></a>
### Backers
Thank you to all our backers! [[Become a backer](https://opencollective.com/turf#backer)]
<a href="https://opencollective.com/turf#backers" target="_blank"><img src="https://opencollective.com/turf/backers.svg?width=890"></a>
### Sponsors
Thank you to all our sponsors! (please ask your company to also support this open source project by [becoming a sponsor](https://opencollective.com/turf#sponsor))
<a href="https://opencollective.com/turf/sponsor/0/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/0/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/1/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/1/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/2/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/2/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/3/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/3/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/4/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/4/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/5/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/5/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/6/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/6/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/7/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/7/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/8/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/8/avatar.svg"></a>
<a href="https://opencollective.com/turf/sponsor/9/website" target="_blank"><img src="https://opencollective.com/turf/sponsor/9/avatar.svg"></a>

30
docs/OPEN_COLLECTIVE.md Normal file
View File

@ -0,0 +1,30 @@
## About Turf.js
[TurfJS](http://turfjs.org/) is a modular geospatial analysis library designed for use in the browser as well as Node.js.
We provide almost 120 modules for people to use freely in their applications.
Our most [popular module](https://www.npmjs.com/package/@turf/helpers) is downloaded 4,200,000 times a week via npm.
## Why we're looking for support
TurfJS is a community-driven project maintained by a small group of core contributors who work on the project in their spare time.
Time is spent investigating issues, supporting users, improving documentation, fixing bugs, and adding new functionality.
Your funding will go directly to development costs, marketing campaigns, promotional events, and other expenses needed to maintain and promote TurfJS.
In particular, we're looking for corporate sponsors who use TurfJS in revenue-generating ways, either by creating applications for clients, or through use in an app used by customers.
Of course individuals are welcome to support us as well if TurfJS has helped you :)
## 2024 Achievements
- First major release in a few years
- Modernised build and publishing infrastructure
- Merged many PRs that had been on hold
- Resolved several long standing bugs
- Overhauled the [documentation website](https://turfjs.org)
## Goals for 2025
- Continue to work through the bug backlog
- Release more often
- Encourage more contributors by engaging with PRs
- Resolve disparities between planar and spherical modes

76
docs/PUBLISHING.md Normal file
View File

@ -0,0 +1,76 @@
## Publishing
### Prerelease
A [prerelease](https://github.com/Turfjs/turf/blob/master/.github/workflows/prerelease.yml) action is available that publishes a canary release for every commit or PR merged to the master branch. However, this action is only [enabled](https://github.com/Turfjs/turf/actions/workflows/prerelease.yml) when needed.
When used, it publishes an alpha release to NPM (e.g. `7.0.0-alpha.116` where 116 is the number of commits to master since the last release tag).
- The version number is calculated by a combination of the output of `git describe` and the `publish:prerelease` script in the root package.json. It is typically setup to do a `minor` prerelease, but can be changed, such as prior to a `major` release.
### Release
A turf release is initiated from your local computer, and then built and published remotely via a github actions.
To make a release as a core contributor, you will need:
- Turf repository write permission
- Turf npm organization publish permission
- A clean local copy of the Turf Github repository (not a fork!). Starting with a fresh clone will ensure it's clean.
- Depending on your auth method
- `git clone git@github.com:Turfjs/turf.git turf-release`
- or `git clone https://github.com/Turfjs/turf.git turf-release`
- `cd turf-release` - start at the top-level of the repo
- `pnpm install`
- `pnpm test` - make sure everything is passing
- If you choose to clean up an existing copy instead, be very careful:
- `git remote -v` - verify your remote origin points to `https://github.com/Turfjs/turf.git`
- `git checkout master`
- `git reset --hard` - reset your local working copy, will lose any uncommitted or unstashed work!
- `git fetch origin` - fetch latest commits
- `git rev-list master...origin/master` - verify local master in sync with remote, command output should be empty
- `pnpm install`
- `pnpm test` - make sure everything is passing
Before release:
- If necessary, make and merge a PR with any last minute housekeeping items.
- Turf's documentation (README.md files) should already be up to date as it is generated automatically on commit from JSDoc comments in source files.
- Review PR's and decide the new version number to be published. See [semantic versioning](https://semver.org/).
Run the following release commands, replacing `7.0.0` with your version number:
- create a release branch and switch to it. All building, tagging and publishing will be done on the release branch, and then merged back into master in a later step.
- `git checkout origin/master -b release-7.0.0`
- increment the version number of all packages, and create a local commit, without pushing to origin. This will also create a release tag.
- `pnpm lerna version --no-commit-hooks --no-push 7.0.0`
- Push the release branch and the release tag.
- `git push origin release-7.0.0 --follow-tags`
- Pushing the tag will trigger the Github [release](https://github.com/Turfjs/turf/blob/master/.github/workflows/release.yml) action which you can view the status of at - https://github.com/Turfjs/turf/actions. If successful, a new [version](https://www.npmjs.com/package/@turf/turf?activeTab=versions) of all turf packages will have been published on NPM.
- If the release action was not successful
- commit any changes to master to fix it.
- Make a [prerelease](#prerelease) if helpful to make sure the release action is successful.
- Then reset by deleting your tag and branch locally and remotely.
- `git push --delete origin v7.1.0`
- `git tag --delete v7.1.0`
- `git push -d origin release-7.0.0`
- `git branch -d release-7.0.0`
- Now redo the steps above starting with creating "A clean local copy of the Turf Github repository"
- If the release action was successful, now create a Pull Request for the release to merge back to master.
- You may be given a link in the output of the branch/tag push command to create the PR.
- If you don't get this message, just go to https://github.com/Turfjs/turf/pulls and you should be prompted at the top to create a PR for this new branch you just pushed.
- If that prompt doesn't appear, then just create a new pull request from the PR page and make sure the title is the version number e.g. `v7.0.0` and that it is merging your release branch -> to master.
- Here is an example PR - https://github.com/Turfjs/turf/pull/2615.
- Get approval for the release PR, then "Squash and merge" it.
- Do not delete this branch in Github after merging, the release tag points to it. If you do, click "Restore branch" at the bottom of the merged PR.
#### Follow-on steps
- As part of the release action, a draft Github release will have been created at https://github.com/Turfjs/turf/releases with an auto-generated changelog.
- Edit and add to the release notes for readability and completeness, specifically noting any breaking changes. Use past releases as a guide.
- Be sure to "Save draft" each time, then ask for a review or edits from other contributors.
- Try not to leave the notes unpublished more than a day, people rely on these notes for upgrading.
- Once ready, click `Publish release`. This will make the release notes publicly accessible and notify all watchers of the project.
- You can edit and republish your release notes after this, but that will likely notify followers, so best to get it right the first time.
- Release a new version of the [API docs](https://github.com/Turfjs/turf-www/blob/master/CONTRIBUTING.md) for the https://turfjs.org website.

0
SECURITY.md → docs/SECURITY.md
View File

40
docs/SEE_ALSO.md Normal file
View File

@ -0,0 +1,40 @@
## Ports of Turf.js
Turf has been ported to several other languages, listed below.
- [Java](https://github.com/mapbox/mapbox-java/tree/master/services-turf/src/main/java/com/mapbox/turf) (Android, Java SE)
- > [The current to-do list for porting to Java](https://github.com/mapbox/mapbox-java/blob/master/docs/turf-port.md)
- [Swift](https://github.com/mapbox/turf-swift/) (iOS, macOS, tvOS, watchOS, Linux)
- > Turf for Swift is **experimental** and its public API is subject to change. Please use with care.
- [Dart/Flutter](https://github.com/dartclub/turf_dart) (Dart Web, Dart Native; Flutter for iOS, Android, macOS, Windows, Linux, Web)
- > The Turf for Dart port is still in progress, the implementation status can be found in the [README](https://github.com/dartclub/turf_dart#components).
## Other Geospatial Analysis Software
Below are other geospatial options that aren't specifically ports of Turf.
### Python
* [Shapely](https://pypi.python.org/pypi/Shapely) is a friendly Python binding to GEOS
* [geopandas](https://geopandas.org/) is a layer on top of Shapely and Fiona for PostGIS-like tasks
### C++
* [GEOS](https://libgeos.org/) is a port of JTS to C++
### JavaScript
* [jsts](https://github.com/bjornharrtell/jsts) is a port of JTS to JavaScript
### Java
* [JTS](https://www.tsusiatsoftware.net/jts/main.html)
### Go
* [gogeos](https://paulsmith.github.io/gogeos/) is a Go binding to GEOS
* [go.geo](https://github.com/paulmach/go.geo) is a pure-Go implementation of some geometry operations and primitives
### Postgres
* [PostGIS](https://postgis.net/) provides geospatial operations within the Postgres database. Advanced operations rely on GEOS.