Skip to main content

Search the Commons

Type at least 2 letters. Use the arrow keys to move through results, Enter to open, Escape to close.

Ask a question instead: answers drawn from across the Commons, with links to the source. Or browse the site map.

Get started · GitHub for the Commons

New to GitHub? How the Commons and its code work together

Everything you see in this portal is built from files kept in one open, public place on GitHub. You don't need to code to use it. This page explains what GitHub is, why the Commons uses it, and what you can do there at each level of confidence.

In short: a plain English summary
  • This page explains GitHub.
  • GitHub is a website where people share their work in the open.
  • The code and words for this website are kept there.
  • You can read everything without an account.

What GitHub is

GitHub is a website for keeping files that many people work on together. Think of it as a shared folder that remembers every change ever made, who made it and why, with a noticeboard attached where anyone can raise a problem or suggest an improvement. A project's folder on GitHub is called a repository (or "repo").

The Commons repository is github.com/cyberdudeuk/dq-commons. It is public, so anyone can read it, and free to reuse: code under the MIT licence and documentation and content under CC BY 4.0.

Why the Commons uses it

Background, aims and desired outcomes of the Commons itself are on About the Commons.

How the portal and the repository connect

  1. 1. FilesRules, frameworks, page content and the toolkit's code are files in the repository.Folders such as knowledge/, rules/ and dqkit/
  2. 2. A changeSomeone suggests a change: a fix, a new framework, a case study.As an issue or a pull request
  3. 3. ReviewA maintainer checks it for accuracy, personal data and plain English.See the charter
  4. 4. Automatic checksTests, accessibility, security and link checks run on their own.Called GitHub Actions
  5. 5. PublishedOnce merged, the portal rebuilds and goes live within minutes.Hosted on GitHub Pages
  6. 6. ReleasedBigger sets of changes get a version number and release notes.See releases

What you can do, by level

Beginner no account needed

  • Read any file and its history in your browser.
  • Download a release as a zip file to keep or share.
  • Use everything in this portal; none of it needs GitHub.

Intermediate free GitHub account

  • Report a problem or ask for a feature with a short form (an issue).
  • Join a conversation in Discussions.
  • Suggest a wording fix straight in your browser (a pull request).
  • Watch the repository to hear about new releases.

Advanced some technical confidence

  • Run the toolkit on your own computer (see the README).
  • Add rules, framework packs or code, with tests.
  • Take your own copy (a fork) to adapt for your organisation.
  • Read CONTRIBUTING.md and the architecture notes.

Step by step

Report a problem or idea

  1. Sign in to GitHub (creating an account is free).
  2. Go to New issue.
  3. Choose the form that fits: bug, feature, rule or pack, or contribution.
  4. Fill in the boxes in plain words. Leave out names and personal details.
  5. Select Create. You'll get updates as it is worked on.

Suggest a wording change

  1. Open the file you want to change on GitHub.
  2. Select the pencil icon, "Edit this file". GitHub makes your own copy for you.
  3. Make the change, then write one line saying what you changed and why.
  4. Select Propose changes, then Create pull request.
  5. A maintainer reviews it; the automatic checks run; once merged it goes live.

GitHub's own guide is a good next step: Hello World (about 10 minutes).

Key words

Repository (repo)
The project's folder of files and their full history.
Commit
One saved change, with a note saying what changed and why.
Branch
A separate line of work, so changes can be tried without affecting the live version.
Pull request
A proposal to bring a change into the main version, with room for review and discussion.
Issue
A numbered report of a problem, question or idea, with its conversation.
Fork
Your own copy of someone else's repository, to adapt or to propose changes from.
Release and tag
A named, numbered version (for example v2.0.0) you can download and refer to.
GitHub Actions
Automatic jobs that test, check and publish the work on every change.
GitHub Pages
GitHub's free website hosting, which serves this portal.
Dependabot
An automatic helper that proposes updates when tools the Commons relies on change.

How every portal feature connects to GitHub

Everything you can do in the portal has a matching place on GitHub. Every portal form opens the GitHub form below, already filled in with what you typed, and the portal shows the results (published contributions, survey totals, votes) after its daily update. You need a free GitHub account to submit; if you don't have one, ask a colleague to send it, or say so in the contact form.

In the portalOn GitHubGood to know
Contact us (every page footer, Help us build this)Issue form: Contact the CommonsThe portal fills the form in for you. No email address is shown or needed.
Suggest a feature, wishlistIssue form: Feature request or wish; issues labelled wishlistA thumbs-up reaction on a wish is a vote. The portal shows the counts on Help us build this.
Share a resource, case study, event, blog, video or podcastIssue form: Contribute to the libraryModerators review it within 10 working days (the Triage workflow flags anything waiting).
Report a problemIssue form: Something isn't workingUse made-up example data.
Add a rule, identifier, value set or framework packIssue form: Rule or packOr open a pull request with the YAML file.
Ask the Commons for help (commission)Issue form: Ask for helpWe reply on the issue.
Roadmap (Now, Next, Later, Done)MilestonesKept in step with the portal automatically when the backlog changes.
BacklogIssues labelled backlog; needs-people marks prepared items waiting on peopleComment to discuss, or say you're picking it up.
Co-design, ideas and questionsDiscussions: Ideas, Q&A, Show and tellComment in your own time, from any time zone.
What's new, releasesReleasesEach version has notes, a source zip and an offline copy of the portal. Watch the repository (Custom, Releases) to be told.
Pipeline statusActions: Data quality pipeline; issues labelled dq-escalationRuns every Monday; anyone with access can press Run workflow.
Content health, broken links, settingsActions: Content health, Link check, Repository health; one tracked issue eachOpened when there is a problem, updated while it lasts, closed when it is fixed.
Accessibility statementActions: Accessibility (axe-core on every change)A pull request that breaks accessibility can't pass.
Every page's change historyCommit history for that pageLinked from each page footer.
SecurityPrivate vulnerability reporting, secret scanning, Dependabot, CodeQLReport problems privately, never in a public issue.
The portal itselfGitHub Pages, built by the publish portal workflowEvery change to main republishes it.
Pull requestsDependency review, automatic area labels, CODEOWNERS reviewNew dependencies with serious known vulnerabilities, or closed licences, are refused automatically.
Downloads you can trustSigned build provenance and a software bill of materials on each releaseAnyone can check a download came from this repository: gh attestation verify FILE -R cyberdudeuk/dq-commons.
Citing the Commons"Cite this repository" (CITATION.cff)For research and publications.

Find other public sector code

The Commons is one of thousands of public sector projects on GitHub. The GitHub Repos Asset Catalogue lists every UK public sector code project, organised by topic, organisation, question and capability, and explained in plain English for people who don't use GitHub. Search it for "data quality" to find checks, validators and dashboards other teams have already built, and reuse them before building your own.

The catalogue and the Commons share an approach: open by default, plain English at three levels, contact by form only, and automatic checks that keep personal data and credentials out of the repository.

Staying safe in a public space