From d59a6e48c7ad28689c0e6c85b54d8406a24eacb8 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 8 Dec 2025 16:32:45 +0100 Subject: [PATCH] docs: :memo: update README and other general details from template --- .copier-answers.yml | 11 +++++ .zenodo.json | 46 +++++++++++++++++++ 404.qmd | 2 +- README.md | 91 ++++++++++++++++++++++++++++++++++++-- README.qmd | 77 ++++++++++++++++++++++++++++++++ _metadata.yml | 3 ++ _quarto.yml | 18 +++++--- includes/_badges.qmd | 9 ++++ includes/_contributors.qmd | 3 ++ index.qmd | 16 +++++++ tools/get-contributors.sh | 20 +++++++++ 11 files changed, 287 insertions(+), 9 deletions(-) create mode 100644 .copier-answers.yml create mode 100644 .zenodo.json create mode 100644 README.qmd create mode 100644 _metadata.yml create mode 100644 includes/_badges.qmd create mode 100644 includes/_contributors.qmd create mode 100644 tools/get-contributors.sh diff --git a/.copier-answers.yml b/.copier-answers.yml new file mode 100644 index 0000000..1e7af1a --- /dev/null +++ b/.copier-answers.yml @@ -0,0 +1,11 @@ +# Changes here will be overwritten by Copier; NEVER EDIT MANUALLY +_commit: 0.17.10 +_src_path: gh:seedcase-project/template-website +author_family_name: Johnston +author_given_name: Luke +github_board_number: '18' +github_repo: guidebook +github_user: seedcase-project +hosting_provider: netlify +is_seedcase_website: true +review_team: '@seedcase-project/developers' diff --git a/.zenodo.json b/.zenodo.json new file mode 100644 index 0000000..c81385b --- /dev/null +++ b/.zenodo.json @@ -0,0 +1,46 @@ +{ + "creators": [ + { + "name": "Johnston, Luke", + "affiliation": "Steno Diabetes Center Aarhus", + "orcid": "https://orcid.org/0000-0003-4169-2616" + }, + { + "name": "Brødbæk, Signe Kirk", + "affiliation": "Steno Diabetes Center Aarhus", + "orcid": "https://orcid.org/0009-0000-2208-7088" + }, + { + "name": "Beicher, Kristiane", + "affiliation": "Steno Diabetes Center Aarhus", + "orcid": "https://orcid.org/0000-0001-7556-9566" + }, + { + "name": "Vago, Marton", + "affiliation": "Steno Diabetes Center Aarhus", + "orcid": "https://orcid.org/0009-0007-4628-655X" + } + ], + "title": "Guidebook to doing research software engineering in a team-setting", + "description": "This repository documents the practices, guidelines, and conventions that we've learned and applied that help us develop and release research software more effectively as solo developers and as a team. See our website at https://guidebook.seedcase-project.org/ for more details.", + "access_right": "open", + "related_identifiers": [ + { + "identifier": "https://github.com/seedcase-project/guidebook", + "relation": "isIdenticalTo", + "resource_type": "other" + } + ], + "keywords": [ + "quarto website", + "guidebook", + "research software engineering", + "teamwork", + "best practices", + "collaboration" + ], + "license": "cc-by-4.0", + "upload_type": "publication", + "publication_type": "other", + "language": "eng" +} diff --git a/404.qmd b/404.qmd index 9a29f89..817c6db 100644 --- a/404.qmd +++ b/404.qmd @@ -1,5 +1,5 @@ --- -title: "You’ve entered the garden of missing pages" +title: "You've entered the garden of missing pages" --- Let's get you back to greener grounds. diff --git a/README.md b/README.md index 13be4ac..eb1556a 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,90 @@ -# Guidebook -[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/seedcase-project/seedcase-sprout/main.svg)](https://results.pre-commit.ci/latest/github/seedcase-project/seedcase-sprout/main) -This repo is ... +# guidebook: Doing research software engineering in a team-setting + + + +[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true.svg)](https://github.com/copier-org/copier) +[![GitHub +License](https://img.shields.io/github/license/seedcase-project/guidebook.svg)](https://github.com/seedcase-project/guidebook/blob/main/LICENSE.md) +[![GitHub +Release](https://img.shields.io/github/v/release/seedcase-project/guidebook.svg)](https://github.com/seedcase-project/guidebook/releases/latest) +[![Build +website](https://github.com/seedcase-project/guidebook/actions/workflows/build-website.yml/badge.svg)](https://github.com/seedcase-project/guidebook/actions/workflows/build-website.yml) +[![pre-commit.ci +status](https://results.pre-commit.ci/badge/github/seedcase-project/guidebook/main.svg)](https://results.pre-commit.ci/latest/github/seedcase-project/guidebook/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: WIP – Initial development is in progress, but there +has not yet been a stable, usable release suitable for the +public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) + + +This repository documents the practices, guidelines, and conventions +that we’ve learned and applied that help us develop and release research +software more effectively as solo developers and as a team. + +> [!TIP] +> +> This website repository was generated from the +> [`template-website`](https://github.com/seedcase-project/template-website) +> Seedcase template :tada: + +## Project files and folders + +- `.copier-answers.yml`: Contains the answers you gave when copying the + project from the template. **You should not modify this file + directly.** +- `.cz.toml`: + [Commitizen](https://commitizen-tools.github.io/commitizen/) + configuration file for managing versions and changelogs. +- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/) + configuration file for managing and running checks before each commit. +- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell + checker configuration file. +- `.zenodo.json`: Structured citation metadata for your project when + archived on [Zenodo](https://zenodo.org/). This is used to add the + metadata to Zenodo when a GitHub release has been uploaded to Zenodo. +- `justfile`: [`just`](https://just.systems/man/en/) configuration file + for scripting project tasks. +- `.editorconfig`: Editor configuration file for + [EditorConfig](https://editorconfig.org/) to maintain consistent + coding styles across different editors and IDEs. +- `CHANGELOG.md`: Changelog file for tracking changes in the project. +- `CONTRIBUTING.md`: Guidelines for contributing to the project. +- `.github/`: Contains GitHub-specific files, such as issue and pull + request templates, workflows, + [dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide) + configuration, pull request templates, and a + [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) + file. +- `_metadata.yml`: Quarto metadata file for the website, including + information about the project, such as the titles and GitHub names. +- `_quarto.yml`: Quarto configuration file for the website, including + settings for the website, such as the theme, navigation, and other + options. + +## Contributing + +Check out our [contributing document](CONTRIBUTING.md) for information +on how to contribute to the project, including how to set up your +development environment. + +Please note that this project is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree +to abide by its terms. + +### Contributors + +The following people have contributed to this project by submitting pull +requests :tada: + +[@lwjohnst86](https://github.com/lwjohnst86), +[@signekb](https://github.com/signekb) + +## Licensing + +This project is licensed under the [CC-BY-4.0 License](LICENSE.md). + +## Changelog + +For a list of changes, see our [changelog](CHANGELOG.md) page. diff --git a/README.qmd b/README.qmd new file mode 100644 index 0000000..ca6d0ff --- /dev/null +++ b/README.qmd @@ -0,0 +1,77 @@ +--- +format: gfm +metadata-files: + - _metadata.yml +--- + +# {{< meta gh.repo >}}: Doing research software engineering in a team-setting + +{{< include /includes/_badges.qmd >}} + +This repository documents the practices, guidelines, and conventions +that we've learned and applied that help us develop and release research +software more effectively as solo developers and as a team. + +::: callout-tip +This website repository was generated from the +[`template-website`](https://github.com/seedcase-project/template-website) +Seedcase template :tada: +::: + +## Project files and folders + +- `.copier-answers.yml`: Contains the answers you gave when copying + the project from the template. **You should not modify this file + directly.** +- `.cz.toml`: + [Commitizen](https://commitizen-tools.github.io/commitizen/) + configuration file for managing versions and changelogs. +- `.pre-commit-config.yaml`: [Pre-commit](https://pre-commit.com/) + configuration file for managing and running checks before each + commit. +- `.typos.toml`: [typos](https://github.com/crate-ci/typos) spell + checker configuration file. +- `.zenodo.json`: Structured citation metadata for your project when + archived on [Zenodo](https://zenodo.org/). This is used to add the + metadata to Zenodo when a GitHub release has been uploaded to + Zenodo. +- `justfile`: [`just`](https://just.systems/man/en/) configuration + file for scripting project tasks. +- `.editorconfig`: Editor configuration file for + [EditorConfig](https://editorconfig.org/) to maintain consistent + coding styles across different editors and IDEs. +- `CHANGELOG.md`: Changelog file for tracking changes in the project. +- `CONTRIBUTING.md`: Guidelines for contributing to the project. +- `.github/`: Contains GitHub-specific files, such as issue and pull + request templates, workflows, + [dependabot](https://docs.github.com/en/code-security/getting-started/dependabot-quickstart-guide) + configuration, pull request templates, and a + [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) + file. +- `_metadata.yml`: Quarto metadata file for the website, including + information about the project, such as the titles and GitHub names. +- `_quarto.yml`: Quarto configuration file for the website, including + settings for the website, such as the theme, navigation, and other + options. + +## Contributing + +Check out our [contributing document](CONTRIBUTING.md) for information +on how to contribute to the project, including how to set up your +development environment. + +Please note that this project is released with a [Contributor Code of +Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree +to abide by its terms. + +### Contributors + +{{< include /includes/_contributors.qmd >}} + +## Licensing + +This project is licensed under the [CC-BY-4.0 License](LICENSE.md). + +## Changelog + +For a list of changes, see our [changelog](CHANGELOG.md) page. diff --git a/_metadata.yml b/_metadata.yml new file mode 100644 index 0000000..fd8af1b --- /dev/null +++ b/_metadata.yml @@ -0,0 +1,3 @@ +gh: + repo: guidebook + org: seedcase-project diff --git a/_quarto.yml b/_quarto.yml index 8602227..41dff3f 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -4,15 +4,23 @@ project: book: title: "Guidebook to doing research software engineering in a team-setting" - subtitle: "A living document for how we work in the Seedcase project" + subtitle: "A living document for how we work and build things in the Seedcase project" search: type: textbox favicon: _extensions/seedcase-project/seedcase-theme/favicon/favicon.ico author: - - "Luke W. Johnston" - - "Signe Kirk Brødbæk" - - "Kristiane Beicher" - - "Marton Vago" + - name: "Luke W. Johnston" + affiliation: "Steno Diabetes Center Aarhus" + orcid: "https://orcid.org/0000-0003-4169-2616" + - name: "Signe Kirk Brødbæk" + affiliation: "Steno Diabetes Center Aarhus" + orcid: "https://orcid.org/0009-0000-2208-7088" + - name: "Kristiane Beicher" + affiliation: "Steno Diabetes Center Aarhus" + orcid: "https://orcid.org/0000-0001-7556-9566" + - name: "Marton Vago" + affiliation: "Steno Diabetes Center Aarhus" + orcid: "https://orcid.org/0009-0007-4628-655X" date: last-modified repo-url: "https://github.com/seedcase-project/guidebook" site-url: "https://guidebook.seedcase-project.org/" diff --git a/includes/_badges.qmd b/includes/_badges.qmd new file mode 100644 index 0000000..3e0f68b --- /dev/null +++ b/includes/_badges.qmd @@ -0,0 +1,9 @@ + +[![Copier](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/copier-org/copier/master/img/badge/badge-grayscale-inverted-border-teal.json?raw=true.svg)](https://github.com/copier-org/copier) +[![GitHub License](https://img.shields.io/github/license/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/blob/main/LICENSE.md) +[![GitHub Release](https://img.shields.io/github/v/release/{{< meta gh.org >}}/{{< meta gh.repo >}}.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/releases/latest) +[![Build website](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/{{< meta gh.org >}}/{{< meta gh.repo >}}/actions/workflows/build-website.yml) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/{{< meta gh.org >}}/{{< meta gh.repo >}}/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip) + diff --git a/includes/_contributors.qmd b/includes/_contributors.qmd new file mode 100644 index 0000000..bf065da --- /dev/null +++ b/includes/_contributors.qmd @@ -0,0 +1,3 @@ +The following people have contributed to this project by submitting pull requests :tada: + + [\@lwjohnst86](https://github.com/lwjohnst86), [\@signekb](https://github.com/signekb) diff --git a/index.qmd b/index.qmd index ed436b8..8644101 100644 --- a/index.qmd +++ b/index.qmd @@ -1,5 +1,7 @@ # Welcome! +{{< include /includes/_badges.qmd >}} + Guidebook is about... ## Who you are as the reader @@ -11,3 +13,17 @@ think will read the documents: - **Research software/data engineers**: ... - **Managers or leaders**: ... - **Research or development operations personnel**: ... + +## Contributing + +Check out our [contributing document](CONTRIBUTING.md) for information +on how to contribute to the project. + +### Contributors + +{{< include /includes/_contributors.qmd >}} + +## Changes + +Check out our [changelog](CHANGELOG.md) for information on what has +changed in each version of the guidebook. diff --git a/tools/get-contributors.sh b/tools/get-contributors.sh new file mode 100644 index 0000000..7918505 --- /dev/null +++ b/tools/get-contributors.sh @@ -0,0 +1,20 @@ +#!/usr/bin/env bash + +# Get a list of contributors to this repository and save it to +# _contributors.qmd file (overwritten if it exists). It also: +# +# - Formats users into Markdown links to their GitHub profiles. +# - Removes any usernames with the word "bot" in them. +# - Removes the trailing comma from the list. +repo_spec=${1} +contributors=$(gh api \ + -H "Accept: application/vnd.github+json" \ + -H "X-GitHub-Api-Version: 2022-11-28" \ + /repos/$repo_spec/contributors \ + --template '{{range .}} [\@{{.login}}]({{.html_url}}){{"\n"}}{{end}}' | \ + grep -v "\[bot\]" | \ + tr '\n' ', ' | \ + sed -e 's/,$/\n/' +) + +echo "The following people have contributed to this project by submitting pull requests :tada:\n\n${contributors}"