Skip to content

Latest commit

 

History

History
258 lines (176 loc) · 11.7 KB

CONTRIBUTING.md

File metadata and controls

258 lines (176 loc) · 11.7 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 and their core GeoJSON validation functions. This project DOES NOT manipulate or create GeoJSON objects. 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

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

├── src
│   ├── core
|   │   └── <categories>
│   ├── matchers
|   │   └── <categories>
│   ├── setup
|   ├── core.js
|   ├── matchers.js
|   └── typedefinitions.js
├── tests
|   ├── <categories>
│   ├── core.test.js
|   └── matchers.test.js
  • src: contains all distribution files
    • core: contains the key functionality used throughout
    • matchers: contains the matchers powered by the core functions
    • setup: contains the scripts that install the matchers into the Jest runtime
    • core.js and matchers.js: export a single object containing their categories as object members, each with their respective functions
    • typedefinitions.js: documents the project's JSDoc type definitions and contains no actual code
    • index.d.ts: Typescript definitions for the matchers
  • tests: the Jest scripts used to verify the matchers work as designed

package.json contains entry points for core.js, matchers.js, and each of the loading scripts in setup.

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

Checklist

Before pushing to Github and opening a pull request:

  • Open an issue with detailed description of the purpose and required behavior
  • Create Core Function (If Applicable)
    • 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 tests/matchers.test.js
    • Add the matcher to src/index.d.ts
    • Add the matcher to the .cz-config.js list (alphabetical order under the allMatchers 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

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 and do not get distributed with the NPM package.

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

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

Additionally, 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. For example:

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

    test('Invalid input to matcher', () => {
        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 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.