Skip to content

Latest commit

 

History

History
262 lines (178 loc) · 11.6 KB

CONTRIBUTING.md

File metadata and controls

262 lines (178 loc) · 11.6 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>
    • Register the core function in src/core.js
    • Add a verification test to tests/core.test.js
    • Document the function using JSDoc. Refer to the issue. Include good and bad examples.
  • Create Matcher Function
    • Create a matcher function under src/matchers/<category>
    • 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)
    • Document the matcher using JSDoc. Refer to the issue. Include good and bad examples.
  • 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

After installing, you should run the build script to verify everything works without runtime errors before you start modifying.

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.

setup contains the scripts that install the matchers into the Jest runtime. package.json references these in entry points.

├── src
│   ├── core
│   ├── matchers
│   ├── setup
|   ├── core.js
|   ├── matchers.js
|   └── typedefinitions.js
├── tests
│   ├── core.test.js
|   └── matchers.test.js

The core, matchers, setup, and tests folder each have the same subfolder structure:

├── boundingBoxes
├── coordinates
├── features
├── featureCollections
├── functional
├── geometries
└── geometryCollections

The core.js and matchers.js consolidate and export their respective elements grouped by folder structure category. When adding a new matcher, refer to the instructions in the comments at the top of these files.

typedefinitions.js document the project's JSDoc type definitions and contains no actual code.

Building

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

npm run build # lint, test, document, and format everything automatically

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:<type> #runs the tests only in that category
npm run watch # Runs tests in watch mode

This requires at least Jest v24.0.0 (specified as a peer dependency) due to the use of setupFilesAfterEnv.

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()
    })
})

To ensure code refactoring doesn't result in vague error messages, ensure there is at least one snapshot covering each expected error message.

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 using one of the following:

npm run test -- -u
npm run test:<type> -- -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.