Skip to content

Latest commit

 

History

History
270 lines (188 loc) · 11.4 KB

CONTRIBUTING.md

File metadata and controls

270 lines (188 loc) · 11.4 KB
Raw

Contributing Guide

Commitizen friendly Linting: ESLint Code format: Prettier Style Guide: Airbnb jest semantic-release: angular

Thank you for contributing to jest-geojson!

Before contributing, please take a moment to read through this document. This guide documents the standards, tooling, and processes that go into the CI/CD pipeline.

Table of Contents

Code of Conduct

Please help keep this project open and inclusive. Refer to the Code of Conduct before your first contribution.

How can I Contribute?

Submit Issues

Bug Reports: Be as detailed as possible, and fill out all information requested in the bug report template.

For security related issues, see the security policy.

Documentation Requests: Is something unclear in the documentation or the API? Submit a documentation change request! Be as detailed as possible. If you have the question, chances are someone else will also who isn't as willing to speak up as you are. If you want to do it yourself, see the documentation guidelines for instructions.

Propose New Matchers

These are welcome! Before submitting:

  • Take a moment to make sure your matcher idea fits within the scope and aims of this project. Remember, jest-geojson exports ONLY matchers for Jest to aide test driven developers, not generic GeoJSON functions. For that, refer to Turf.js.
  • Search the issues for new matchers to make sure this isn't already in the works.
  • Be as detailed as possible, and fill out a new matcher request. It is up to you to make your case of why the matcher should get included.

Please ask before embarking on any significant undertaking (e.g. implementing a new matcher, major code refactoring), otherwise you risk wasting time on something that might not fit well with the project. Do this by opening an issue for the proposal.

Submit a Pull Request

Good pull requests are outstanding help. They should remain focused in scope and avoid unrelated commits.

To submit a pull request,

  1. Fork and clone the repository
  2. Create a branch for your edits
  3. Make sure your work follows the commits guidance

New Matcher Submission Checklist

  • Open an issue with detailed description of the purpose and required behavior
  • Create Core Function
    • Create a core function under src/core/<category>
    • Document the function using JSDoc. Refer to the issue.
    • Register the core function in src/core.js
    • Add a verification test to tests/core.test.js
  • Create Matcher Function
    • Create a matcher function under src/matchers/<category>
    • Document the matcher using JSDoc. Refer to the issue.
    • Register the matcher in src/matchers.js
    • Add a verification test to matchers.test.js
    • Add the matcher to the .cz-config.js list (alphabetical order under the coordinateMatchers variable)
  • Create a test for the matcher under tests/<category>
  • Verify all tests pass and have 100% coverage
  • Add the matcher to the README.md list (alphabetical order within category)
  • Run the build script locally
  • Push to Github then open pull request

Commits

All commits must follow the common commit guidance in @m-scott-lassiter/semantic-release-github-npm-config.

This project uses Commitizen and Husky hooks to help enforce good commit practices. Work on matcher functions must use that matcher function name as the scope.

When adding a new matcher, you must update this project's Commitizen configuration so the matcher shows up in the scope list.

Development

Local Installation

git clone https://github.com/M-Scott-Lassiter/jest-geojson.git
cd jest-geojson
npm install

Project Structure

All distribution files are contained in the src folder. The tests folder contains the scripts used to verify the matchers work as designed (using the matchers themselves!).

core contains the functions that matchers use.

├── src
│   ├── core
│   │   ├── boundingBoxes
│   │   ├── coordinates
│   │   ├── features
│   │   ├── featureCollections
│   │   ├── functional
│   │   ├── geometries
│   │   └── geometryCollections
│   ├── matchers
│   │   ├── boundingBoxes
│   │   ├── coordinates
│   │   ├── features
│   │   ├── featureCollections
│   │   ├── functional
│   │   ├── geometries
│   │   └── geometryCollections
│   ├── setup
│   │   ├── all.js
│   │   ├── boundingBoxes.js
│   │   └── coordinates.js
|   ├── index.js
|   └── JestSetup.js
├── tests
│   │   ├── boundingBox
│   │   ├── coordinate
│   │   ├── feature
│   │   ├── featureCollection
│   │   ├── functional
│   │   ├── geometry
│   │   └── geometryCollection

The index.js serves two functions:

  • Document the project's JSDoc type definitions
  • Export each matcher function individually

When adding a new matcher, refer to the comments at the top of index.js for instructions.

Building

After installing, run Before submitting changes, run the build script locally, then commit:

npm run build

This will lint, test, document, and format everything automatically.

You should run this script after installing to verify you do not encounter run time errors before you get started.

Linting and Formatting

Prettier provides formatting, and ESLint does linting using the Airbnb style guide. To lint, run the following:

npm run lint  # Runs ESLint

npm run format  # Runs Prettier

Running Tests

This project provides high working confidence to developers by uses Jest itself for unit testing. Test locally using one of the following scripts:

npm run test # Runs all tests and generates coverage report

npm run test:dev # Runs tests in watch mode

Documentation

API Documentation is automatically generated from JSDoc comments within the scripts. To generate, run:

npm run docs

The table of contents in this guide and the main README are automatically generated using the markdown-toc package. To generate, run:

npm run tableofcontents

Adding New Matchers

Creating Core Functions

All matcher functionality should have a core function that goes along with it. This goes under the src/core/<category> folder.

The corresponding matcher goes under src/matchers/<category>.

Creating New Tests

Tests reside separately from the source code.

Provide 100% test coverage when creating new matchers. Use the opened issue to fully describe and document the logic on how this matcher works. This provides a persistent reference point for the logic that drives the tests.

The Jest configuration file calls a setup script before the test suite runs that extends Jest's built in matchers with all of the jest-geojson matchers. This is consistent with how it will get used by other developers in their own projects.

For consistency, organize your tests under the following three describe blocks:

  • Valid Use Cases
  • Invalid Use Cases
  • Error Snapshot Testing

Refer to any of the test files for an example.

Error Snapshot Testing

Because matchers return the message as an arrow function, Jest doesn't actually execute these when running which prevents getting code coverage to 100% by normal methods.

To make sure these messages work correctly, you need to use Jest's toThrowErrorMatchingSnapshot matcher. Put these in their own describe block.

describe('Error Snapshot Testing', () => {
    test('.not.isValid2DCoordinate', () => {
        expect(() => expect([0, 0]).not.isValid2DCoordinate()).toThrowErrorMatchingSnapshot()
    })

    test('.isValid2DCoordinate', () => {
        expect(() => expect(false).isValid2DCoordinate()).toThrowErrorMatchingSnapshot()
    })
})

Updating Error Snapshots

If you change the error messages, the snapshots will also change. Once you manually verify it still works as intended, update the snapshot:

npm run test -- -u

Export Both Core and Matcher Functions

The files src/core.js and src/matchers.js each export their respective functions within an object for each category. Add any new matcher or function in alphabetical order under the appropriate category.

Ensure tests/core.test.js and tests/matchers.test.js each have a test that verifies the function and matcher successfully export.