Skip to content

Latest commit

 

History

History
135 lines (99 loc) · 7 KB

CONTRIBUTING.md

File metadata and controls

135 lines (99 loc) · 7 KB

Contributing

Welcome!

We're excited for your interest in Greenwood, and maybe even your contribution!

Issues

Please make sure to have the following prepared (where applicable)

  1. High Level Overview
  2. For bugs, please provide steps to reproduce
  3. Code Sample
  4. Links / references

Pull Requests

Pull requests are the best! To best help facililate contributions to the project, here are some requests:

  • We generally we prefer an issue be opened first, to help faciliate general discussion outside of the code review process itself and align on the ask and any expections. However, for typos in docs and minor "chore" like tasks a PR is usually sufficient. When in doubt, open an issue.
  • For bugs, please consider reviewing the issue tracker.
  • For branching, we generally follow the convention <issue-label>/issue-<number>-<issue-title>, e.g. bug/issue-12-fixed-bug-with-yada-yada-yada
  • To test the CI build scripts locally, run the yarn commands mentioned in the below section on CI.

Continuous Integration

Greenwood makes active use of testing tools like GitHub Actions and Netlify deploy previews as part of the workflow. Each time a PR is opened, a sequence of build steps defined .github/workflows/ci..yml are run:

  1. Linting: yarn lint
  2. Running unit tests: yarn test
  3. Building the Greenwood website: yarn build

A preview is also made available within the status checks section of the PR in GitHub and can be used to validate work in a live environment before having to merge.

Local Development

To develop for the project, you'll want to follow these steps:

  1. Have NodeJS LTS installed (>= 10.x) and Yarn
  2. Clone the repository
  3. Run yarn install
  4. Run yarn lerna bootstrap

Tasks

The Greenwood website is currently built by Greenwood itself, and all files for it are located in this repository in the www/ directory. In addition to unit tests, you will want to verify all changes by running the website locally.

Below are the development tasks available for working on this project:

  • yarn develop - Develop for the website locally using the dev server at localhost:1984 in your browser.
  • yarn build - Builds the website for production.
  • yarn serve - Builds the website for production and runs it on a local webserver at localhost:8000

Packages

Greenwood is organized into packages as a monorepo, managed by Lerna and Yarn Workspaces. You can find all of these in the packages/ directory. Each package will manage its own:

  • Dependencies
  • README
  • Test Cases

Lerna (specifically lerna publish) will be used to release all packagess under a single version. Lerna configuration can be found in lerna.json.

Dependencies

To yarn add / yarn remove packages from anything in packages/ or www/, please make sure you cd into the directory with the package.json first.

For example

$ cd packages/cli
$ yarn add <package>

Yarn workspaces will automatically handle installing node_modules in the appropriate directory.

Unit Testing

TDD is the recommended approach for developing for Greenwood and for the style of test writing we use BDD style testing; "cases". Cases are used to capture the various configurations and expected outputs of Greenwood when running its commands, in a way that is closer to how a user would be expecting Greenwood to work.

Running Tests

To run tests in watch mode, use:

$ yarn test:tdd

To verify compliance with coverage and watermark thresholds (what CI server runs), use:

$ yarn test

Below are some tips to help with running / debugging tests:

  • describe.only / it.only: only runs this block
  • xdescribe / xit: dont run this block
  • Uncomment setup.teardownTestBed() in a case to see the build output without it getting cleaned up post test run
  • Use new TestBed(true) get debug output from Greenwood when running tests

PLEASE DO NOT COMMIT ANY OF THESE ABOVE CHANGES THOUGH

Writing Tests

Cases follow a convention starting with the command (e.g. build) and and the capability and features being tested, like configuration with a particular option (e.g. publicPath):

<command>.<capability>.<feature>.spec.js

Examples:

  • build.default.spec.js - Would test greenwood build with no config and no workspace.
  • build.config.workspace-custom.spec.js - Would test greenwood build with a config that had a custom workspace
  • build.config.workspace-public-path.spec.js - Would test greenwood build with a config that had a custom workspace and publicPath set.

Notes

Here are some thigns to keep in mind while writing your tests, due to the asynchronous nature of Greenwwood:

  • Make sure to wrap all calls to TestBed with async
  • All usages of JSDOM should be wrapped in async
  • Avoid arrow functions in mocha tests (e.g. () => ) as this can cause unexpected behaviors.. Just use function instead.

Internet Explorer

For situations that require testing Internet Explorer or Edge browser, Microsoft provides Virtual Machines for various combinations of Windows and Internet Explorer versions. VirtualBox is a good platform to use for these VMs.

To test from a VM, you can

  1. Run yarn serve
  2. From the VM, open http://10.0.2.2:8000 in the browser

You can disable plugins in webpack.config.prod.js to remove production optimizations for testing purposes.

Docker

A Docker container is available within the project to use as a development environment if you like. It is configured to use the same image that runs as part of the project's Continuous Integration environment.

First make sure you have Docker installed.

Then from the root of this repository do the following:

  1. Build the container: $ docker build -t nodejs-dev .
  2. Connect to the container: $ docker run --name greenwood -v $(pwd):/workspace -i -t nodejs-dev
  3. Now you can run all the usual commands, e.g.
  • $ yarn install
  • $ yarn build
  • $ yarn test

This will create a 2 way binding between your host and the container, so file changes will go both ways between the host and container.

When you're done with the container:

  1. Exit the container: $ exit
  2. Destroy the container: $ docker rm greenwood

Note: If you have issues running tests due to timeouts, you can increase the setting in package.json