Skip to content

Contributing

If you have an idea you'd like to contribute please log an issue.

If you'd like to suggest a change or addition, create a branch, add your changes to it, then submit a pull request.

Feedback will be done in Github either against the issue or pull request. When enough time has been allowed for feedback, and you and the Standards Group are happy the change will be merged! 🎉

If you have any questions or need to discuss or check anything contact us via the #development-standards channel in Slack.

What not to include

This repository is concerned with standards and guidance so please keep ideas and contributions to those areas. You should also avoid

  • repeating content available elsewhere. Link to it instead
  • be careful with anything related to how a service's environment is setup
  • be careful about discussing any internal Defra processes
  • adding in any personal information

If in doubt speak to Alan Cruikshanks or Ben Sagar before creating the PR.

Getting started

Read the style guide for standards.

Create a branch with a brief but descriptive name e.g. add-more-details-for-contributors.

Start committing your changes and push straight away rather than when finished. We don't want your work to get lost!

When you are ready for feedback create the pull request. Take the time to give it a meaningful title and detailed description as this will help those reviewing it understand what you've done.

Pro tip! If you create the PR straight after your first commit, GitHub will automatically populate the title and description for the new PR from the commit message.

Also assign yourself to the PR so folks know who created it and consider adding a label to the PR. These can help potential reviewers quickly see the nature of the it.

When you are ready request a review from DEFRA/sds-group.

Finally announce your PR in our slack channel in Slack to make sure no one can say they didn't know about it 😀.

Getting feedback

Feedback will be provided within the PR. Decisions will be documented and reasons given.

We want to encourage all to contribute and suggest ways we can improve. Anyone providing feedback should be positive and professional with any comments made about your contribution, but let us know if you feel we failed.

Approval

Those that review your contribution when happy with it will leave a comment indicating so e.g. 👍, 🚢, LGTM.

It will formally be approved however by the Head of Standards, or in their absence one of the Principal Developers. This will be done via the GitHub UI.

Finishing up

When your contribution has been approved, you can go ahead and merge it using the GitHub UI for the pull request.

IMPORTANT If you have multiple commits on your branch it will squash them, and ask you to confirm what the final single commit message should be. Rewrite the message so it reflects the final change you've made (feedback may have changed your original intent) and why.

With that done sit back, have a 🍹, and ponder your next contribution!

GitHub pages

This documentation is published to GitHub pages using MkDocs and the Material for MkDocs theme.

To view changes locally you will need the following pre-requisites:

Once installed you can run mkdocs serve to start a live-reloading server to view your changes.

Once your changes are merged, the CI pipeline will automatically deploy the changes to GitHub pages.