MongoDB Documentation Front-End

Uses Gatsby to build static site.

Installation

npm install

If this is your first time running the site you'll need the static directory:

make static

.env file setup

You'll need to set some environment variables in two separate files at the root of this directory for separate production/development environments.

.env.production

Snooty's build and serve stages use the production environment. Your .env.production file should be as follows:

GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true

.env.development

Snooty's develop stage uses the development environment. Your .env.development file should be as follows:

GATSBY_SITE=<SITE>
GATSBY_PARSER_USER=<USER>
GATSBY_PARSER_BRANCH=<BRANCH>
GATSBY_SNOOTY_DEV=true

The GATSBY_SNOOTY_DEV variable is what allows Gatsby to know that when the application is built it should use the snooty branch name as part of the file paths. When not set, the file paths will use the value of GATSBY_PARSER_BRANCH.

It should be set to true when working on snooty locally.

Running locally

npm run develop

To build and serve the site, run the following commands:

$ npm run build
$ npm run serve

Staging

Install mut and ensure that you have properly configured your Giza/AWS keys. Then, from root, run:

make stage

Releasing

We have configured an automatic release process using GitHub Actions that is triggered by npm-version. To release a version, run npm version [major | minor | patch], using Semantic Versioning guidelines to correctly increment the version number. GitHub Actions will create a new git tag and push it to GitHub. To complete the process, update the release notes using the automatically generated CHANGELOG.md and publish the release.

Testing

Tests can be run using:

npm test  # alias for npm run test

Unit tests

Unit tests are located in the tests/unit/ directory. To run only unit tests, use:

npm run test:unit

Running individual suites

Jest includes configurations for running individual test suites:

npm test -- my-test   # or
npm test -- path/to/my-test.js

For more information, see the Jest CLI Options documentation, or run npm test -- --help.

Linting & Style

We use ESLint and Prettier to help with linting and style.

Lint

Our CI (via GitHub Actions) is configured to test for lint errors. To run this test locally and attempt to automatically fix errors:

npm run lint:fix

These errors must be fixed for the CI build to pass.

Style

To format code using Prettier, run the following command:

npm run format:fix

We have set up a precommit hook that will format staged files. Prettier also offers a variety of editor integrations to automatically format your code.