MongoDB Documentation Front-End

Uses Gatsby to build static site.

Installation

npm install --legacy-peer-deps

.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

⚠️ Note: This will promote the contents of your local public directory. Your instance in staging may break or be outdated if you haven't run npm run build before make stage.

Releasing

We have configured an automatic release process using GitHub Actions that is triggered by npm-version. To release a version, you must have admin privileges in this repo. Then proceed as follows:

1. On the master branch, run git pull followed by npm ci.
2. Run npm version [major | minor | patch], using Semantic Versioning guidelines to correctly increment the version number. Keep the minor version consistent with snooty-parser versioning. GitHub Actions will create a new git tag and push it to GitHub.
3. Update the release draft found here using the automatically generated CHANGELOG.md and publish the release. Keep "pre-release" checked until version 1.0.0.

⚠️ This process cannot be completed if the releaser's origin points to a fork.

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.