PHS Data Science - Knowledge Base

The PHS Data Science Knowledge Base is a web app that collates all resources related to Data Science (R, Python, git, etc.) created by and for PHS staff. This includes booking for in-person and access to online training, guidance documents, and internally developed textbooks. There is also a social page for announcements related to Data Science in the organisation, social links, and a list of relevant external materials such as textbooks and blogs.

Directory structure

├── assets                     // static resource
│   ├── courses.json           // data for courses and content
├── .github
│   ├── workflows/deploy.yml   // builds and deploys to GitHub Pages on push to main
├── docs                       // generated by CI on deploy - not committed, gitignored
├── layouts                    // layouts
│   ├── default.vue            // site-wide template
├── pages                      // pages
│   ├── index.vue              // homepage
│   ├── social.vue             // social page
├── plugins                    // external components
├── static                     // static resources like images
├── .gitignore                 // gitignore
└── package.json               // package.json

Build Setup

The project is built with Vue and Nuxt. Requires Node.js 20 or later (CI builds with Node 22).

# install dependencies
$ npm install

# serve with hot reload at localhost:3000
$ npm run dev

# build for production and launch server
$ npm run build
$ npm run start

# generate the static site into docs/ (what CI runs on deploy)
$ npm run generate

Deployment

Trigger	Every push to main (including a merged pull request), or manually via workflow_dispatch from the Actions tab
Produces	The live site, published to GitHub Pages
Comes from	.github/workflows/deploy.yml runs npm ci && npm run generate, which builds the Nuxt app into docs/ (the generate.dir set in nuxt.config.js); that output is uploaded and deployed as the Pages artifact

No manual build, no committing docs/, and no merging to a gh-pages branch - docs/ is build output only, regenerated on every deploy and not tracked in git (see .gitignore).

Committing changes

Before opening a pull request against main:

• Build: run npm run generate locally and confirm it completes without errors - this is exactly what CI runs, so a local failure will fail the deploy too.
• Test: there is no automated test suite for this app. Run npm run dev and manually check the page(s) your change affects, including any other page that uses a shared component, layout, or plugin you touched.
• Commit style: follow the contribution guidance.
• Changes are made via pull request into main - merging triggers the deploy described above.

Releases

A release is a vX.Y.Z git tag plus a GitHub Release, cut manually via two chained workflows - separate and independent from deployment, which happens automatically on every merge whether or not a release is ever cut. See CONTRIBUTING - Branching and Release Process for the process to follow when using these.

1. Prepare Release

Trigger	Manual - Actions tab → Prepare Release → choose patch, minor, or major
Produces	A release/vX.Y.Z branch, and a pull request from it into main, labelled release
Comes from	.github/workflows/release-prepare.yml applies the chosen bump to whatever version is currently in package.json on main, via npm version

2. Publish Release

Trigger	Automatic, when a pull request labelled release is merged
Produces	A git tag vX.Y.Z on main, and a GitHub Release with auto-generated notes
Comes from	.github/workflows/release-publish.yml reads the version from package.json on main after the merge, and generates release notes from the pull requests merged since the previous release tag - nothing is fixed or recorded at the point Prepare Release was triggered

Expectations and limitations

• Deployment and releases are independent: every merge to main deploys the live site whether or not a release is ever cut.
• Both release workflows depend on main's pull-request requirement - workflow_dispatch cannot bypass branch protection, so a version bump goes through the same review as any other change. If branch protection is ever relaxed and someone pushes to main directly, that change won't appear in a release's auto-generated notes (they're generated from merged pull requests, not raw commits).
• The release label is required for release-publish.yml to trigger. release-prepare.yml creates it automatically if missing - don't remove it from an open release pull request, or the tag/release won't be created on merge.
• See CONTRIBUTING - Branching and Release Process for the sequencing to follow (e.g. merging the release PR last) to make sure a release captures the changes you expect.

Contributing

This app currently has one developer, Russell McCreath with oversight from the PHS Data Science team. For details on how to contribute, please see the contribution guidance.