Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
154 lines (95 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

154 lines (95 loc) · 6.56 KB

Contributing

We'd love for you to contribute to our source code and to make our products even better.

Getting started

To start modifying the codebase, you should clone this repository on your local machine and install all the dependencies.

git clone https://github.com/dadi/publish.git
cd publish
npm install

The application requires a configuration file, which contains information such as the port to listen on and the API to connect to.

Edit this file at dev-config/config.development.json to fit your needs, Note that you'll need an instance of API running – if you don't have one, head to https://docs.dadi.cloud/api#creating-an-api.

To start the application, run npm run watch. This will also listen for changes in the codebase and rebuild the bundle accordingly.

Test suite

The application has an end-to-end test suite. It's built using CodeceptJS, which uses Puppeteer and Chromium under the hood.

To add tests for a new feature, create a file on test/functional/features. If you're testing a new part of the application, you might want to add a new file to test/functional/pages too.

To start the test suite, run npm test.

Continuous Integration

Whenever you submit a new pull request or commit to an existing one, we fire a Travis CI that runs the test suite.

We also deploy your branch to a live URL, which can be accessed by following the Publish check on the GitHub pull request page. An instance of API will be created for this build, taken from https://github.com/dadi/publish-dev/tree/master/api.

You should use this live URL to double check that the functionality you've modified works as expected.

Git commit guidelines

One change per commit

A commit should contain exactly one logical change. A logical change includes adding a new feature, fixing a specific bug, etc. If it's not possible to describe the high level change in a few words, it is most likely too complex for a single commit. The diff itself should be as concise as reasonably possibly and it's almost always better to err on the side of too many patches than too few. As a rule of thumb, given only the commit message, another developer should be able to implement the same patch in a reasonable amount of time.

Please don't include more than one change in each patch. If your commit message requires an "and" in the middle, it's likely you need separate commits.

Commit message format

We use Semantic Release to publish new versions of our products, and as such we have very precise rules over how our git commit messages can be formatted. This leads to more readable messages that are easy to follow when looking through the project history. We also use the git commit messages to generate the change log.

The commit message format validation can be initialised by running npm run init from the root of the repository. This will add a symlink at .git/hooks/commit-msg which will be run every time you commit.

Message format

type: subject

Optional long description

BREAKING CHANGE: Optional

Fix #xxx
Close #yyy
Ref #zzz

Each commit message consists of a header, a body and a footer. The header has a special format that includes a type and a subject:

Type: must be one of the following:
  • feat: A new feature
  • fix: A bug fix
  • docs: Documentation only changes
  • style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
  • refactor: A code change that neither fixes a bug nor adds a feature
  • perf: A code change that improves performance
  • test: Adding missing tests
  • chore: Changes to the build process or auxiliary tools and libraries such as documentation generation
Subject

The subject contains a succinct description of the change:

  • use the imperative, present tense: "fix" not "fixed" nor "fixes"
  • don't capitalize first letter of type or description e.g. "fix: foo Bar"
  • no period (.) at the end
Body

Just as in the subject, write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug". This convention matches up with commit messages generated by commands like git merge and git revert.

The body should include the motivation for the change and contrast this with previous behavior.

Footer

The footer should contain any information about Breaking Changes and is also the place to reference GitHub issues that this commit might Fix or Close.

Breaking changes should start with the words BREAKING CHANGE: followed by a space or two newlines. The rest of the commit message is then used for this.

Autoclose issues and pull requests

  • Use Fix #xxx when the commit fixes an open issue.
  • Use Close #xxx when the commit closes an open pull request.

Reference another issue or pull request

  • Use Ref #xxx when referencing an issue or pull request that is already closed or should remain open. Examples include partial fixes and commits that add a test but not a fix.

Line length

Any line of the commit message cannot be longer 100 characters. This allows the message to be easier to read on GitHub as well as in various git tools.

Examples

A bug fix

Commit messages like this will generate a new patch version:

fix: package.json & .snyk to reduce vulnerabilities
A new feature

Commit messages like this will generate a new minor version:

feat: add remove method to DiskStorage
A breaking change

Commit messages like this will generate a new major version:

feat: remove existing delete() method from DiskStorage

BREAKING CHANGE: removing the delete method affects all client appliations that
use the delete method directly

Reverting

If the commit reverts a previous commit, it should begin with revert:, followed by the header of the reverted commit. In the body it should say: This reverts commit <hash>., where the hash is the SHA of the commit being reverted.