Skip to content

Latest commit

 

History

History
159 lines (106 loc) · 4.38 KB

CONTRIBUTING.adoc

File metadata and controls

159 lines (106 loc) · 4.38 KB
Raw

Contributing

Prerequisites

To build this project and run the tests, you need the following software installed on your computer:

  • git (command: git)

  • Node.js (commands: node, npm, and npx)

git

First, make sure you have git installed.

$ git --version

If not, download and install the git package for your system.

Node.js

Next, make sure that you have Node.js installed (which also provides npm and npx).

$ node --version

If this command fails with an error, you don’t have Node.js installed. If the command doesn’t report an active LTS version of Node.js, it means you don’t have a suitable version of Node.js installed.

We strongly recommend that you use nvm (Node Version Manager) to manage your Node.js installation(s). Follow the nvm installation instructions to set up nvm on your machine.

Once you’ve installed nvm, open a new terminal and install Node.js 20 using the following command:

$ nvm install

You can switch to this version of Node.js at any time using the following command:

$ nvm use

Now that you have git and Node.js installed, you’re ready to start developing on this project.

Clone Project

Clone the project using git:

$ git clone https://github.com/spring-io/antora-xref-extension && cd "`basename $_`"

The previous chained command clones the project then switches to the project folder on your filesystem. Stay in this project folder when running all subsequent commands.

Install Dependencies

Use npm to install the project’s dependencies inside the project. In your terminal, run the following command:

$ npm ci

This command installs the dependencies listed in package-lock.json into the node_modules/ folder inside the project. This folder should not be committed to the source control repository.

Run Tests

This project uses mocha to run the tests and the assertion library chai to assert outcomes. To run the test suite, use:

$ npm test

By default, npm test will run all tests. You can run the tests in a single test suite by passing the path of that test suite as the final argument:

$ npm test test/partial-build-extension-test.js

You can also run a single test by adding .only to the it function (e.g., it.only). If it.only is present, npm test will only run that test.

To generate a coverage report when running the tests (enabled by default in CI), run the coverage script instead:

$ npm run coverage

A coverage report shows the lines, statements, and branches that the tests exercise. You can view the coverage report by opening the HTML file reports/lcov-report/index.html in your browser.

Verify Code Style

This project adheres to the JavaScript Standard style with some exceptions defined in .eslintrc. The code style is verified using ESLint.

To verify that the style of the code is correct, run the following command:

$ npm run lint

To format the code to adhere to the code style, run the following command:

$ npm run format

The CI workflow will fail if there are pending code style changes, so be sure to run it before you push a change.

Use Project From Source

If you want to use the project locally before it is published, you can specify the path to the project as the version in package.json.

"dependencies": {
  "@springio/antora-extensions": "/path/to/project"
}

When you run npm i in that project, npm will set up a symlink to the location of this project. Any changes to this project will take effect immediately.