@honzajavorek - product decisions, feature requests, lead of development
@artem-zakharchenko - development
Hall of fame¶
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 hooks handlers:
Big thanks also to @netmilk, the original author of Dredd and Gavel!
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 test to verify everything works as expected. If you want to run Dredd during development, you can do so using
See also the full installation guide.
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> is a prefix, which tells Semantic Release what kind of changes you made in the commit:
feat- New functionality added (results in _minor_ version bump)
fix- Broken functionality fixed (results in _patch_ version bump)
refactor- Changes in code, but no changes in behavior
perf- Performance improved
style- Changes in code formatting
test- Changes in tests
docs- Changes in documentation
chore- Changes in package or repository configuration
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.
feat: add option "--require" to support custom transpilers Remove bult-in compilation of CoffeeScript. Close #1234 BREAKING CHANGE: Hookfiles using CoffeeScript are not supported out of the box anymore. Instead manually install the coffeescript module and add --require=coffeescript/register to your command.
See existing commits as a reference
Commitizen CLI can help you to create correct commit messages
npm run lintto validate format of your messages
BREAKING CHANGE:for changes in code which only remove features (there doesn’t seem to be a better category for that use case) – see real-world example
That still proved problematic for Dredd though. The current solution is to provide an npm-shrinkwrap.json file with the Dredd Transactions library, which completely excludes protagonist, i.e. the compiled C++ binding. Unlike
package-lock.json, the file can be distributed inside an npm package. The exclusion is performed by a
postshrinkwrap npm script. This didn’t work well with Dredd’s
package-lock.json, so currently Dredd’s dependency tree is not locked for local or CI installations.
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 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.
There are two release tags:
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.
npm test to run all tests. Dredd uses Mocha as a test framework. Its default options are in the
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.
We want to have a one-page changelog in the documentation as well - see #740.
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).
Due to reoccurring service denial from Coveralls, we have decided to remove any test coverage integration from Dredd. The topic of test coverage usefulness is to be discussed, and a suitable solution to be presented.
Hacking Apiary reporter¶
If you want to build something on top of the Apiary Reporter, note that it uses a public API described in Apiary Tests API for authenticated test reports
Following data are sent over the wire to Apiary:
APIARY_API_URL environment variable allows the developer to override the host of the Apiary Tests API.
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¶
Create a virtual environment and activate it:
python3 -m venv ./venv source ./venv/bin/activate
Install dependencies for the docs:
(venv)$ pip install -r docs/requirements.txt
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
Installation on ReadTheDocs¶
The final documentation gets published by ReadTheDocs. We force their latest build image in the
readthedocs.yml to get Python 3.
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:
npm i -g
npm install --global
When using Dredd’s long CLI options in tests or documentation, please always use the notation with
While both should work, the version with
=feels more like standard GNU-style long options and it makes arrays of arguments for
Do not title case headings, life’s too short to spend it figuring out title casing correctly
127.0.0.1(in code, tests, documentation) is preferred over
Images are in the
docs/_static/images directory. For images exported in sophisticated graphic formats, the source file should be committed to Git and placed in the same directory, with the same basename, just with different extension.
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:
- GitHub links checker
Fails the docs build if there’s an absolute link (
github.com/apiaryio/dredd/blob/master) to a non-existing local file
- API Blueprint spec
Simplifies linking the API Blueprint spec. Usage:
- MSON spec
Simplifies linking the MSON spec. Usage:
- OpenAPI 2 spec
Simplifies linking the OpenAPI 2 spec. Usage:
- OpenAPI 3 spec
Simplifies linking the OpenAPI 3 spec. Usage:
Simplifies linking the RFCs. Not a custom extension in fact, this is provided by Sphinx out of the box. Usage:
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 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.