https://gds-way.cloudapps.digital/manuals/licensing.html#use-mit says that all repositories should have a LICENCE file and that we use the MIT licence.

https://gds-way.cloudapps.digital/standards/publish-opensource-code.html#how-to-publish-open-source-code says that we use the MIT licence for code and code samples in documentation and Open Government Licence (OGL) for documentation.

Some questions I'd like clarity on (and then I'm happy to try and improve the documentation based on the answers):

1. Should absolutely all repositories contain a LICENCE file? For example the gds-way repository itself does not have a LICENCE file. Note, if you build the gds-way docs then there is a link at the bottom of all pages to the OGL licence. Is that sufficient rather than having an actual LICENCE file in the repository?

2. For documentation repositories, should we therefore be including two licences (MIT and OGL)? Does this differ if the repository is the documentation (e.g. https://github.com/alphagov/monitoring-doc) versus the repository gets built into an actual website serving documentation (such as the gds-way)?

I would like to have a conversation around the "Important Note" that can be seen on the "Using Node.js at GDS" page.

We currently don't have a Deputy Director Technology Operations at GDS to consult around this issue, and if we did would this person be the correct person to consult with and make this decision? Should this paragraph be reworded so that a decision is made from a key group of individuals using the new GDS Way Forum strategy that has recently been proposed? Or should the paragraph now be removed completely?

Node is already being used internally, and it is a language area that has a huge supporter base that has matured greatly in the past few years. I'm concerned that this paragraph will immediately halt any consideration for using Node in projects, even when it could be the perfect technology to use.

Python 2.7 is recommended against by the python maintainers for new stuff, and has an end of life in 2020.

Python 3.6 is the latest release and should probably be used for new stuff.

Upgrading from 2.7 to 3.x can be tricky.

We should make a clear recommendation about python version.

what did we learn? what else do we need to do?

In the 3rd main paragraph of https://gds-way.cloudapps.digital/#about-the-gds-way we mention the Tech Forum. We don't say what that is, or how to get in touch with it. It might make sense to have a short explanation and then a link to a more detailed section about governance/representation as a h3 within "Adding new guidance" at the bottom.

There are quite a few examples of GDS projects that use static website generation tools but no actionable guidance on the topic.

Prior art includes:

• gatsby a javascript and react based static site publishing tool used by the Open Registers Specification
• hugo a go based static site publishing tool
• jekyll a ruby based static site publising tool
• middleman a ruby based static site publishing tool used by the tech-docs-template and many GDS teams such as the GOV.UK PaaS paas-tech-docs

There are many approaches to hosting

• AWS S3 with cloudfront
• GitHub Pages
• GOV.UK PaaS static buildpacks
• Heroku static site
• Netlify
• anything that can run a container with a web server in it e.g a docker container with nginx on GOV.UK PaaS or the GDS Supported Platform

and probably more if we go looking.

Some guidance on which options are best for specific user needs would be helpful.

e.g. I need to publish technical documentation for a GDS Service or publish my teams working practices as a Team Manual

(As suggested by Will Pearson.)

I know there's lots of discussion about APIs within GDS, but there's nothing currently in The GDS Way. Should we add something around APIs?

The Open Standards team is currently evaluating whether we should mandate the use of OpenAPI v3 to document all our APIs.

See the discussion on co-cddo/open-standards#31

add guidance to https://github.com/alphagov/gds-tech/blob/gh-pages/source-code.md

questions from TechOps Forum 29.04.2017:

• Can our deployment systems deploy from GitLab?
• How do we do account management on GitLab?
• What’s the commercial model for moving away from github enterprise, and for gitlab
• Do we need the ability to take a full archive or can we rely on the integrity of the git artefact?

https://sentry.io

non on G-Cloud

zuz to meet with Nick Sinclair and find out how it can be procured

bob & Alex to start collecting numbers to determine which tier we need (most likely Enterprise but need some numbers ie no of events to begin conversations) and start creating the business case

Problem with 'How to do penetration tests' (https://gds-way.cloudapps.digital/standards/how-to-do-penetration-tests.html)

I'm getting a 404 on "GDS Information Assurance (IA) team" and "contact the IA team", both of which point to https://sites.google.com/a/digital.cabinet-office.gov.uk/gds/operations/information-assurance.

From @selfthinker on PR #828:

When the alt-text section was changed in #500 it was to align with the GOV.UK content guidance. But The GDS Way is not about GOV.UK content specifically (although it can, and maybe should, be included) but about products from all of GDS. And the guidance in here currently does not align with the Design System guidance.

I think this is a valid point and one we should address. My view is that it might make sense to make this section much smaller (probably keeping the bit about figcaption) and link to the Design System guidance on alt text. It's a good introduction to using alt text, it explains most of the same things we're saying here, and it's not overly prescriptive, so GOV.UK and other teams can have their own more specific guidance if they want to.

I wanted to keep the changes in #828 limited so didn't make this change in that PR - capturing in an issue and assigning to myself so it still gets done.

I've just tested the GDS Way in Edge 16 (latest, released in October) and have noticed a strange issue where clicking on an anchor jump link in the left hand nav now has no effect.

The browser looks like it is trying to jump down, the URL hash changes for a second, then reverts back to its previous state.

Note: this has been tested in BrowserStack. It would be good to test and debug on a device actually running 16 rather than through the emulator. Would be worth investigating if a page refresh is being triggered, as that is what it looks to be doing.

Also Edge 15 and 14 work as expected, looks to be a 16 only issue.

Problem with 'Linting Python at GDS' (https://gds-way.cloudapps.digital/manuals/programming-languages/python/linting.html)

• I can't click on links that are on the last line before a new section

To reproduce:

• Find a link that is on a line just before a section - for example "Flake8 error codes list", or "by performing a PyPI search".
• Try to click on it. It won't work.
  • Neither will the link be highlighted when you hover over it.

I wonder if this issue is common to all GDS Way pages.

#26

To reproduce:

• Goto: https://gds-way.cloudapps.digital/#standards
• Shrink the viewport down to approx 760px
• Try clicking on "storing source code" link
• Link not clickable due to following headings negative margin causing an overlap.

Issue caused here

h3, h4, h5, h6 {
    @include heading-offset($gutter);
  }

Proposed fix:

1. Either remove usage of the mixin in this case and add specific styling manually (less padding, no negative margin)
2. Continue to use the mixin but add an override after it's usage

Option 1 seems like the cleanest to me with minimal impact.

https://gds-way.cloudapps.digital/manuals/programming-languages/docker.html#content
https://gds-way.cloudapps.digital/standards/tracking-dependencies.html#docker-base-images

The current "How to host a service" page is scheduled for review:

https://gds-way.cloudapps.digital/standards/hosting.html

Is there anything we think should change about it?

I'd like to see a bit more guidance on how to decide whether to host something on PaaS or IaaS.

https://gds-way.cloudapps.digital/standards/pull-requests.html#reviewing-a-request
and
https://gds-way.cloudapps.digital/manuals/code-review-guidelines.html

We need to consolidate or at least cross-reference these pages

Problem with 'JavaScript coding style' (https://gds-way.cloudapps.digital/manuals/programming-languages/js.html)

The last item in the contents list is: "Let the project define the style". There does not appear to be a matching section.

Problem with 'The GDS Way' (https://gds-way.cloudapps.digital/)

Hi,

Just had a look through the GDS Way and and realised that the How to store source code link doesn't appear to work.

I hope this helps,
Aidan

The content on the building accessible services page is good quality but has significant overlaps with the Making your frontend accessible guidance in the service manual.

To avoid repeating ourselves, we should remove the overlapping content and link this page to the service manual guidance. It would also be beneficial to add specific guidance for GDS developers e.g. using the empathy lab.

Problem with 'Threat Modelling' (https://gds-way.cloudapps.digital/standards/threat-modelling.html)

The link to OWASP is broken, I think it should now be https://owasp.org/www-community/Threat_Modeling

Following a discussion with @jamietanna here, should we have some guidance around markdown, even if that's to say no preferences around usage?

I'm in favour of setting a max line length and using breaks within a sentence as I find it makes using the terminal and comparing changes in commits easier, but I do appreciate that's not easy to maintain with some editors including GitHub's web interface and some parsers/renderers handle differently. So, I'd happily follow guidance saying not to break sentences if it was noted and included somewhere, or maybe we note that there's no set guide as long as the output renders correctly?

The guidance on NodeJS currently recommends using the Express framework for web applications.

It has been suggested that the Koa framework is now a better fit for how we advise writing NodeJS JavaScript. While this is true, Koa's design encourages a different way of writing application code¹ which:

• requires developers to provide common features like routing, sessions, etc...
• has fewer conventions around how to write applications

GDS also currently has no examples of applications written in Koa in production.

While all of this is true, it also appears the guidance to use Express has prevented developers choosing Koa in the past, despite it potentially being a better fit.

This aims to collect the discussion in one place and gather evidence for how we advise developers choosing between Express and Koa and whether migrating to Koa from Express is something teams should consider.

1. see #606 (comment) for more detail

might be useful to add rationale for this here: https://github.com/alphagov/gds-tech/blob/gh-pages/source-code.md

@alexmuller working on this, reduced number of repos on GHE to c. 180 from 300 so far. some conversations with non-GOV.UK teams still need to happen though.

Isobel is working out costs.

Since PR #400 we've added a Technical Operations page for the Cyber and RE pages to sit underneath: https://gds-way.cloudapps.digital/standards/technical-operations.html
We should also include content on User Support in this section as they are part of the Technical Operations programme.

A 'How GDS provides user support' page already exists here: https://gds-way.cloudapps.digital/standards/user-support.html

We should review this page and either move the content under the TO page or cross-link

Should we go further and tackle the problem of JavaScript having so many ways to write things? Not just at the commonjs level, but also things like => vs function, class vs function, for vs forEach vs map, Promises vs async/await, TypeScript vs Flow, etc.

Every other language has the same issue, of course. But JS happens to be worse, and this can result in code being very hard to read and modify by devs inheriting a JS codebase (which is the main problem the GDS Way is trying to solve, I think). And I'm not even talking about packages like Ramda that let you write your JS in an almost unintelligible way for people not used to pure functional programming or other paradigms. Should we encourage some of those practices and reject others?

I'm afraid I don't have a PR that answers this, but I think an extra conversation about higher-level abstract patterns is worth having.

(related to guidance that will be published on Service Manual for the rest of government )

It would be good to re-use all/some of the guidance Laura wrote in this PR - #89

If it can capture the way things are working right now it can be amended/expanded later as needed.

Problem with 'HTML coding style' (https://gds-way.cloudapps.digital/manuals/programming-languages/html.html)

Hello I just noticed a typo on this page, here below the details:

@ line 131
"Links should not open new tabs or windows by default, but if users choose to to so (through keyboard[...]"
correct word is do

regards
Paola

(how much £££ do we need for everyone to be able to use Logit etc, Pay PCI requirements)

working with Alethea

After a short review we noted there are various aspects that are out of date and could go with an update especially around
aria-labelledby= guidance and <section> use.

https://gds-way.cloudapps.digital/manuals/programming-languages/html.html

Ruby is mentioned 3rd in the list of backend programming languages we use, and doesn't have an actual section dedicated to it. This makes it seem like an odd choice, when it is our number one language. I think it's important we reflect that in the guide.

Problem with 'Programming languages' (https://gds-way.cloudapps.digital/standards/programming-languages.html)

now available on G-Cloud

procurement docs to be set up

bob & Alex to start collating info for the business case

current users: Pay, DMP