Application: service-manual-frontend

Serves the Service Manual and Service Toolkit on GOV.UK

Ownership

#govuk-platform-health owns the application and is responsible for updating its dependencies.

Hosting

The production version of this application is hosted on AWS.

SSH Access (AWS)

gds govuk connect ssh -e integration draft_frontend
gds govuk connect ssh -e staging aws/draft_frontend
gds govuk connect ssh -e production aws/draft_frontend

Run a rake task

• Run a Rake task on Integration
• Run a Rake task on Staging
• ⚠️ Run a Rake task on Production ⚠️

Links

• GitHub repo
• Sentry (error tracking)
• Puppet configuration
• Deploy scripts
• Deployment dashboard
• Publishing E2E scenarios (warning: not all apps have E2E tests)

Example pages rendered by service-manual-frontend

• Service Standard
• Service Manual
• Agile delivery
• Understanding WCAG 2.1
• Making your service accessible: an introduction
• How the discovery phase works
• How the alpha phase works
• User research
• How the beta phase works
• 1. Understand users and their needs

README

Warning The content below is pulled in directly from the repository.
Links might not function properly.

Service Manual Frontend is a public-facing app to display the service manual formats on GOV.UK.

Technical documentation

This is a Ruby on Rails application that fetches documents from
content-store and displays them.

Dependencies

• content-store - provides documents
• static - provides shared GOV.UK assets and templates.

Development notes

The application does not serve content at its root (/) - the
homepage will be found at service-manual-frontend.dev.gov.uk/service-manual but
only if the content item for the homepage exists in the content store.

You can achieve this by restoring from a production backup, publishing the home
page using the rake task in service-manual-publisher or by using the dummy
content store.

Running the test suite

The test suite relies on the presence of the
govuk-content-schemas
repository. If it is present at the same directory level as
the service-manual-frontend repository then run the tests with:

bundle exec rake

Or to specify the location explicitly:

GOVUK_CONTENT_SCHEMAS_PATH=/some/dir/govuk-content-schemas bundle exec rake

Visual regression tests

Use Wraith (“A responsive screenshot
comparison tool”) to generate a visual diff to compare rendering changes in this
application.

Wraith does not work correctly from within the VM because
assets-origin.dev.gov.uk is not resolvable within the VM, and so none of the
assets load. You should instead install wraith on your local machine and run
it from there.

Wraith has some dependencies you’ll also
need to install.

First, on master branch, run:

wraith history test/wraith/config.yaml

Then, on a branch with your changes, run:

wraith latest test/wraith/config.yaml

This will generate image diffs comparing the two runs, including a browseable
gallery of the output, in tmp/wraith.

Use of BEM

The Service manual frontend application uses a modified version of the BEM methodology,
coined by Harry Roberts.

It uses the following conventions:

• block, element and modifier names are written in lower case
• words within the names of BEM entities are separated by a hyphen (-)
• an element name is separated from a block name by a double underscore (__)
• modifiers are delimited by double hyphens (–)
• Key-value type modifiers are not used

A block:

.button

An element:

.button__icon

A modifier:

.button--large

Licence

MIT License