Hello! Thank you for taking the time to contribute to the HMRC Multichannel Digital Tax Platform (MDTP)
We welcome contributions to assets-frontend. By following these guidelines, you will greatly reduce the amount of feedback (and therefore time) between opening your Pull Request and us merging it.
We’re always looking for feedback, and help is always welcome. These are the areas where you can help:
- Bug fixes and improvements
- Proposing new features
- More tests and better coverage
- Documentation
Before starting on a piece of work, please get in touch.
We may already have what you’re planning to do in our backlog, or already be working on it.
Communicating early can also help with design decisions and direction for your approach, increasing the chance of us accepting your work.
- Raise an issue
- Slack channel for getting in touch with frontend developers (requires an HMRC slack account)
Please follow these contribution guidelines to maintain the quality of the code:
Before a Pull Request
- Follow style guides
- Write tests
- Write documentation
- Write good commit messages
- Squash related commits before a PR merge
- Don't bump the
package.jsonversion
Opening a Pull Request
“All code in any code-base should look like a single person typed it, no matter how many people contributed.” – Rick Waldron
The project uses EditorConfig to ensure consistent coding styles between different editors and IDEs. Please install a plugin for your editor of choice or manually enforce the rules listed in .editorconfig.
The project follows JavaScript Standard Style.
When running locally, all code is linted automatically every time a file is saved. Just run:
npm start
To lint the code as a standalone task, run:
npm run lint
Once you’ve made your changes, run the JavaScript tests to make sure they pass:
Details on running the JavaScript tests
If there aren’t any existing tests that cover your changes, write some new tests.
Make sure that your work hasn’t changed anything visually without you knowing, run the visual regression tests:
To run visual regression tests you will need to install backstopjs:
npm install -g backstopjs
You can then run the tests with:
backstop test
If there are known changes, these can be approved with:
backstop approve
The existing reference images were run using backstopjs on a Mac running Mac OS Catalina.
See more information on backstop at https://www.github.com/garris/backstopjs
“Your service must be universally accessible. This means building it to work on every browser or device that your users access it on.”
[Details on GOV.UK Browser support] (https://www.gov.uk/service-manual/technology/designing-for-different-browsers-and-devices)
The project’s files are documented using kss-node.
The live documentation lives on GitHub pages
Details on generating and viewing the documentation
If you’ve added a new component, then document it following our documentation guidelines
The project follows the guidelines laid out in keepachangelog.com
Writing good commit messages is important. Not just for other developers on your project, for also for your future self.
There has already been a lot written about git commit messages, so we follow the same standards as GOV.UK
Recommended reading on this topic
...changes are proposed in a branch, which ensures that the
mainbranch only contains finished and approved work. – GitHub
Pull requests that do one thing have much more chance of being reviewed and merged quickly. Huge changes that take a long time to work through will have less chance of being reviewed or merged.
Recommended reading on this topic
When filling out the description for your Pull Request, follow the template.
Search for all issues relating to your work that may have been raised prior to your pull request and link to them so we can keep our issue backlog tidy.
If your pull request closes an issue then follow this guide on GitHub
Our internal build and release tooling is responsible for bumping the versions of the project.
Once the pull request has been merged, it is the joint responsibility of the Contributor and the Owning Team to:
- Discuss the optimal timing of pre-production and production releases
- Validate the functional and operational impact once the release reaches pre-production and production
It's the responsibility of the Owning Team alone to deploy/schedule the release into the relevant pre-production and production environment(s).
Work should be added in a modular fashion and code that only serves the purpose of a single service should be avoided. Be generic and compliment the shared library.
All work on GOV.UK should be built in a progressive fashion.
Recommended reading on this topic
Services on GOV.UK are for the benefit of all UK citizens. This means you must build a service that’s as inclusive as possible.