From a65765674536cc496fec9036c5cafb001438dd57 Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Mon, 7 Sep 2026 11:00:17 +0100 Subject: [PATCH 1/5] Add a lifecycle section to style guide --- style/git_and_github.qmd | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index c0c0e264..f0a53f1f 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -196,7 +196,7 @@ To explain your code's purpose: So people can understand the state of your project: -* use `README` badges to indicate statuses like passing checks, [project lifecycle stage](https://www.repostatus.org/) and publication to package indexes (e.g. PyPi, CRAN) +* indicate the lifecycle stage of the reposiitory (see 'Lifecycle' section below), for example, use `README` badges to indicate statuses like passing checks, [project lifecycle stage](https://www.repostatus.org/) and publication to package indexes (e.g. PyPi, CRAN) * [tag and release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) your code using [semantic versioning](https://semver.org/) and add clear notes of the changes made * keep a human-readable changelog up-to-date (e.g. [a NEWS.md file](https://r-pkgs.org/other-markdown.html#sec-news) in an R package) @@ -229,6 +229,26 @@ To make it easier for developers to get an at-a-glance understanding: * use a simple, self-explanatory directory structure (e.g. images in `img/`, data in `data/`) * start with [the SU template repository](https://github.com/The-Strategy-Unit/template-repository) (click 'use this template' button or '+ create new' > 'new repository' > 'start with template') +### Lifecycle + +It should be clear to users what lifecycle stage each of our repos is at. +This signals how mature the content is, how useable it might be and how much support we can provide. +It can help set expectations and prevent misunderstandings. + +Two statuses are particularly important to flag. +When the repository: + +1. Is a work in progress or demo, when code may not be guaranteed to work and features are missing. +2. Has been archived, when the content is no longer in use, will not be developed further and when little to no support will be provided. + +Codeowners are responsible for considering how best to indicate a repository's lifecycle. +Some ideas are to: + +* add a note early in the README to explain how developed the work is (perhaps in [a callout](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)) +* add a README badge from [repostatus.org](https://www.repostatus.org/), particularly 'WIP' (work in progress) and active (stable but developing) +* add a reference in the repo's 'About' section, such as '(work in progress)' +* [archive the repo](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories), a special status that indicates a repo is not maintained or supported, which keeps the repo open but disables interaction + ## Further reading See also our [GitHub as a Team Sport](../presentations/2024-05-23_github-team-sport/index.qmd) presentation for ideas about working together in GitHub repos. From f08999afd3ea61a79814c6643d24c59fa75cc6fc Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Mon, 7 Sep 2026 12:41:22 +0100 Subject: [PATCH 2/5] Correct typo --- style/git_and_github.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index f0a53f1f..b8ed058d 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -196,7 +196,7 @@ To explain your code's purpose: So people can understand the state of your project: -* indicate the lifecycle stage of the reposiitory (see 'Lifecycle' section below), for example, use `README` badges to indicate statuses like passing checks, [project lifecycle stage](https://www.repostatus.org/) and publication to package indexes (e.g. PyPi, CRAN) +* indicate the lifecycle stage of the repository (see 'Lifecycle' section below), for example, use `README` badges to indicate statuses like passing checks, [project lifecycle stage](https://www.repostatus.org/) and publication to package indexes (e.g. PyPi, CRAN) * [tag and release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) your code using [semantic versioning](https://semver.org/) and add clear notes of the changes made * keep a human-readable changelog up-to-date (e.g. [a NEWS.md file](https://r-pkgs.org/other-markdown.html#sec-news) in an R package) From a6f3e4d3e22e005890bda41883967f02fe9046ab Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:12:05 +0100 Subject: [PATCH 3/5] Tweak wording for clarity --- style/git_and_github.qmd | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index b8ed058d..447ab5ae 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -238,10 +238,10 @@ It can help set expectations and prevent misunderstandings. Two statuses are particularly important to flag. When the repository: -1. Is a work in progress or demo, when code may not be guaranteed to work and features are missing. -2. Has been archived, when the content is no longer in use, will not be developed further and when little to no support will be provided. +1. Is a work in progress or demo, which means that code is not guaranteed to work and features may be missing. +2. Has been archived, which means the content is no longer in use, will not be developed further and that little to no support will be provided. -Codeowners are responsible for considering how best to indicate a repository's lifecycle. +Codeowners are responsible for considering how best to indicate a repository's lifecycle stage. Some ideas are to: * add a note early in the README to explain how developed the work is (perhaps in [a callout](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)) From 2f403087f47204253620c8123af8d5e533d39633 Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:12:26 +0100 Subject: [PATCH 4/5] Note that we prefer archiving to deleting --- style/git_and_github.qmd | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index 447ab5ae..5f706aec 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -249,6 +249,10 @@ Some ideas are to: * add a reference in the repo's 'About' section, such as '(work in progress)' * [archive the repo](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories), a special status that indicates a repo is not maintained or supported, which keeps the repo open but disables interaction +We prefer to archive repositories rather than delete them. +This keeps our work in the open so that we and others can reuse, develop and/or learn from it later. +This also makes it easier to reactivate a repository in future, should the need arise. + ## Further reading See also our [GitHub as a Team Sport](../presentations/2024-05-23_github-team-sport/index.qmd) presentation for ideas about working together in GitHub repos. From 9ead071cff77090c0444455435e89b5bcd3888ab Mon Sep 17 00:00:00 2001 From: Matt Dray <18232097+matt-dray@users.noreply.github.com> Date: Mon, 7 Sep 2026 15:20:05 +0100 Subject: [PATCH 5/5] Clarify how to edit the repo description --- style/git_and_github.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/style/git_and_github.qmd b/style/git_and_github.qmd index 5f706aec..ad7f4c51 100644 --- a/style/git_and_github.qmd +++ b/style/git_and_github.qmd @@ -246,7 +246,7 @@ Some ideas are to: * add a note early in the README to explain how developed the work is (perhaps in [a callout](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts)) * add a README badge from [repostatus.org](https://www.repostatus.org/), particularly 'WIP' (work in progress) and active (stable but developing) -* add a reference in the repo's 'About' section, such as '(work in progress)' +* reference the lifecycle stage in the repo's description (to edit, click the cog above the 'About' section of your repository's home page), such as '(work in progress)' * [archive the repo](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories), a special status that indicates a repo is not maintained or supported, which keeps the repo open but disables interaction We prefer to archive repositories rather than delete them.