From b768e06210af9bd4bb74315a4f2a7d59cd36b62a Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 15:36:46 +1100 Subject: [PATCH 01/12] Moving "optional" project documentation files to docs/ subdir to minimise clutter in project root. --- CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md | 0 CONTRIBUTING.md => docs/CONTRIBUTING.md | 0 OPEN_COLLECTIVE.md => docs/OPEN_COLLECTIVE.md | 0 SECURITY.md => docs/SECURITY.md | 0 SEE_ALSO.md => docs/SEE_ALSO.md | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename CODE_OF_CONDUCT.md => docs/CODE_OF_CONDUCT.md (100%) rename CONTRIBUTING.md => docs/CONTRIBUTING.md (100%) rename OPEN_COLLECTIVE.md => docs/OPEN_COLLECTIVE.md (100%) rename SECURITY.md => docs/SECURITY.md (100%) rename SEE_ALSO.md => docs/SEE_ALSO.md (100%) diff --git a/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md similarity index 100% rename from CODE_OF_CONDUCT.md rename to docs/CODE_OF_CONDUCT.md diff --git a/CONTRIBUTING.md b/docs/CONTRIBUTING.md similarity index 100% rename from CONTRIBUTING.md rename to docs/CONTRIBUTING.md diff --git a/OPEN_COLLECTIVE.md b/docs/OPEN_COLLECTIVE.md similarity index 100% rename from OPEN_COLLECTIVE.md rename to docs/OPEN_COLLECTIVE.md diff --git a/SECURITY.md b/docs/SECURITY.md similarity index 100% rename from SECURITY.md rename to docs/SECURITY.md diff --git a/SEE_ALSO.md b/docs/SEE_ALSO.md similarity index 100% rename from SEE_ALSO.md rename to docs/SEE_ALSO.md From e699409f685276eb008f3dd5a9c8541aafe49a5a Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 18:15:25 +1100 Subject: [PATCH 02/12] Verbatim copy of Contributor Covenant v2.1. --- docs/CODE_OF_CONDUCT.md | 152 +++++++++++++++++++++++++++------------- 1 file changed, 105 insertions(+), 47 deletions(-) diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 8da0e81feb..20bcc4f647 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -1,75 +1,133 @@ -# Code of Conduct + +# Contributor Covenant 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. +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 creating a positive environment -include: +Examples of behavior that contributes to a positive environment for our +community 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 +* 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 by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* 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 electronic - address, without explicit permission +* 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 -## Our Responsibilities +## Enforcement 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. +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. -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. +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 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. +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 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. +reported to the community leaders responsible for enforcement at +[INSERT CONTACT METHOD]. +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 -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. +**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 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +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]. -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ +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 From bfc1401d222f7bde6804d22825938737845a1cf9 Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 18:23:34 +1100 Subject: [PATCH 03/12] Updating code of conduct with contact details. Removed @lyzidiamond and @tcql as they don't currently list obvious contact details. --- docs/CODE_OF_CONDUCT.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CODE_OF_CONDUCT.md b/docs/CODE_OF_CONDUCT.md index 20bcc4f647..3c27eb0e77 100644 --- a/docs/CODE_OF_CONDUCT.md +++ b/docs/CODE_OF_CONDUCT.md @@ -61,7 +61,7 @@ representative at an online or offline event. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at -[INSERT CONTACT METHOD]. +[@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 From c88b6687837f767feb69c0608e9821945ee3fe5b Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 18:29:16 +1100 Subject: [PATCH 04/12] 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. --- docs/CONTRIBUTING.md | 77 -------------------------------------------- docs/PUBLISHING.md | 76 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 77 deletions(-) create mode 100644 docs/PUBLISHING.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 6a6fe4acc6..b0094c86d0 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -172,83 +172,6 @@ Making sure that the monorepo packages can be managed at scale, we use [Monorepo - 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. diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md new file mode 100644 index 0000000000..2ed0f16e39 --- /dev/null +++ b/docs/PUBLISHING.md @@ -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. From ae9e08de8647e053f4074dfeaf7cdf55228164e9 Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 18:54:02 +1100 Subject: [PATCH 05/12] Updated issue and PR templates to read a bit better, ask for more meaningful details. --- .github/ISSUE_TEMPLATE.md | 9 +++++---- .github/PULL_REQUEST_TEMPLATE.md | 17 +++++++---------- 2 files changed, 12 insertions(+), 14 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index da461ef289..6d5a0ef0ee 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -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. +- [ ] What you expected to happen, and what is happening instead. +- [ ] 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. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 3f8e381e81..a1b378770f 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -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. +- [ ] Categorisation as a bug fix, new functionality, or project housekeeping. +- [ ] Whether this is a breaking change. +- [ ] Which 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). From 5a88c88fc915f4bab46acba55859ee61e9f710cf Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 18:54:48 +1100 Subject: [PATCH 06/12] Updating open collective stats, project goals for coming year. --- docs/OPEN_COLLECTIVE.md | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/docs/OPEN_COLLECTIVE.md b/docs/OPEN_COLLECTIVE.md index 5fb33a304f..7d0a8b1a29 100644 --- a/docs/OPEN_COLLECTIVE.md +++ b/docs/OPEN_COLLECTIVE.md @@ -1,27 +1,30 @@ ## 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. +[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 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. +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. +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 +## 2024 Achievements - - Refactoring the codebase to support ES6 modules - - Adding approx 70 new modules/functions - - All new documentation + - 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) -## Development goals for Turf.js in the coming year +## Goals for 2025 - - 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 + - Continue to work through the bug backlog + - Release more often + - Encourage more contributors by engaging with PRs + - Resolve disparities between planar and spherical modes From 6526f3c7303358e128e87742f9878dc634efaa27 Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 19:13:41 +1100 Subject: [PATCH 07/12] Further revisions to issue and PR templates. --- .github/ISSUE_TEMPLATE.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 6d5a0ef0ee..caad9aceb4 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,6 +1,6 @@ Please provide the following when reporting an issue: -- [ ] What you expected to happen, and what is happening instead. +- [ ] 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/). diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index a1b378770f..5a40151ca6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,8 +1,8 @@ Please provide the following when creating a PR: - [ ] Meaningful title, including the name of the package being modified. -- [ ] Categorisation as a bug fix, new functionality, or project housekeeping. -- [ ] Whether this is a breaking change. -- [ ] Which issues this [resolves](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests). +- [ ] 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). From eb465457176af6019443fe249bbcd38b8c9a8505 Mon Sep 17 00:00:00 2001 From: James Beard Date: Mon, 16 Dec 2024 21:58:01 +1100 Subject: [PATCH 08/12] Split readme into a few pieces, including a new WIP getting started guide. 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! --- README.md | 93 ++++------------------------- docs/CONTRIBUTING.md | 127 ++++++++++++++-------------------------- docs/GETTING_STARTED.md | 70 ++++++++++++++++++++++ docs/SEE_ALSO.md | 38 +++++++----- 4 files changed, 148 insertions(+), 180 deletions(-) create mode 100644 docs/GETTING_STARTED.md diff --git a/README.md b/README.md index b9015da164..9a8a2b517f 100644 --- a/README.md +++ b/README.md @@ -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 plugin, or you can [run Turf server-side](https://www.npmjs.com/package/@turf/turf) with [Node.js](https://nodejs.org/) (see below). -## Installation - -### In Node.js - -```bash -# get all of turf -npm install @turf/turf - -# or get individual packages -npm install @turf/helpers -npm install @turf/buffer -``` - -### In browser - -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 - -``` - -You can also include it directly from a CDN: - -```html - -``` - -### 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 GeoJSON for all geographic data. Turf expects the data to be standard WGS84 longitude, latitude coordinates. Check out geojson.io for a tool to easily create this data. +## Getting Started -> **NOTE:** Turf expects data in (longitude, latitude) order per the GeoJSON standard. +Read our [getting started guide](docs/GETTING_STARTED.md) to begin working with Turf. -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: +Or explore the Turf API and examples at [turfjs.org](https://turfjs.org/). -* Point -* LineString -* Polygon +## Runtime support -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: +Turf is currently published to work with any reasonably modern Javascript runtime. -```js -// Note order: longitude, latitude. -var point1 = turf.point([-73.988214, 40.749128]); +Node is a first class citizen, and we recommend using an [Active or Maintenance LTS](https://nodejs.org/en/about/previous-releases) release. -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). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index b0094c86d0..8af35ff27c 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -1,22 +1,25 @@ +# Contributing to Turf + ## 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. +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, open an [issue](https://github.com/Turfjs/turf/issues), or start a [discussion](https://github.com/Turfjs/turf/discussions). +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. - 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. +- Turf modules are small, generally containing a single exported function. - 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. +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. -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`). +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. @@ -41,11 +44,9 @@ Turf modules are under the `packages` directory. For example `packages/turf-are ``` turf- -β”‚ index.js -β”‚ index.d.ts -β”‚ bench.js -β”‚ test.js -β”‚ types.ts +β”‚ index.ts +β”‚ bench.ts +β”‚ test.ts β”‚ package.json β”‚ README.md β”‚ LICENSE @@ -58,49 +59,20 @@ turf- └───out points.geojson ``` -To get started with a new module navigate to the root directory and run -```sh -$ node ./scripts/create-new-module -``` -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`. + +* `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 module 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. - 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`. + Modules imported in `index.ts` should be listed here under `dependencies`, + and modules used in `test.ts` or `bench.ts` should be listed under + `devDependencies`. * `README.md` - This README is generated _automatically_ by running `pnpm run - docs` from the project root level. **DO NOT edit this file**. + 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 (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. - + dynamic tests. Input data in `./test/in`, and expected output data in `./test/out`.
@@ -109,28 +81,11 @@ it will create a new folder inside `packages` with a simple boilerplate for your 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. +- 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 -- 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. -
- -
-Cleaning up -
-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. -
- -
-Staying up to date -
-To update your local master branch with the latest code for all branches from the Github remote `origin`. -- `git fetch remote` +- Regularly run `pnpm test` in whatever submodule you are working in to avoid unintended bugs. +- Occasionally run `pnpm test` at the top-level directory to run test for all modules, to make sure you haven't introduced a problem that affects another module.
## Preparing a pull request @@ -140,49 +95,52 @@ A simple, complete pull request is more likely to get merged.
But I don't know how
-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. +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.
### 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. +- 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-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 +### Documentation + +The module README.md files and https://turfjs.org API docs are auto-generated from JSDoc comments in each modules' source file. -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`. +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 module (for example `turf/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/#/). -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. +Most modules 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). -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. +Code for consumption by browsers is transpiled by babel as described in the README. -- Linters are run at commit time, using a pre-commit hook in `.husky/pre-commit`. See the package.json `lint:staged` section. +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 using via the pre-commit hook. +- 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 module:** will generate the docs for that module. - - **main folder:** will generate docs for all modules. + - **from root folder:** will generate docs for all modules. ### Documentation - Examples -**Only build docs for `@turf/center`** +**Build docs for only `@turf/center`** ```bash $ cd ./turf/packages/turf-center @@ -215,10 +173,11 @@ 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). +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 8](https://pnpm.io/8.x) and [lerna](https://lernajs.io/) during the testing, packaging and publishing process. + + - 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`. diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md new file mode 100644 index 0000000000..451028604f --- /dev/null +++ b/docs/GETTING_STARTED.md @@ -0,0 +1,70 @@ +## Installation + +### In Node.js + +```bash +# get all of turf +npm install @turf/turf + +# or get individual packages +npm install @turf/helpers +npm install @turf/buffer +``` + +### In browser + +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 + +``` + +You can also include it directly from a CDN: + +```html + +``` + +### TypeScript + +Turf modules ship with type definitions packaged in each module. No DefinitelyTyped packages required. + +The types defining 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 + +[Turf ports and GIS alternatives](SEE_ALSO.md). + + +## Data in Turf + +Turf uses GeoJSON for all geographic data. Turf expects the data to be standard WGS84 longitude, latitude coordinates. Check out geojson.io 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: {} +}; +``` diff --git a/docs/SEE_ALSO.md b/docs/SEE_ALSO.md index f26edea562..5adb1586ff 100644 --- a/docs/SEE_ALSO.md +++ b/docs/SEE_ALSO.md @@ -1,30 +1,40 @@ -Geospatial analysis software has a few prominent strains: +## Ports of Turf.js -* Esri & other closed-source, proprietary libraries -* Open source libraries in the lineage of JTS +Turf has been ported to several other languages, listed below. -# Python +- [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](http://geopandas.org/) is a layer on top of Shapely and Fiona for PostGIS-like tasks +* [geopandas](https://geopandas.org/) is a layer on top of Shapely and Fiona for PostGIS-like tasks -# C++ +### C++ -* [GEOS](http://trac.osgeo.org/geos/) is a port of JTS to C++ +* [GEOS](https://libgeos.org/) is a port of JTS to C++ -# JavaScript +### JavaScript * [jsts](https://github.com/bjornharrtell/jsts) is a port of JTS to JavaScript -# Java +### Java -* [JTS](http://tsusiatsoftware.net/jts/main.html) +* [JTS](https://www.tsusiatsoftware.net/jts/main.html) -# Go +### Go -* [gogeos](http://paulsmith.github.io/gogeos/) is a Go binding to GEOS +* [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 +### Postgres -* [PostGIS](http://postgis.net/) provides geospatial operations within the Postgres database. Advanced operations rely on GEOS. +* [PostGIS](https://postgis.net/) provides geospatial operations within the Postgres database. Advanced operations rely on GEOS. From 017a5cc71332dcc3d21beac7cee988b75ebd5567 Mon Sep 17 00:00:00 2001 From: James Beard Date: Fri, 20 Dec 2024 21:48:32 +1100 Subject: [PATCH 09/12] Apply suggestions from code review Fixed a couple of spelling errors. Co-authored-by: mfedderly <24275386+mfedderly@users.noreply.github.com> --- README.md | 2 +- docs/CONTRIBUTING.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 9a8a2b517f..41c0ffea6f 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,7 @@ Other runtimes, such as Deno or Bun, are not officially supported. We would be v ## Browser support -Turf uses babel to transpile to a JavaScript version usable by most +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): [> 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) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8af35ff27c..7cd2b879c5 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -122,11 +122,11 @@ JSDoc comments are found in the top-level index file for each module (for exampl ## 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/#/). +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 modules 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). +Most modules 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. +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. From 634cb028d47602a5316cf3490eeac8ee4cf985de Mon Sep 17 00:00:00 2001 From: James Beard Date: Sat, 21 Dec 2024 23:28:09 +1100 Subject: [PATCH 10/12] Changed to use 'package' rather than 'module'. --- docs/CONTRIBUTING.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 7cd2b879c5..d42ba66070 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -11,9 +11,9 @@ To make a code contribution, follow the steps for [how to contribute](#how-to-co ## 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, generally containing a single exported function. -- Many turf modules depend on other smaller Turf modules. +- 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 @@ -30,20 +30,20 @@ Once you've cloned a Turf repository, and have a terminal open and currenty in t - `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 + - install dependencies and build packages - `pnpm test` - run all tests and linters You're now ready to contribute.
-Structure of a Turf module +Structure of a Turf package
-Turf modules are under the `packages` directory. For example `packages/turf-area`. Here's how they are structured. +Turf packages all live under the `packages` directory. For example `packages/turf-area`. Here's how they are structured. ``` -turf- +turf- β”‚ index.ts β”‚ bench.ts β”‚ test.ts @@ -60,13 +60,13 @@ turf- 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 module provides. +* `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. - Modules imported in `index.ts` should be listed here under `dependencies`, - and modules used in `test.ts` or `bench.ts` should be listed under + 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**. @@ -84,8 +84,8 @@ Work in a feature branch when possible - 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 submodule you are working in to avoid unintended bugs. -- Occasionally run `pnpm test` at the top-level directory to run test for all modules, to make sure you haven't introduced a problem that affects another module. +- 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.
## Preparing a pull request @@ -103,7 +103,7 @@ having to revisit the same code any time soon. - 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-module issues. If you don't catch this now, the Github CI will. +- 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 @@ -114,17 +114,17 @@ having to revisit the same code any time soon. ### Documentation -The module README.md files and https://turfjs.org API docs are auto-generated from JSDoc comments in each modules' source file. +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 module (for example `turf/packages/turf-area/index.ts`). Look for the `@name`, `@params`, `@returns`, `@example` tags. +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 modules 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). +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. @@ -135,8 +135,8 @@ Making sure that the monorepo packages can be managed at scale, we use [Monorepo - 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 module:** will generate the docs for that module. - - **from root folder:** will generate docs for all modules. + - **inside a package:** will generate the docs for that package. + - **from root folder:** will generate docs for all package. ### Documentation - Examples @@ -152,7 +152,7 @@ $ pnpm run docs Building Docs: @turf/center ``` -**Builds docs for all modules** +**Builds docs for all packages** ```bash $ cd ./turf From d8270d611688c37f25b04b33f2f54fc5af6a3f3c Mon Sep 17 00:00:00 2001 From: James Beard Date: Sat, 28 Dec 2024 11:58:32 +1100 Subject: [PATCH 11/12] Describe Turf as a client side "module" rather than a "plugin". Co-authored-by: Tim Welch --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 41c0ffea6f..dccf108b7a 100644 --- a/README.md +++ b/README.md @@ -15,7 +15,7 @@ ***A modular geospatial engine written in JavaScript*** -[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). +[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). ## Getting Started From feb8f80cedcaf7425f13d55ecd0be3fcf1fd25cd Mon Sep 17 00:00:00 2001 From: James Beard Date: Sat, 28 Dec 2024 13:23:50 +1100 Subject: [PATCH 12/12] Per PR suggestion point README to getting started guide on website instead of a duplicated file in docs/. --- README.md | 2 +- docs/GETTING_STARTED.md | 70 ----------------------------------------- 2 files changed, 1 insertion(+), 71 deletions(-) delete mode 100644 docs/GETTING_STARTED.md diff --git a/README.md b/README.md index dccf108b7a..3f63130d3e 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ ## Getting Started -Read our [getting started guide](docs/GETTING_STARTED.md) to begin working with Turf. +Read our [getting started guide](https://turfjs.org/docs/getting-started) to begin working with Turf. Or explore the Turf API and examples at [turfjs.org](https://turfjs.org/). diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md deleted file mode 100644 index 451028604f..0000000000 --- a/docs/GETTING_STARTED.md +++ /dev/null @@ -1,70 +0,0 @@ -## Installation - -### In Node.js - -```bash -# get all of turf -npm install @turf/turf - -# or get individual packages -npm install @turf/helpers -npm install @turf/buffer -``` - -### In browser - -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 - -``` - -You can also include it directly from a CDN: - -```html - -``` - -### TypeScript - -Turf modules ship with type definitions packaged in each module. No DefinitelyTyped packages required. - -The types defining 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 - -[Turf ports and GIS alternatives](SEE_ALSO.md). - - -## Data in Turf - -Turf uses GeoJSON for all geographic data. Turf expects the data to be standard WGS84 longitude, latitude coordinates. Check out geojson.io 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: {} -}; -```