guardian / guardian/coding-exercise-project

Standardise toolchains with .tool-versions and verify builds in CI

Open
#143 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
18
Forks
25
PR merge metrics
No merged PRs in 30d

Description

The example skeleton projects all use their own approach to setting up their language toolchains. Many use `brew`, which will only work on a Mac, but there are other approaches including assuming the tools are already available.

Additionally, lots of the projects are very out of date, and will no longer build. Ideally we'd know about this automatically ahead of time.

This issue tracks the work to fix that.

See also: https://github.com/guardian/coding-exercise-project/issues/142

#### Approach

- Each project declares its toolchain in a `.tool-versions` file, pinned to the major version (e.g. `java 21`, `sbt 1`).
- `script/setup` runs the project's own dependency-fetch command, which populates their caches and ensures the language build tools defined in .tool-versions are available.
- `script/test` runs a trivial passing testuite in the example skeleton project, which ensures the project builds and runs. These test scripts are now consistent so this can be run from CI.
- The root README recommends [mise](https://mise.jdx.dev/) for reading those files, but any version manager that understands `.tool-versions` would work.
- CI discovers projects by looking for a `.tool-versions` file. CI also includes a step that fails the build if a project declares a toolchain without also providing the standard `script/setup` and `script/test` scripts.

#### Changes to the test-suites

This collection of PRs change the stub test suites so that they pass, instead of fail.

The original pattern was to have a failing test in every project skeleton, likely to follow the TDD pattern of going `red ➡️ green` in a loop. With the new approach we want to catch problems with these ill-maintained examples, and we need a way to automatically verify that the setup works.

We don't lose much (if anything) on the getting started side by having the test start green, but we gain a lot on the maintenance side by having these tests be automatically checked.

This is why each language is split into two PRs - one to set up the project (including making sure the test suite passes), and a second one that migrates to the new .tool-versions file structure.

#### PRs

The platform PR sets up CI and the documentation, all the language specific PRs build on top of it. Projects are independent of each other, but within a project `fix` must merge before `adopt`. Where languages include multiple PRs (a fix PR separate to an adopt PR), these have been "stacked" in GitHub.

**Platform** — the CI workflow and README updates:

- #144 Add the CI workflow and document mise

**Per project** — `fix` makes the project builds and the tests pass ,`adopt` adds `.tool-versions` and updates `script/setup`:

- `scala`
- fix #145
- adopt #146
- `java`
- adopt #147
- `rust`
- adopt #148
- `swift`
- adopt #149
- `python`
- fix #150
- adopt #151
- `ruby`
- fix #152
- adopt #153
- `javascript`
- fix #154
- adopt #155
- `javascript-esm`
- fix #156
- adopt #157
- `typescript-deno`
- fix #158
- adopt #159
- `typescript-node`
- fix #160
- adopt #161
- `go`
- fix #162
- adopt #163
- `kotlin`
- fix #164
- adopt #165
- `dot-net-core`
- fix #166
- adopt #167
- `clojure`
- fix #168
- adopt #169
- `php`
- fix #170
- adopt #171

#### Notes

- java, rust and swift have no `fix` PR: their tests already pass on `main`.
- `typescript-node`'s `fix` PR is large even though there are only a few changes. This is because of the Yarn zero-install cache regeneration, which is unavoidable because the committed lockfile is stale.
- The `clojure` project was nested one directory deeper than every other skeleton. Its `adopt` PR unnests it, so that the CI discovery works.

The expected end state (with every project change included) is on [`integration/verify`](https://github.com/guardian/coding-exercise-project/compare/main...integration/verify). That branch is pushed so we can see the whole change at once if that's useful, it shouldn't be merged.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the root README, the CI workflow, and the existing project directories; inspect the `.tool-versions`, `script/setup`, and `script/test` conventions described here. Review #144–#171 and the `integration/verify` branch to understand the work already underway. Done means every discovered project follows the standard setup and test contract and CI verifies its build.

Written by the indexing model from the issue text.

Assessment

Tech stack
clojure, csharp, git, github-actions, go, java, javascript, kotlin, php, python, ruby, rust, scala, shell, swift, typescript
Domain
build-system, ci-cd, developer-experience, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
20/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.