Add recommendations for continuous integration, delivery and deployment

[stephengeller]

What does this change?

This PR adds documentation on continuous integration, deployment and delivery at the Guardian.

Following @guardian/developer-experience 's sessions on establishing a vision for CI & CD, these documents list the current state of play for these areas as well as our vision for what it could look like in the future.

For more information and context, please see the Best Practices Index created from the above sessions, with links to research and proposal documents inside.

How to test

Verify that these documents align with our current practices and assess whether the proposal is appropriate for our department.

How can we measure success?

We have a clear set of documents listing our best practices for continuous integration, delivery and deployment.

[davidfurey]

Thanks for contributing to the recommendations repo! There are definitely some great things in here. I think it makes sense to mark this as a draft PR for now, and not consider merging it until it provides clear recommendations for the approach developers should use now.

Also, since this is a public repo ideally the final version would not contain links to docs that are not public.

[stephengeller]

Thanks @davidfurey , that's good advice. I'll take those notes onboard - should be feasible to at least make all information public, and I can capture current approaches better here too.

[stephengeller]

@davidfurey your suggestions have been actioned and this is hopefully now ready for review, let me know if there is more needed.

[davidfurey]

Thanks for the changes, it is much clearer now. What do you think about moving the future vision into a github issue or Google doc? My preference would be for the recommendations repo to be a living document of what we currently recommend rather than a place to articulate our vision. But I'd like to hear your and others views, because maybe future vision does belong here.

[stephengeller]

Interesting - I think you're right, having in one of those two places could be better as I do agree that we should keep this centred around recommendations rather than visions.

I'd worry that the vision would get lost if in a Google doc though, so maybe an issue or even a discussion would be more suitable? It would mean we have what we are doing colocated with what we want to be doing in the future. Also keen to hear other people's thoughts though.

[stephengeller]

Following a conversation on chat with @davidfurey , we have agreed to move the proposals side of this PR to a GitHub discussion and keep this PR focused on current recommendations. Will update this PR accordingly soon!

[stephengeller]

Future vision has been moved to a discussion (https://github.com/guardian/recommendations/discussions/50) and removed from this PR.

[markjamesbutler]

Should we be suggesting this if there isn't a safe way to do it? Probably we need to discuss what is mean't by safe.

[stephengeller]

Sorry, didn't see this comment until now! This is a good point, but I think this could be better explained by changing the phrasing a bit.

I've just pushed a change that aims to rephrase the recommendation from "there isn't a safe way to push artefacts to RiffRaff" to "we haven't developed a best practice for this yet", which is more accurate. I think, at the time, I meant "safe" as "you can't safely use the recommended node-riffraff-artifact in GitHub Actions as you'd have to publish/configure credentials somewhere", but this would be fairly safe to do if you configured AWS credentials in each repo and rotated them regularly.

I think a good (and safe)solution for this is possible (likely relying on Guardian org-wide tokens being set up and a custom GitHub Action to implement it), and I think it's sensible to still encourage people to use GitHub Actions as it is a great interface, free for public repositories, and safe to use for the tasks mentioned besides publishing artefacts to RiffRaff.

[akash1810]

minor: Could we add the qualifier that CI should have a single step, and that is to run this script:

Where possible, have CI execute a single, centralised script in the repository named scripts/ci

[stephengeller]

Yeah, good call. Added this. Also corrected my own error of scripts -> script in the process

[mxdvl]

Mostly Markdown formatting comments from me.

I noticed we didn’t mention anything about visual testing or code coverage. Is it too team-specific to make it into a recommendation?

[mxdvl]

Same as above, if you've added the link this will be turned into it automatically.

Suggested change

	**See [continuous integration](continuous-integration.md)**
	**See [continuous integration]**

[mxdvl]

Should we make a note of UI / visual regression testing here? The interface of our applications is often an important part of the integration process.