Skip to content

Latest commit

 

History

History
74 lines (42 loc) · 3.63 KB

CONTRIBUTING.md

File metadata and controls

74 lines (42 loc) · 3.63 KB

Contributing

This guidance is intended for changes to:

  • versions of dependencies for this repo (e.g. RuboCop itself); and
  • the extra config we have to support historical GOV.UK patterns.

All dependencies should be locked to patch versions to avoid surprise upgrades in consumer repos.

Getting started

To install dependencies:

bundle

To lint the config / Rakefile:

bundle exec rake

RuboCop GOV.UK is a styleguide, so each rule in each YAML file should have a comment to explain why it's there. This is enforced by linting with a custom explain_yourself rake task.

Doing a release

1. Check what the impact is going to be

Find out how much effort it will be to adopt your changes in typical GOV.UK repos. This could just be running rubocop -A to autocorrect new issues, or it could involve significant manual effort.

You can test changes against an alphagov repo by running the GitHub worflow we have configured.

This is a rough list of typical GOV.UK repos we recommend testing against:

  • An old app e.g. Whitehall, Smart Answers
  • A newer app e.g. Content Publisher, Email Alert API
  • A non-Rails app e.g. Search API
  • A gem e.g. GDS API Adapters

2. Decide if the config needs to change

Ideally we should have none of our own config and follow RuboCop defaults:

  • This is easier than making our own decisions.
  • We don't want to diverge from the Ruby community.

However, we also want to make it easy for all GOV.UK repos to keep pace with RuboCop GOV.UK. This means we should try to ensure all issues can be auto-corrected or are easy to fix manually.

You should only change the config as a last resort. Examples of good changes:

  • Disable a rule if it's based on heuristics (example).

  • Change a rule to match a GOV.UK-wide pattern (example).

  • Change a rule if the effort to fix is very high (example).

Sometimes it's more appropriate to put config overrides in the .rubocop.yml file of consumer repos (example). Use this approach if the override is only necessary in a small number of repos.

3. Consider making a pre-release version

This can be helpful if there are lots of changes where it's hard to assess the impact e.g. a major dependency upgrade. Use the pre-release version to gather feedback from maintainers of consumer repos, working with them to make any necessary adjustments here before releasing the next official version.

👉 Example of major release after testing a pre-release version.

4. Make your CHANGELOG really helpful

The CHANGELOG.md is what maintainers of consumer repos will use to understand your changes. Tools like Dependabot will automatically include it in PR descriptions. A helpful changelog:

  • Gives an overview of the change e.g. "Upgrade X to Y".

  • Explains any actions to take e.g. "run rubocop -A".

  • Advises on potential compatibility issues (TODO: example).