Internals

Dredd itself is a command-line Node.js application written in modern JavaScript. Contents:

Maintainers

Apiary is the main author and maintainer of Dredd’s upstream repository. Currently responsible people are:

Dredd supports many programming languages thanks to the work of several contributors. They deserve eternal praise for dedicating time to create, improve, and maintain the respective hook handlers:

Contributing

We are grateful for any contributions made by the community. Even seemingly small contributions such as fixing a typo in the documentation or reporting a bug are very appreciated!

To learn the basics of contributing to Dredd, please read the contributing documentation, placed in Dredd’s GitHub repository.

Installing Dredd for development

To hack Dredd locally, clone the repository and run npm install to install JavaScript dependencies. Then run npm test to verify everything works as expected.

If you want to run Dredd during development, you can do so using ./bin/dredd, but you need to make sure all your changes are compiled by npm run build to take effect.

Note

See also the full installation guide.

You might see some errors during installation because of the C++ dependencies, but they should not prevent you from installing and developing Dredd.

Also, when using npm with the project, you might notice it tries to compile the C++ dependencies again and again, which means every npm command takes very long until it finishes. The workaround is to append --no-optional every time to your npm command. We’re working on a better solution together with the team behind the C++ projects we depend on (drafter-npm#16).

Commit message format

Semantic Release automatically manages releasing of new Dredd versions to the npm registry. It makes sure correct version numbers get increased according to the meaning of your changes once they are added to the master branch. This requires all commit messages to be in a specific format, called Conventional Changelog:

<type>: <message>

Where <type> is a prefix, which tells Semantic Release what kind of changes you made in the commit:

  • feat - New functionality added
  • fix - Broken functionality fixed
  • perf - Performance improved
  • docs - Changes in documentation
  • chore - Changes in package or repository configuration
  • refactor - Changes in code, but no changes in behavior
  • test - Changes in tests

In the rare cases when your changes break backwards compatibility, the message must include BREAKING CHANGE:, followed by an explanation. That will result in bumping the major version.

GitHub labels

Todo

This section is not written yet. See #808.

Programming language

Dredd is written in modern JavaScript, ran by Node.js, and distributed by npm.

Before publishing to the npm registry, Babel compiles the code in the src directory and produces widely compatible ES5 JavaScript code in the lib directory. This is done because in the future we want to be able to run Dredd in the browser. With time this seems like a long shot and until we actually work on having Dredd browser-compatible, we might want to get rid of the build step.

Tests need to be pre-compiled every time, because some integration tests use code linked from lib. This is certainly a flaw and it slows down day-to-day development, but until we refactor the tests, compiling is necessary.

Previously Dredd was written in CoffeeScript, and it was only recently converted to modern JavaScript. That’s why sometimes the code does not feel very nice. Any efforts to refactor the code to something more human-friendly are greatly appreciated.

CoffeeScript is still a production dependency (not dev dependency), because it’s needed for running user-provided hooks written in CoffeeScript. This is planned to be generalized: #1082

C++ dependencies

Dredd uses Drafter for parsing API Blueprint documents. Drafter is written in C++ and needs to be compiled during installation. Because that can cause a lot of problems in some environments, there’s also pure JavaScript version of the parser, drafter.js. Drafter.js is fully equivalent, but it can have slower performance. Therefore there’s drafter-npm package, which tries to compile the C++ version of the parser and in case of failure it falls back to the JavaScript equivalent. Dredd depends on the drafter-npm package.

That’s the reason why even if you see node-gyp, gyp, or python errors during the installation process, afterwards Dredd seems to normally work and correctly parses API Blueprint documents.

The compilation can be avoided by using --no-optional with npm install. There are attempts to improve the whole experience in drafter-npm#16.

Note

See also Installing C++ dependencies in the full installation guide.

Supported Node.js versions

Given the table with LTS schedule, only versions marked as Current, Maintenance, or Active are supported, until their Maintenance End. The testing matrix of Dredd’s CI builds must contain all currently supported versions and must not contain any unsupported versions. The same applies for the underlying libraries, such as Dredd Transactions or Gavel. In appveyor.yml the latest supported Node.js version should be used. When dropping support for Node.js versions, remember to update the installation guide.

When dropping support for a certain Node.js version, it should be removed from the testing matrix, and it must be delivered as a breaking change, which increments Dredd’s major version number.

Dependencies

New versions of dependencies are monitored by David and Greenkeeper. Vulnerabilities are monitored by Snyk.

Dependencies should not be specified in a loose way - only exact versions are allowed. This is ensured by .npmrc and the lock file. Any changes to dependencies (version upgrades included) are a subject to internal policies and must be first checked and approved by the maintainers before merged to master. This is because we are trying to be good Open Source citizens and to do our best to comply with licenses of all our dependencies.

As a contributor, before adding a new dependency or upgrading an existing one, please try to make sure the project and all its transitive dependencies feature standard permissive licenses, including correct copyright holders and license texts.

Versioning

Dredd follows Semantic Versioning. The releasing process is fully automated by Semantic Release.

There are two release tags: latest and stable. Currently they both point to the latest version. The stable tag exists only for backward compatibility with how Dredd used to be distributed in the past. It might get removed in the future.

Testing

Use npm test to run all tests. Dredd uses Mocha as a test framework. Its default options are in the test/mocha.opts file.

Linting

Dredd uses eslint to test the quality of the JavaScript codebase. We are adhering to the Airbnb’s styleguide. Several rules are disabled to allow us to temporarily have dirty code after we migrated from CoffeeScript to JavaScript. The long-term intention is to remove all these exceptions.

The linter is optional for local development to make easy prototyping and working with unpolished code, but it’s enforced on the CI level. It is recommended you integrate eslint with your favorite editor so you see violations immediately during coding.

Changelog

Changelog is in form of GitHub Releases. Currently it’s automatically generated by Semantic Release.

We want to have a one-page changelog in the documentation as well - see #740.

Coverage

Tests coverage is a metric which helps developer to see which code is not tested. This is useful when introducing new code in Pull Requests or when maintaining under-tested old code (coverage shows that changes to such code are without any safety net).

We strive for as much test coverage as possible. Coveralls help us to monitor how successful we are in achieving the goal. If a Pull Request introduces drop in coverage, it won’t be accepted unless the author or reviewer provides a good reason why an exception should be made.

Note

Currently the integration is broken and while we’re sending data to Coveralls, they do not report back under Pull Requests. Multiple sessions to debug the problem were not successful and we are considering to replace the service.

The Travis CI build uses following commands to deliver coverage reports:

  • npm run test:coverage - Tests Dredd and creates the ./coverage/lcov.info file
  • npm run coveralls - Uploads the ./coverage/lcov.info file to Coveralls

The first mentioned command does following:

  1. Uses istanbul to instrument the JavaScript code
  2. Runs the tests on the instrumented code using Mocha with a special lcov reporter, which gives us information about which lines were executed in the standard lcov format
  3. Because some integration tests execute the bin/dredd script in a subprocess, we collect the coverage stats also in this file. The results are appended to a dedicated lcov file
  4. All lcov files are then merged into one using the lcov-result-merger utility and sent to Coveralls

Hand-made combined Mocha reporter is used to achieve running tests and collecting coverage at the same time.

Both Dredd code and the combined reporter decide whether to collect coverage or not according to contents of the COVERAGE_DIR environment variable, which sets the directory for temporary lcov files created during coverage collection. If the variable is set, collecting takes place.

Hacking Apiary reporter

If you want to build something on top of the Apiary Reporter, note that it uses a public API described in following documents:

Following data are sent over the wire to Apiary:

The APIARY_API_URL environment variable allows the developer to override the host of the Apiary Tests API.

Contributing to documentation

The documentation is written as code in the reStructuredText format and its source files are located in the docs directory. It is published automatically by the ReadTheDocs when the master branch is updated.

Even though alternatives exist (dredd.readthedocs.io, dredd.rtfd.io, or dredd.io), the documentation should always be linked canonically as https://dredd.org.

Building documentation locally

The documentation is built by Sphinx. To render it on your computer, you need Python 3 and Node.js.

  1. Make sure node is an executable and npm install has been done for the Dredd directory.

  2. Get Python 3. ReadTheDocs build the documentation with Python 3.6, so make sure you have this version.

  3. Create a virtual environment and activate it:

    python3 -m venv ./venv
    source ./venv/bin/activate
    
  4. Install dependencies for the docs:

    (venv)$ pip install -r docs/requirements.txt
    

    Note

    We are not using pipenv as it is not yet properly supported by ReadTheDocs.

Now you can use following commands:

  • npm run docs:lint - Checks quality of the documentation (broken internal and external links, reStructuredText markup mistakes, etc.)
  • npm run docs:build - Builds the documentation
  • npm run docs:serve - Runs live preview of the documentation on http://127.0.0.1:8000

Installation on ReadTheDocs

The final documentation gets published by ReadTheDocs. Because the documentation needs some of the npm dependencies installed and ReadTheDocs do not support this in their default build environment, we force their latest build image, which includes Node.js out of the box, in the readthedocs.yml. In the Sphinx’ configuration file, docs/conf.py, we make sure npm install is executed on ReadTheDocs.

Writing documentation

  • Read the reStructuredText primer

  • No explicit newlines, please - write each paragraph as a single long line and turn on word wrap in your editor

  • Explicit is better than implicit:

    • Bad: npm i -g
    • Good: npm install --global
  • When using Dredd’s long CLI options in tests or documentation, please always use the notation with = wherever possible:

    • Bad: --path /dev/null
    • Good: --path=/dev/null

    While both should work, the version with = feels more like standard GNU-style long options and it makes arrays of arguments for spawn more readable.

  • Do not title case headings, life’s too short to spend it figuring out title casing correctly

  • Using 127.0.0.1 (in code, tests, documentation) is preferred over localhost (see #586)

  • Be consistent

Sphinx extensions

There are several extensions to Sphinx, which add custom directives and roles to the reStructuredText syntax:

CLI options
Allows to automatically generate documentation of Dredd’s CLI options from the JSON file which specifies them. Usage: .. cli-options:: ./path/to/file.json
GitHub issues
Simplifies linking GitHub issues. Usage: :ghissue:`drafter#123`
API Blueprint spec
Simplifies linking the API Blueprint spec. Usage: :apib:`schema-section`
MSON spec
Simplifies linking the MSON spec. Usage: :mson:`353-type-attribute`
OpenAPI 2 spec
Simplifies linking the OpenAPI 2 spec. Usage: :openapi2:`parameterobject`
OpenAPI 3 spec
Simplifies linking the OpenAPI 3 spec. Usage: :openapi3:`parameterobject`
RFCs
Simplifies linking the RFCs. Not a custom extension in fact, this is provided by Sphinx out of the box. Usage: :rfc:`1855`

The extensions are written in Python 3 and are heavily based on the knowledge shared in the FOSDEM 2018 talk by Stephen Finucane. Extensions use Python’s unittest for tests. You can use npm run docs:test-extensions to run them.

Redirects

Redirects are documented in the docs/redirects.yml file. They need to be manually set in the ReadTheDocs administration. It’s up to Dredd maintainers to keep the list in sync with reality.

You can use the rtd-redirects tool to programmatically upload the redirects from docs/redirects.yml to the ReadTheDocs admin interface.

Windows support

Dredd is tested on the AppVeyor, a Windows-based CI. There are still several known issues when using Dredd on Windows, but the long-term intention is to support it without any compromises.

API description parsing

Todo

This section is not written yet. See #820.

Architecture

Todo

This section is not written yet. See #820.