alphagov/govuk-developer-docs

📖 Tech docs for everyone working on GOV.UK

GOV.UK Developer Docs

👉 https://docs.publishing.service.gov.uk/

This is a static site generated with Middleman, using alphagov/tech-docs-template.

Some of the files (like the CSS, javascripts and layouts) are managed in the template and are not supposed to be modified here. Any project-specific Ruby code needs to go into /app.

Build the app locally

bundle install

Run the tests locally

bundle exec rake

Run the app locally

SKIP_PROXY_PAGES=true ./startup.sh

Proxy pages

The live docs site includes pages from other alphagov GitHub repositories. To test this locally, omit SKIP_PROXY_PAGES=true from the command above.

The app downloads these "proxy pages" at startup and this can cause GitHub to rate limit your requests. You can pass a valid GitHub API token to the app to help avoid this:

1. Create a GitHub token. The token doesn't need any scopes.

2. Store the token in a .env file:

   GITHUB_TOKEN=somethingsomething

3. Start the application:

   ./startup.sh

Update to the latest Tech Docs template

bin/update

Deployment

We host GOV.UK Developer Docs as a static site on GitHub Pages. The ci.yml GitHub Actions workflow updates the site automatically:

• when a PR is merged to the default branch
• on an hourly schedule, to pick up changes to docs included from other repos

Build the static site locally

NO_CONTRACTS=true bundle exec middleman build

This will create a build directory containing a set of HTML files.

Licence

MIT License

govuk-developer-docs's Issues

Re: 'Deploy Puppet'

When trying to run the ./bin/puppet_versions.sh script on staging, I get this error:

Traceback (most recent call last):
  File "bin/show_puppet_versions.py", line 6, in <module>
    import requests_cache
ImportError: No module named requests_cache

Problem with 'Deploy Puppet' (https://docs.publishing.service.gov.uk/manual/deploy-puppet.html)

Re: 'Deploy Puppet'

Problem with 'Deploy Puppet' (https://docs.publishing.service.gov.uk/manual/deploy-puppet.html)

The link near the top "integration-puppet-deploy job on Jenkins CI" 404s. I would fix it myself, but can't figure out where it should point.

SSH command generation ambiguous

See https://docs.publishing.service.gov.uk/apps/email-alert-frontend.html#ssh-access-aws

Recommended SSH command is this:

ssh -A -t jumpbox.integration.publishing.service.gov.uk 'ssh `govuk_node_list -c draft_frontend --single-node`'

Generated from this logic: https://github.com/alphagov/govuk-developer-docs/blob/master/app/app_docs.rb#L56-L63

The problem

email-alert-frontend exists in multiple puppet classes: frontend and draft_frontend. The command only suggests connecting to draft_frontend as this is the first one alphabetically. It would be good to perhaps list all the possible SSH options (i.e. both in this case), rather than pick one arbitrarily.

See:

  draft_frontend:
    apps:
      - email-alert-frontend
  frontend:
    apps:
      - email-alert-frontend

The proposed solution would therefore be to render this instead:

# choose one of the two below
ssh -A -t jumpbox.integration.publishing.service.gov.uk 'ssh `govuk_node_list -c draft_frontend --single-node`'
ssh -A -t jumpbox.integration.publishing.service.gov.uk 'ssh `govuk_node_list -c frontend --single-node`'

"GOV.UK developer docs" is inconsistent naming and slightly exclusionary of non-developers

We currently have our docs named GOV.UK developer docs while most other parts of GDS have their documentation named <blah> Technical Documentation (even the middleman wrapping gem is called tech-docs-gem).

We also groups of other technical folk across GOV.UK who could be contributing documentation. To make it a friendlier and more inclusive documentation site we should rename it to be more encompassing.

We must also be clearer on who the audience is. It's publicly available, but for internal consumption. The contributors and consumers are those who write code and add to the systems that are run by GOV.UK (mostly developers at the moment).

Unable to update without causing YAML problems

To update a dependency to latest version, we should run ./bin/update, but this updates all dependencies to their latest versions. And one of these updates causes the YAML parsing to fail:

YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/fall-back-to-mirror.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/ram-vm.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/fix-signature-expired-errors.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/frontend-architecture.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/receiving-emails-from-email-alert-api-in-integration-and-staging.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/github-trello-poster.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/resync-mongo-db.html.md: Tried to load unspecified class: Date
YAML Exception parsing /Users/christopherashton/govuk/govuk-developer-docs/source/manual/development-pipeline.html.md: Tried to load unspecified class: Date

This isn't a silent failure; it means a lot of content is lost from the Manual page:

We should fix up our usage of YAML parsing so that we can continue to update problem-free.

Re: 'Architecture overview of GOV.UK applications'

Problem with 'Architecture overview of GOV.UK applications' not showing the architecture (https://docs.publishing.service.gov.uk/manual/architecture.html)

Problem with 'Content Store' - missing content

Problem with 'Content Store' (https://docs.publishing.service.gov.uk/apis/content-store.html)

Some content does not work on the API:

alphagov/content-store#325

However the documentation says that it will:

The Content Store is the store for all published content on GOV.UK. When given a path, it responds with the content that should be displayed on that path.

I suggest

• explaining what is missing, and
• explain how to check if the API is returning what you asked for, or it's returning another item

Re: 'Whitehall'

Problem with 'Whitehall' (https://docs.publishing.service.gov.uk/apis/whitehall.html)

Add your application to this list href is 404'ing
https://github.com/alphagov/whitehall/edit/master/docs/api.html

Page "Merge a Pull Request" Has Review Date in the Future

The "Merge a Pull Request" page states that it was last reviewed in August 2019. At the time of raising this issue, it's July 2019.

It would appear, from the history for this file, that it was updated in March 2019 as part of commit 8eb20b2, on March 29th 2019. During this commit the following front-matter update was made:

last_reviewed_on: 2019-02-15

was changed to

last_reviewed_on: 2019-08-28

I suspect the 08 should have been a 03.

Page: https://docs.publishing.service.gov.uk/manual/merge-pr.html

Source: https://github.com/alphagov/govuk-developer-docs/blob/master/source/manual/merge-pr.html.md

Issue originally spotted by @petevb

Problem with 'Set up a new Rails app'

Problem with 'Set up a new Rails app' (https://docs.publishing.service.gov.uk/manual/setting-up-new-rails-app.html)

Some links still point to Github Enterprise

Using comments in codeblocks makes tests fail

It appears as if the presence of a comment in a codeblock, where that comment is a # character, fails the following test. This probably isn't easily fixable, but perhaps it would be possible to suggest it as a source of errors when this fails?

      it "doesn't use H1 tags (the page title is already an H1)" do
        expect(raw).not_to match(/\n#\s/)
      end

Broken SSH command on several applications

See https://docs.publishing.service.gov.uk/apps/smart-answers.html

ssh -A -t jumpbox.integration.publishing.service.gov.uk 'ssh govuk_node_list -c Unknown - have you configured and merged your app in govuk-puppet/hieradata_aws/common.yaml --single-node'

^ This doesn't look right!

See also https://docs.publishing.service.gov.uk/apps/transition.html#ssh-access-aws

smartanswers has node classes on calculators_frontend and draft_frontend, so something should appear in this command. I have a hunch the problem is down to hieradata_aws/common.yaml naming smartanswers rather than smart-answers in places...?

Either way, we should probably avoid rendering broken SSH commands in cases like these, before fixing the smartanswers problem specifically.

Find & fix root cause of 'html-pipeline' issue

First spotted by Tim Blair in April (e9541eb), html-pipeline 2.11.0 causes issues with ASCII/UTF-8 processing:

Error processing resource for index: apis/search/faceted-search.html
"\xE2" from ASCII-8BIT to UTF-8
 govuk-developer-docs/.bundle/gems/commonmarker-0.19.0/lib/commonmarker.rb:26:in `encode'

We pinned html-pipeline to 2.5.0 in 6f81229, but should investigate the root cause and fix it.

Re: 'Deploy Puppet'

It'd be good to specify what permissions you need to set on the Github token.

Problem with 'Deploy Puppet' (https://docs.publishing.service.gov.uk/manual/deploy-puppet.html)

Problem with tunnelling instructions

I've noticed that other developers are not able to use the ssh commands in some of the manual pages, eg the integration command here https://docs.publishing.service.gov.uk/manual/rabbitmq.html#header

This is because ssh integration doesn't work for them.

In my ssh config I have an integration host defined as

Host integration
  Hostname jumpbox.integration.publishing.service.gov.uk

But this is not in the example config here:

https://github.com/alphagov/govuk-puppet/blob/master/development-vm/ssh_config

We could fix this by changing the example and/or changing the docs. I'm just creating the issue to keep track of this as I don't have time to fix right now. Does anyone have any opinions on how this should work?

Markdown: soft line breaks not being rendered correctly

http://spec.commonmark.org/0.27/#soft-line-breaks

I used ExternalDoc.fetch to embed some markdown from GitHub. This markdown contained newlines within paragraphs. These newlines were rendered as <br> tags. The spec says they should have been rendered as newlines in the HTML or space characters. This breaks formatting.

I don't know if this issue is specific to ExternalDoc.fetch or whether it's for markdown within this project, too.

Problem with ''uptime metrics" link - not responding due to time out

Problem with '' (https://docs.publishing.service.gov.uk/apps/publishing-api.html) - the "Uptime Metrics" link, https://grafana.publishing.service.gov.uk/dashboard/file/application_uptime.json is not loading. ERR_CONNECTION_TIMED_OUT

Update 'Use the side-by-side browser'

@boffbowsh I think most of 'Use the side-by-side browser' (https://docs.publishing.service.gov.uk/manual/side-by-side-browser.html) is out of date now. We could update it but we might not actually need the page.

History links to removed paths

In https://docs.publishing.service.gov.uk/manual/retiring-an-application.html it refers to https://github.gds/gds/opsmanual/tree/master/infrastructure/howto/retiring-an-application.md

We should link to a commit-ish slug rather than HEAD

Problem with 'Raising issues with Reliability Engineering'

Problem with 'Raising issues with Reliability Engineering' (https://docs.publishing.service.gov.uk/manual/raising-issues-with-reliability-engineering.html)

"Who do I ask for support?" link is broken.

Problem with 'ntp drift too high'

Problem with 'ntp drift too high' (https://docs.publishing.service.gov.uk/manual/alerts/ntp-drift-too-high.html)

This is normally a red herring. If the error is "Socket timeout", re-schedule the check and it'll normally go away.

Skyscape status url

In this document https://github.com/alphagov/govuk-developer-docs/blob/master/source/manual/alerts/pingdom-homepage-check.html.md

The Skyscape status url seems to not be accessible.

Problem with 'Backup passive checks'

Problem with 'Backup passive checks' (https://docs.publishing.service.gov.uk/manual/alerts/backup-passive-checks.html)

This only covers the false alarm case, but not the case when the backup actually hasn't run at all and needs re-running.

Problem with 'Remove an asset'

Problem with 'Remove an asset' (https://docs.publishing.service.gov.uk/manual/howto-manually-remove-assets.html)

govuk -> govuk-publishing

Should we be specific?

`govuk-abtest` Headers Appearing in requests to our API

We had a user from the UK write in that they were receiving an error on a specific route to our service because they appeared unauthenticated for this specific request. The were able to interact with the site and send successful requests to other route before and after this failing request.

When we looked in to it, we saw that their browser appeared to be sending our cookie but our service was not receiving the cookie and was instead receiving a request with headers that look like govuk-abtest-* cookie values.

This is pretty inexplicable to us, especially given that we use CloudFront as a CDN and not Fastly. Do you have any idea what's going on here?

Here's the request :

{ 'x-real-ip': '<redacted>',
  'x-forwarded-for': '<redacted>',
  'x-forwarded-proto': 'https',
  host: 'www.figma.com',
  'x-nginx-proxy': 'true',
  'content-length': '2819252',
  origin: 'https://www.figma.com',
  'user-agent':
   'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/72.0.3626.109 Safari/537.36',
  'x-csrf-bypass': 'true',
  'content-type': 'image/png',
  accept: '*/*',
  'govuk-abtest-contentpagesnav': 'B',
  'govuk-abtest-tasklistsidebar': 'B',
  'govuk-abtest-tasklistheader': 'B',
  'govuk-abtest-guidechapternav': 'B',
  'govuk-abtest-contextualcomms': 'BlueBoxCampaign',
  'govuk-abtest-topicpagestest': 'A',
  referer: '<redacted>',
  'accept-encoding': 'gzip, deflate, br',
  'accept-language': 'en-GB,en-US;q=0.9,en;q=0.8' }

Problem with 'Sidekiq'

Problem with 'Sidekiq' (https://docs.publishing.service.gov.uk/manual/sidekiq-retries.html)

Sidekiq monitor link at bottom of page is broken

Problem with 'Get started on GOV.UK'

Problem with 'Get started on GOV.UK' (https://docs.publishing.service.gov.uk/manual/get-started.html)

Section 8: Run your apps
This seems to be out of date. I can't run "bowl x" but have to run "bundle exec bowl x" to get any output. What then happens is the app runs and quits with a message that seems to suggest bundle exec wasn't previously run, even when it was:
/usr/lib/rbenv/versions/1.9.3-p550/lib/ruby/gems/1.9.1/gems/bundler-1.7.4/lib/bundler/source/git.rb:188:in rescue in load_spec_files': git://github.com/alphagov/airbrake.git (at silence-dep-warnings-for-rails-5) is not yet checked out. Run bundle install` first. (Bundler::GitError)

I've been pointed at an alternate way of running the apps which is to go into their directory and run the startup file from in there - does the documentation need to switch to instructing users to do this instead?

Add documentation for updating browser support

Recently there's been some questions about which browsers we support:

• How do we determine what to support
• Where do we document what is supported
• How do we update support for a browser
• How often do we check

It'd be good to document the answers to these questions in this repo.

This should sit alongside the service manual page:
https://www.gov.uk/service-manual/technology/designing-for-different-browsers-and-devices

Note in the above:

your plan for ensuring this is continually reviewed

This will become more relevant with any TLS changes.

cc @NickColley @timblair

Markdown list rendering incorrect

Markdown doc on github

vs

Is it possible to make bluebadge renewal via API?

Hello! i was trying to find how i can make blu badge renewal via this API, unfortunately i cant find any endpoint for this task. Is it possible? thanks

Re: 'Get started on GOV.UK' - 404 for user monitoring system

Problem with 'Get started on GOV.UK' (https://docs.publishing.service.gov.uk/manual/get-started.html)

• In section two 'Set up your GitHub account', step 2 has a link to to 'user monitoring system' (
  https://github.com/alphagov/govuk-user-reviewer) that 404s.

Intermittent test failures for GitHubRepoFetcher

This issue was discovered in #2935 and was presumably introduced by #2918.

It looks the tests are sensitive to their order of execution and that state from a previous run of tests can remain on the GitHubRepoFetcher singleton object.

To replicate you can run bundle exec rspec --seed 1 -f d spec/app/github_repo_fetcher_spec.rb

➜  govuk-developer-docs git:(master) bundle exec rspec --seed 1 -f d spec/app/github_repo_fetcher_spec.rb

Randomized with seed 1

GitHubRepoFetcher
  #repo
    fetches a repo from cache if it exists (FAILED - 1)
    raises error if no repo is found (FAILED - 2)
    fetches a repo from GitHub if it doesn't exist in the cache (FAILED - 3)
  #readme
    retrieves the README content from the GitHub CDN (FAILED - 4)
    returns nil if no README exists (FAILED - 5)
I, [2021-01-27T10:03:26.414160 #93187]  INFO -- request: GET https://raw.githubusercontent.com/alphagov/some-repo/master/README.md
I, [2021-01-27T10:03:26.414231 #93187]  INFO -- request: User-Agent: "Faraday v1.2.0"
I, [2021-01-27T10:03:26.430047 #93187]  INFO -- response: Status 200
I, [2021-01-27T10:03:26.430105 #93187]  INFO -- response:
    caches the first response
    returns nil if the repo is private
I, [2021-01-27T10:03:26.434079 #93187]  INFO -- request: GET https://raw.githubusercontent.com/alphagov/some-repo/latest/README.md
I, [2021-01-27T10:03:26.434120 #93187]  INFO -- request: User-Agent: "Faraday v1.2.0"
I, [2021-01-27T10:03:26.449511 #93187]  INFO -- response: Status 200
I, [2021-01-27T10:03:26.449553 #93187]  INFO -- response:
    retrieves the README content from the repo's default branch
  #docs
I, [2021-01-27T10:03:26.462233 #93187]  INFO -- request: GET https://api.github.com/repos/alphagov/a033a536-1769-487b-b9cb-48ad975d0b7c/contents/docs
I, [2021-01-27T10:03:26.462321 #93187]  INFO -- request: Accept: "application/vnd.github.mercy-preview+json"
User-Agent: "Octokit Ruby Gem 4.20.0"
Content-Type: "application/json"
Authorization: "token 638f47e591706cd4624e855e6506244dd8255d9d"
I, [2021-01-27T10:03:26.478839 #93187]  INFO -- response: Status 200
I, [2021-01-27T10:03:26.478888 #93187]  INFO -- response: content-type: "application/json"
    skips over any non-markdown files
I, [2021-01-27T10:03:26.483339 #93187]  INFO -- request: GET https://api.github.com/repos/alphagov/77698e58-b02c-4a5a-a8ee-665dcf06ca30/contents/docs
I, [2021-01-27T10:03:26.483410 #93187]  INFO -- request: Accept: "application/vnd.github.mercy-preview+json"
User-Agent: "Octokit Ruby Gem 4.20.0"
Content-Type: "application/json"
Authorization: "token 638f47e591706cd4624e855e6506244dd8255d9d"
    returns nil if no docs folder exists
    returns nil if the repo is private
    returns an array of hashes including title derived from markdown contents

Failures:

  1) GitHubRepoFetcher#repo fetches a repo from cache if it exists
     Failure/Error: all_alphagov_repos.find { |repo| repo.name == repo_name } || raise("alphagov/#{repo_name} not found")
       #<Double "Public repo"> received unexpected message :name with (no args)
     # ./app/github_repo_fetcher.rb:8:in `block in repo'
     # ./app/github_repo_fetcher.rb:8:in `each'
     # ./app/github_repo_fetcher.rb:8:in `find'
     # ./app/github_repo_fetcher.rb:8:in `repo'
     # ./spec/app/github_repo_fetcher_spec.rb:26:in `block (3 levels) in <top (required)>'

  2) GitHubRepoFetcher#repo raises error if no repo is found
     Failure/Error:
       expect {
         GitHubRepoFetcher.instance.repo("something-not-here")
       }.to raise_error(StandardError)

       expected StandardError, got #<RSpec::Mocks::ExpiredTestDoubleError: #<Double "Public repo"> was originally created in one example...only last for one example, and you need to create a new one in each example you wish to use it for.> with backtrace:
         # ./app/github_repo_fetcher.rb:8:in `block in repo'
         # ./app/github_repo_fetcher.rb:8:in `each'
         # ./app/github_repo_fetcher.rb:8:in `find'
         # ./app/github_repo_fetcher.rb:8:in `repo'
         # ./spec/app/github_repo_fetcher_spec.rb:40:in `block (4 levels) in <top (required)>'
         # ./spec/app/github_repo_fetcher_spec.rb:39:in `block (3 levels) in <top (required)>'
     # ./spec/app/github_repo_fetcher_spec.rb:39:in `block (3 levels) in <top (required)>'

  3) GitHubRepoFetcher#repo fetches a repo from GitHub if it doesn't exist in the cache
     Failure/Error: all_alphagov_repos.find { |repo| repo.name == repo_name } || raise("alphagov/#{repo_name} not found")
       #<Double "Public repo"> was originally created in one example but has leaked into another example and can no longer be used. rspec-mocks' doubles are designed to only last for one example, and you need to create a new one in each example you wish to use it for.
     # ./app/github_repo_fetcher.rb:8:in `block in repo'
     # ./app/github_repo_fetcher.rb:8:in `each'
     # ./app/github_repo_fetcher.rb:8:in `find'
     # ./app/github_repo_fetcher.rb:8:in `repo'
     # ./spec/app/github_repo_fetcher_spec.rb:33:in `block (3 levels) in <top (required)>'

  4) GitHubRepoFetcher#readme retrieves the README content from the GitHub CDN
     Failure/Error: all_alphagov_repos.find { |repo| repo.name == repo_name } || raise("alphagov/#{repo_name} not found")
       #<Double "Public repo"> was originally created in one example but has leaked into another example and can no longer be used. rspec-mocks' doubles are designed to only last for one example, and you need to create a new one in each example you wish to use it for.
     # ./app/github_repo_fetcher.rb:8:in `block in repo'
     # ./app/github_repo_fetcher.rb:8:in `each'
     # ./app/github_repo_fetcher.rb:8:in `find'
     # ./app/github_repo_fetcher.rb:8:in `repo'
     # ./app/github_repo_fetcher.rb:14:in `readme'
     # ./spec/app/github_repo_fetcher_spec.rb:76:in `block (3 levels) in <top (required)>'

  5) GitHubRepoFetcher#readme returns nil if no README exists
     Failure/Error: all_alphagov_repos.find { |repo| repo.name == repo_name } || raise("alphagov/#{repo_name} not found")
       #<Double "Public repo"> was originally created in one example but has leaked into another example and can no longer be used. rspec-mocks' doubles are designed to only last for one example, and you need to create a new one in each example you wish to use it for.
     # ./app/github_repo_fetcher.rb:8:in `block in repo'
     # ./app/github_repo_fetcher.rb:8:in `each'
     # ./app/github_repo_fetcher.rb:8:in `find'
     # ./app/github_repo_fetcher.rb:8:in `repo'
     # ./app/github_repo_fetcher.rb:14:in `readme'
     # ./spec/app/github_repo_fetcher_spec.rb:96:in `block (3 levels) in <top (required)>'

Finished in 0.15167 seconds (files took 2.15 seconds to load)
12 examples, 5 failures

Failed examples:

rspec ./spec/app/github_repo_fetcher_spec.rb:21 # GitHubRepoFetcher#repo fetches a repo from cache if it exists
rspec ./spec/app/github_repo_fetcher_spec.rb:38 # GitHubRepoFetcher#repo raises error if no repo is found
rspec ./spec/app/github_repo_fetcher_spec.rb:31 # GitHubRepoFetcher#repo fetches a repo from GitHub if it doesn't exist in the cache
rspec ./spec/app/github_repo_fetcher_spec.rb:71 # GitHubRepoFetcher#readme retrieves the README content from the GitHub CDN
rspec ./spec/app/github_repo_fetcher_spec.rb:92 # GitHubRepoFetcher#readme returns nil if no README exists

Randomized with seed 1

Coverage report generated for RSpec to /Users/kevindew/govuk/govuk-developer-docs/coverage. 373 / 688 LOC (54.22%) covered.
SimpleCov failed with exit 1

Documentation on password reset on PaaS is out-of-date

https://docs.publishing.service.gov.uk/manual/data-gov-uk-operations.html points to https://login.cloud.service.gov.uk/forgot_password which doesn't exist

Relative links on 'external documentation' don't resolve correctly on docs.publishing.service.gov.uk

Problem with '' (https://docs.publishing.service.gov.uk/apis/search-api/how-search-works.html)

Links e.g learning to rank documentation 404

e.g https://docs.publishing.service.gov.uk/apis/search-api/learning-to-rank.md -> 404

but https://docs.publishing.service.gov.uk/apis/search-api/learning-to-rank.html -> this works!

Remove page 'Jenkins Swarm Plugin'

Problem with 'Jenkins Swarm Plugin' (https://docs.publishing.service.gov.uk/manual/jenkins-slave-swarm.html).

This plugin is no longer used PR

"How to run an AB test" not linked in manual

Problem with 'Manual' (https://docs.publishing.service.gov.uk/manual.html)

The wiki for content designers at https://gov-uk.atlassian.net/wiki/spaces/CC/pages/87097383/A+B+Testing links to https://docs.publishing.service.gov.uk/guides.html#a-b-testing which no longer exists as an anchor.

I did a search and found the page it should link to: https://docs.publishing.service.gov.uk/manual/ab-testing.html
It doesn't look like the above page is linked from the Developer Docs navigation - if it's still relevant it should be. And ideally it would have the same anchor on the index page so that the link doesn't break.

Hope that helps
Jonathan

Low available disk space Alert docs

A section needs to be added to this on exactly how to extend the disk on EBS-backed Nitro EC2 Instances.

The process we used today to extend a disk w/ lvm on one such machine is below, this could do to be added to the docs in due course:

Resize nvme ebs drive

1. stop graphite: initctl stop graphite-web
   1. check nothing is using the disk any more: lsof /dev/mapper/graphite-data (should be no output - if not, try to stop remaining processes)
2. unmount volume: umount /dev/mapper/graphite-data
3. stop volume group: vgchange -a n graphite
4. identify block device's pci device:

    root@ip-10-13-4-104:~# readlink /sys/block/nvme1n1
   ../devices/pci0000:00/0000:00:1f.0/block/nvme1n1
   

5. remove device: echo 1 > "/sys/devices/pci0000:00/0000:00:1f.0/remove"
6. rescan pci bus: echo 1 > "/sys/bus/pci/rescan"

now, lsblk should report the correct size
if it doesn't, reboot - that will fix it. Then come back and do the rest:

7. resize to new extents: pvresize /dev/nvme1n1
8. check pv again to make sure stuff is now correct: pvdisplay
9. reactivate vg: vgchange -ay graphite
10. extend lvm to new extents: lvextend -l +100%FREE /dev/mapper/graphite-data
11. resize filesystem to new extents: resize2fs /dev/mapper/graphite-data
12. remount volume: mount /dev/mapper/graphite-data
13. restart graphite: initctl start graphite-web (and any other services stopped in 2)

Problem with 'Switch an app off'

Problem with 'Switch an app off' (https://docs.publishing.service.gov.uk/manual/howto-switch-off-app.html)

$ fab integration node_type:frontend puppet.disable
[localhost] Executing task 'node_type'
Disconnecting from [box]... done.
[box] Executing task 'puppet.disable'
Traceback (most recent call last):
  File "/Users/davidsilva/venv/fabric-scripts/lib/python2.7/site-packages/fabric/main.py", line 743, in main
    *args, **kwargs
  File "/Users/davidsilva/venv/fabric-scripts/lib/python2.7/site-packages/fabric/tasks.py", line 368, in execute
    multiprocessing
  File "/Users/davidsilva/venv/fabric-scripts/lib/python2.7/site-packages/fabric/tasks.py", line 264, in _execute
    return task.run(*args, **kwargs)
  File "/Users/davidsilva/venv/fabric-scripts/lib/python2.7/site-packages/fabric/tasks.py", line 171, in run
    return self.wrapped(*args, **kwargs)
TypeError: disable() takes exactly 1 argument (0 given)

Issues with 'Add a new document type'

@Davidslv @MatMoore you're set as the owners for:

https://docs.publishing.service.gov.uk/manual/add-a-new-document-type.html
https://docs.publishing.service.gov.uk/manual/make-a-new-document-type-available-to-search.html

Some issues:

• The pages have expired, but the manual spaniel can't handle 2 usernames. Perhaps choose one owner or add it to a channel.
• Pages probably need to go into the "Publishing" section
• https://docs.publishing.service.gov.uk/manual/add-a-new-document-type.html#make-the-new-document-type-available-to-search completely duplicates https://docs.publishing.service.gov.uk/manual/make-a-new-document-type-available-to-search.html

Problem with 'Get started on GOV.UK'

Problem with 'Get started on GOV.UK' (https://docs.publishing.service.gov.uk/manual/get-started.html)

Is this https://docs.publishing.service.gov.uk/manual/get-started.html and others
intended to be open widely to the public?

Re: 'SSH into machines'

Problem with 'SSH into machines' (https://docs.publishing.service.gov.uk/manual/howto-ssh-to-machines.html)

I think the suggested command

$ govuk_node_list backend

might be out of date? It doesn't seem to like a single bare argument anymore, the above now seems to be achieved by

$ govuk_node_list -c backend

Move styleguides into these docs?

https://github.com/alphagov/styleguides

Links within the 'manual' navigation are broken

The links within the left-hand nav on the manual section are broken – they all just link to /manual.html##{section_name.parameterize}.

It looks like it may have been broken since #1977 (b081338).

how to delete an asset?

Problem with 'Remove an asset' (https://docs.publishing.service.gov.uk/manual/howto-manually-remove-assets.html)

Re: 'How to use Logit for GOV.UK'

Problem with 'How to use Logit for GOV.UK' (https://docs.publishing.service.gov.uk/manual/logit.html)

The link to how to access is broken

Recommend upgrading your pact broker

Problem with 'Pact Broker' (https://docs.publishing.service.gov.uk/manual/pact-broker.html)

Hi, I am one of the maintainers of the Pact Broker open source project. I notice that you are running a very old version of the broker (I can tell because your index redirects to ui/relationships which it hasn't done for quite a while). There have been vulnerabilities found in old versions of the broker, so I recommend that you upgrade to the latest version. Please feel free to email me if you wish to discuss details.

Creating or moving a page gives a nil parsing error

Error message:

NoMethodError: undefined method `author_date' for nil:NilClass

Steps to replicate:

1. Rename a existing file - for example, changing redirect-routes.html.md to redirect-routes.html.md.erb.
2. Run ./startup.sh
3. Navigate to the new URL for the renamed file - for example, http://localhost:4567/manual/redirect-routes.html

I think that this is due to the file not being committed, which then means that author_date can't be found when file's git information is parsed:

govuk-developer-docs/helpers/commit_helpers.rb

Line 16 in 25dd413

Time.parse(Git.open(".").log.path(source_file(current_page)).first.author_date.to_s)

My stopgap solution was to commit it locally, then git commit --amend for the "real" commit. This also helps solve the other errors thrown by uncommitted files.

Other solutions could be involve using dig, or returning Time.now when no other time stamp is found?

Add support info for licensing apps

Debugging alerts for licensing is hard because it differs from the standard GOV.UK architecture in some ways, but not in others. It's not something we're actively working on, so there's little shared knowledge about where it exists on GOV.UK and what the different machines are for.

It was also surprising that it exists in Signon, given that it's commonly referred to as being 'special'. Appreciate all that is quite vague, but some kind of overview doc that explains the support status and touches on the infrastructure and user journeys would be helpful :-).

Dependabot can't resolve your Ruby dependency files

Dependabot can't resolve your Ruby dependency files.

As a result, Dependabot couldn't update your dependencies.

The error Dependabot encountered was:

Bundler::VersionConflict with message: Bundler could not find compatible versions for gem "coffee-script":
  In Gemfile:
    govuk_tech_docs was resolved to 1.6.3, which depends on
      middleman (~> 4.0) was resolved to 4.2.1, which depends on
        coffee-script (~> 2.2)

Could not find gem 'coffee-script (~> 2.2)', which is required by gem 'middleman (~> 4.0)', in any of the sources.

If you think the above is an error on Dependabot's side please don't hesitate to get in touch - we'll do whatever we can to fix it.

You can mention @dependabot in the comments below to contact the Dependabot team.