CCS Frontend Helpers

The CCS Frontend Helpers gem was created for use in the Crown Marketplace projects at the Crown Commercial Service. This project contains two applications (both use the Ruby on Rails framework):

• Crown Marketplace
• Crown Marketplace Legacy

Compatibility

The following table shows the version of CCS Frontend Helpers that you should use for your targeted version of GOV.UK Frontend:

CCS Frontend Helpers Version	Target GOV.UK Frontend Version	Target CCS Frontend Version
1.2.0	5.6.0	1.1.3
1.1.2	5.5.0	1.1.2
1.1.1	5.4.1	1.1.1
1.1.0	5.4.0	1.1.0
1.0.0	5.4.0	1.0.0
0.4.0	5.4.0	N/A
0.3.0	5.3.0	N/A
0.2.0	5.2.0	N/A
0.1.2	4.7.0	N/A

Any other versions of GOV.UK Frontend not shown above may still be compatible, but have not been specifically tested and verified.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add ccs-frontend_helpers

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install ccs-frontend_helpers

Usage

To use this gem, simply add it to your Gemfile (as described above).

Helpers

To include the helper methods from the GovUKFrontend and CCSFrontend module, you can include the CCS::FrontendHelpers module in your app/helpers/application_helper.rb file like so:

module ApplicationHelper
  include CCS::FrontendHelpers
end 

This will give you access to a variety of GDS components and CCS components to use in your application views. The GovUKFrontend components are based on the components found in GOV.UK Frontend v4.5.0.

Documentation for the helper methods can be found at LINK TO RDOCS

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Linting

The rubocop & rubocop-rspec gems are used to enforce standard coding styles. Some "cops" in the standard configuration have been disabled or adjusted in .rubocop.yml. Rubocop linting is run as part of the default Rake task, but can be run individually using rake rubocop.

Testing

Unit testing

There is an automated RSpec-based test suite.

You can run all the unit tests with:

bundle exec rake

To run a specific unit test, use:

bundle exec rspec /path/to/file_spec.rb

All the specs are run as part of the Pull Request process.

Code coverage

Code coverage is measured by simplecov

After running the Rspec tests, open coverage/index.html in a browser to see the code coverage percentage.

Managing dependencies

We use dependabot and Snyk to help manage our dependencies.

We schedule dependabot to run every Sunday night which will get the latest dependency updates.

Snyk is used more for analysing security issues and it will raise PRs itself for a developer to analyse.

Releasing

1. Check out the main branch and pull the latest changes.

2. Update the version number in version.rb (we follow Semantic Versioning).

3. Run bundle install to update the Gemfile.lock

4. Create and check out a new branch (release-[version])

 git switch -c "release-$(./bin/version)"

5. Update the CHANGELOG.md by:

   • changing the 'Unreleased' heading to the new version number and release type. For example, '3.11.0 (Feature release)'
   • adding a new 'Unreleased' heading above the new version number and release type, so users will know where to add PRs to the changelog
   • if the changelog has headings from a pre release, regroup the content under those headings in a single block
   • saving your changes

6. Run ./bin/build-release.sh to:

   • commit the changes
   • push a branch to GitHub

   You will now be prompted to continue or cancel. Check the details and enter y to continue. If something does not look right, press N to cancel the build and creation of the branch on GitHub.

7. Create a pull request and copy the changelog text. When reviewing the PR, check that the version numbers have been updated and that the compiled assets use this version number.

8. Once a reviewer approves the pull request, merge it to main. The gem will then automatically be published to rubygems.org via a GitHub action.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/Crown-Commercial-Service/ccs-frontend_helpers.

To contribute to the project, you should checkout a new branch from main and make your changes.

Before pushing to the remote, you should squash your commits into a single commit. This can be done using git rebase -i main and changing pick to s for the commits you want to squash (usually all but the first). This is not required but it helps keep the commit history fairly neat and tidy

Once you have pushed your changes, you should open a Pull Request on the main branch. This will run:

• Rubocop
• Unit tests

Once all these have passed, and the PR has been reviewed and approved by another developer, you can merge the PR.

Licence

The gem is available as open source under the terms of the MIT Licence.