From 1b972a994b70368166f9051b6a2347a01d5fe09b Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:26:09 +0200 Subject: [PATCH 01/19] ci: bump crate-ci/typos from 1.45.1 to 1.48.0 (#5) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/checks.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index ff752fd..8f3ccb2 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -19,7 +19,7 @@ jobs: uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 - name: Spell check repo - uses: crate-ci/typos@cf5f1c29a8ac336af8568821ec41919923b05a83 # v1.45.1 + uses: crate-ci/typos@bee27e3a4fd1ea2111cf90ab89cd076c870fce14 # v1.48.0 with: config: .config/typos.toml From 43fe903b692e884d81498e5bd64c69a45fd614bf Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:26:14 +0200 Subject: [PATCH 02/19] ci: bump astral-sh/setup-uv from 8.1.0 to 8.3.2 (#4) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9eebcdf..a98941e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -58,7 +58,7 @@ jobs: # Install uv to use git-cliff and rumdl - name: Set up uv - uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0 + uses: astral-sh/setup-uv@11f9893b081a58869d3b5fccaea48c9e9e46f990 # v8.3.2 with: enable-cache: true From 0f909ae2a68d8f726f176b710b870c44dcda7b8e Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:26:18 +0200 Subject: [PATCH 03/19] ci: bump step-security/harden-runner from 2.14.0 to 2.20.0 (#3) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/add-to-project.yml | 2 +- .github/workflows/build-website.yml | 2 +- .github/workflows/checks.yml | 6 +++--- .github/workflows/release.yml | 2 +- 4 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.github/workflows/add-to-project.yml b/.github/workflows/add-to-project.yml index b7f29fc..d743b3f 100644 --- a/.github/workflows/add-to-project.yml +++ b/.github/workflows/add-to-project.yml @@ -26,7 +26,7 @@ jobs: # This is a useful security step to check for unexpected outbound calls from the runner, # which could indicate a compromised token or runner. - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit diff --git a/.github/workflows/build-website.yml b/.github/workflows/build-website.yml index 81509e9..6ba426c 100644 --- a/.github/workflows/build-website.yml +++ b/.github/workflows/build-website.yml @@ -20,7 +20,7 @@ jobs: # This is a useful security step to check for unexpected outbound calls from the runner, # which could indicate a compromised token or runner. - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 8f3ccb2..71c29a2 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -11,7 +11,7 @@ jobs: # This is a useful security step to check for unexpected outbound calls from the runner, # which could indicate a compromised token or runner. - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit @@ -29,7 +29,7 @@ jobs: # This is a useful security step to check for unexpected outbound calls from the runner, # which could indicate a compromised token or runner. - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit @@ -55,7 +55,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@9af89fc71515a100421586dfdb3dc9c984fbf411 # v2.19.4 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a98941e..01f2c8b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -24,7 +24,7 @@ jobs: # This is a useful security step to check for unexpected outbound calls from the runner, # which could indicate a compromised token or runner. - name: Harden the runner (Audit all outbound calls) - uses: step-security/harden-runner@20cf305ff2072d973412fa9b1e3a4f227bda3c76 # v2.14.0 + uses: step-security/harden-runner@bf7454d06d71f1098171f2acdf0cd4708d7b5920 # v2.20.0 with: egress-policy: audit From a1387d6265eddea48930a5fc1c86e8c2c49c4d57 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:26:23 +0200 Subject: [PATCH 04/19] ci: bump actions/checkout from 6.0.2 to 7.0.0 (#2) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/build-website.yml | 2 +- .github/workflows/checks.yml | 6 +++--- .github/workflows/release.yml | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/build-website.yml b/.github/workflows/build-website.yml index 6ba426c..1fa0574 100644 --- a/.github/workflows/build-website.yml +++ b/.github/workflows/build-website.yml @@ -25,7 +25,7 @@ jobs: egress-policy: audit - name: Check out repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0 diff --git a/.github/workflows/checks.yml b/.github/workflows/checks.yml index 71c29a2..5f6ac2b 100644 --- a/.github/workflows/checks.yml +++ b/.github/workflows/checks.yml @@ -16,7 +16,7 @@ jobs: egress-policy: audit - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Spell check repo uses: crate-ci/typos@bee27e3a4fd1ea2111cf90ab89cd076c870fce14 # v1.48.0 @@ -34,7 +34,7 @@ jobs: egress-policy: audit - name: Checkout repository - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Set up Quarto uses: quarto-dev/quarto-actions/setup@8a96df13519ee81fd526f2dfca5962811136661b # v2.2.0 @@ -60,7 +60,7 @@ jobs: egress-policy: audit - name: "Checkout Repository" - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: "Dependency Review" uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294 # v5.0.0 diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 01f2c8b..959211e 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -38,7 +38,7 @@ jobs: private-key: ${{ secrets.UPDATE_VERSION_TOKEN }} - name: Checkout - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: # Only need the last commit from the repo. fetch-depth: 0 From 2b70f21b645685ec3bf019845ac17fb7dcaca6ff Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:26:28 +0200 Subject: [PATCH 05/19] ci: bump cocogitto/cocogitto-action from 4.1.0 to 4.2.0 (#1) Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 959211e..3a0c4bd 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -52,7 +52,7 @@ jobs: git config user.email "41898282+github-actions[bot]@users.noreply.github.com" - name: Install Cocogitto - uses: cocogitto/cocogitto-action@9a9fe03b31c47444290c0d7f9b1ee1b44ee13f20 # v4.1.0 + uses: cocogitto/cocogitto-action@52d0023b4396897f1815648e553db2ab8d782f3a # v4.2.0 with: command: check From 089c776792f2b3287063855796df4c1b49948038 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sat, 11 Jul 2026 16:48:10 +0200 Subject: [PATCH 06/19] =?UTF-8?q?chore:=20=F0=9F=99=88=20don't=20track=20Q?= =?UTF-8?q?uarto-generated=20`=5Ffiles/`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 8e7c3e8..76c7668 100644 --- a/.gitignore +++ b/.gitignore @@ -17,6 +17,7 @@ _temp/ /.quarto/ docs/.quarto/ **/*.quarto_ipynb +*_files/ # Website generation _site From d5b5a66e4fe1996fc54de36bfa85fec228e5c160 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sat, 11 Jul 2026 16:48:19 +0200 Subject: [PATCH 07/19] =?UTF-8?q?style:=20=F0=9F=8E=A8=20reformat=20Markdo?= =?UTF-8?q?wn?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 404.qmd | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/404.qmd b/404.qmd index 87ccc8c..f759668 100644 --- a/404.qmd +++ b/404.qmd @@ -6,6 +6,7 @@ Let's get you back to greener grounds. πŸ‘‰ Go to [homepage](/index.qmd). -![](/_extensions/seedcase-project/seedcase-theme/images/404.svg){fig-alt="An illustration of the number 404 surrounded by trees and mountains"} +![](/_extensions/seedcase-project/seedcase-theme/images/404.svg){fig-alt="An +illustration of the number 404 surrounded by trees and mountains"} ## Illustration by [Storyset](https://storyset.com/online) {.appendix} From 511051d75b75f8e9d244aa08ef5504ec5571efa8 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sat, 11 Jul 2026 16:48:38 +0200 Subject: [PATCH 08/19] =?UTF-8?q?build:=20=F0=9F=94=A8=20don't=20check=20`?= =?UTF-8?q?pre-commit.ci`=20URLs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- justfile | 1 + 1 file changed, 1 insertion(+) diff --git a/justfile b/justfile index 381b671..3fa6289 100644 --- a/justfile +++ b/justfile @@ -39,6 +39,7 @@ check-urls: --verbose \ --extensions md,qmd \ --exclude "github\.com" \ + --exclude "pre-commit\.ci" \ --exclude-path "_badges.qmd" # Format Markdown files From 79043c7bf57cabc1e219552727a63bd0af36002d Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sat, 11 Jul 2026 16:50:46 +0200 Subject: [PATCH 09/19] =?UTF-8?q?chore:=20=F0=9F=93=9D=20add=20`#sec-`=20l?= =?UTF-8?q?inks=20to=20empty=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/config.qmd | 2 +- docs/devex.qmd | 2 +- docs/docs.qmd | 2 +- docs/index.qmd | 2 +- docs/license.qmd | 2 +- docs/setup.qmd | 2 +- docs/testing.qmd | 2 +- docs/workflow.qmd | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/config.qmd b/docs/config.qmd index ef5aa80..659157a 100644 --- a/docs/config.qmd +++ b/docs/config.qmd @@ -1 +1 @@ -# Configurations +# Configurations {#sec-config} diff --git a/docs/devex.qmd b/docs/devex.qmd index 409dd9f..31bb6c0 100644 --- a/docs/devex.qmd +++ b/docs/devex.qmd @@ -1 +1 @@ -# Developer experience +# Developer experience {#sec-devex} diff --git a/docs/docs.qmd b/docs/docs.qmd index 25f8d45..4817893 100644 --- a/docs/docs.qmd +++ b/docs/docs.qmd @@ -1 +1 @@ -# Documentation +# Documentation {#sec-docs} diff --git a/docs/index.qmd b/docs/index.qmd index e10b99d..d66c6b2 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1 +1 @@ -# Introduction +# Introduction {#sec-intro} diff --git a/docs/license.qmd b/docs/license.qmd index cc3e074..cf1cc4b 100644 --- a/docs/license.qmd +++ b/docs/license.qmd @@ -1 +1 @@ -# License +# License {#sec-license} diff --git a/docs/setup.qmd b/docs/setup.qmd index feae8cb..e975ac2 100644 --- a/docs/setup.qmd +++ b/docs/setup.qmd @@ -1 +1 @@ -# Setup +# Setup {#sec-setup} diff --git a/docs/testing.qmd b/docs/testing.qmd index f00b526..0c939f3 100644 --- a/docs/testing.qmd +++ b/docs/testing.qmd @@ -1 +1 @@ -# Testing +# Testing {#sec-testing} diff --git a/docs/workflow.qmd b/docs/workflow.qmd index 93f5694..8afac9d 100644 --- a/docs/workflow.qmd +++ b/docs/workflow.qmd @@ -1 +1 @@ -# Overall workflow +# Overall workflow {#sec-workflow} From 249be83c2ac1b767d6c5d96262c464cb2614be8c Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 19:16:57 +0200 Subject: [PATCH 10/19] =?UTF-8?q?build:=20=F0=9F=94=A7=20update=20the=20ta?= =?UTF-8?q?gline=20to=20be=20more=20descriptive?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .zenodo.json | 11 ++++++----- README.md | 2 +- README.qmd | 2 +- _metadata.yml | 2 +- _quarto.yml | 3 ++- 5 files changed, 11 insertions(+), 9 deletions(-) diff --git a/.zenodo.json b/.zenodo.json index 84f12a8..e06ded3 100644 --- a/.zenodo.json +++ b/.zenodo.json @@ -6,8 +6,8 @@ "orcid": "https://orcid.org/0000-0003-4169-2616" } ], - "title": "Building data as a package", - "description": "The concept of a 'package' to bundle files together for easier management and distribution is a powerful way of approaching building products. This also applies to developing FAIR (findable, accessible, interoperable, and reusable) data and metadata. In this guide, we walk through how to build data up as a package, including how to organize files and folders, how to create and run a pipeline to take raw data into the final form, and how to bundle everything together into a versioned and released package.", + "title": "Building data packages: A guide to engineering and developing research data as FAIR and tidy data packages", + "description": "The concept of a 'package' to bundle files together for easier management and distribution is a powerful way of approaching building products and is common in all programming languages. This also applies to developing FAIR (findable, accessible, interoperable, and reusable) data and metadata. In this guide, we walk through how to build data up as a package, including how to organize files and folders, how to create and run a pipeline to take raw data into the final form, and how to bundle everything together into a versioned and released package.", "access_right": "open", "related_identifiers": [ { @@ -23,15 +23,16 @@ ], "keywords": [ "guide", + "walkthrough", "how-to", "research data engineering", "data engineering", "data packages", + "data package", + "data development", "best practices", "collaboration", - "workflows", - "data package", - "data development" + "workflows" ], "communities": [ { diff --git a/README.md b/README.md index c89036d..8bf0cf4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# data-pkg-guide: Building Data as a Package +# A guide to engineering and developing research data as a FAIR and tidy data package diff --git a/README.qmd b/README.qmd index d8a0986..ff93f81 100644 --- a/README.qmd +++ b/README.qmd @@ -4,7 +4,7 @@ metadata-files: - _metadata.yml --- -# {{< meta gh.repo >}}: {{< meta tagline >}} +# {{< meta tagline >}} {{< include /includes/_badges.qmd >}} diff --git a/_metadata.yml b/_metadata.yml index 2c61934..18eb706 100644 --- a/_metadata.yml +++ b/_metadata.yml @@ -2,7 +2,7 @@ gh: org: seedcase-project repo: data-pkg-guide -tagline: "Building Data as a Package" +tagline: "A guide to engineering and developing research data as a FAIR and tidy data package" links: github: "https://github.com/seedcase-project/data-pkg-guide" diff --git a/_quarto.yml b/_quarto.yml index 86f4d29..c655608 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -2,7 +2,8 @@ project: type: book book: - title: "Building Data as a Package" + title: "Building Data Packages" + subtitle: "A guide to engineering and developing research data as a FAIR and tidy data package" repo-branch: main repo-actions: [issue, edit, source] downloads: [pdf] From 19cd9fdfa50a795bd11481eb34254280d5b83737 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 20:45:13 +0200 Subject: [PATCH 11/19] =?UTF-8?q?build:=20=F0=9F=94=A7=20move=20Tools=20se?= =?UTF-8?q?ction=20down=20in=20`=5Fquarto.yml`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _quarto.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_quarto.yml b/_quarto.yml index c655608..db291da 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -30,7 +30,6 @@ book: - part: "Overview" chapters: - docs/index.qmd - - docs/tools.qmd - docs/layout.qmd - docs/workflow.qmd - part: "Files and folders" @@ -49,6 +48,7 @@ book: - docs/release.qmd - part: "Development" chapters: + - docs/tools.qmd - docs/setup.qmd - docs/testing.qmd - docs/devex.qmd From 4f899bdaa95f584f9604095d58b9dd00ff44caf0 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 20:51:44 +0200 Subject: [PATCH 12/19] =?UTF-8?q?build:=20=F0=9F=94=A7=20don't=20check=20f?= =?UTF-8?q?or=20merge=20commits=20during=20release?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .config/cog.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/.config/cog.toml b/.config/cog.toml index a1bd9c5..38c205e 100644 --- a/.config/cog.toml +++ b/.config/cog.toml @@ -1,6 +1,7 @@ from_latest_tag = true disable_changelog = true disable_bump_commit = true +ignore_merge_commits = true branch_whitelist = ["main"] pre_bump_hooks = [ # Quiet the log output of git-cliff, it is noisy. From 0882a72441bf27a24c3cc80a608641aa3fc88fab Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 20:55:52 +0200 Subject: [PATCH 13/19] =?UTF-8?q?ci:=20=F0=9F=91=B7=20add=20missing=20path?= =?UTF-8?q?=20to=20`cog.toml`=20in=20`release.yml`=20workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3a0c4bd..84934dc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -55,6 +55,7 @@ jobs: uses: cocogitto/cocogitto-action@52d0023b4396897f1815648e553db2ab8d782f3a # v4.2.0 with: command: check + args: --config .config/cog.toml # Install uv to use git-cliff and rumdl - name: Set up uv From 15808a8c0164c1d6d04b66b68ebf4876a23eab6b Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 20:57:21 +0200 Subject: [PATCH 14/19] =?UTF-8?q?ci:=20=F0=9F=91=B7=20fix=20arg=20to=20pas?= =?UTF-8?q?s=20`--config`=20correctly=20in=20`cog=20check`=20workflow?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 84934dc..968a17a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -55,7 +55,7 @@ jobs: uses: cocogitto/cocogitto-action@52d0023b4396897f1815648e553db2ab8d782f3a # v4.2.0 with: command: check - args: --config .config/cog.toml + args: "-- --config .config/cog.toml" # Install uv to use git-cliff and rumdl - name: Set up uv From 1bfc357e70b306d4a487d20c3455e5f603cfde25 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Sun, 12 Jul 2026 20:59:33 +0200 Subject: [PATCH 15/19] =?UTF-8?q?ci:=20=F0=9F=91=B7=20ignore=20merge=20com?= =?UTF-8?q?mits=20with=20`cog=20check`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 968a17a..5fa5361 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -55,7 +55,7 @@ jobs: uses: cocogitto/cocogitto-action@52d0023b4396897f1815648e553db2ab8d782f3a # v4.2.0 with: command: check - args: "-- --config .config/cog.toml" + args: "--ignore-merge-commits" # Install uv to use git-cliff and rumdl - name: Set up uv From 95da8d378b5a18d91fe7e38a6d3c64fb74b72b8c Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 13 Jul 2026 12:15:53 +0200 Subject: [PATCH 16/19] =?UTF-8?q?feat:=20=E2=9C=A8=20add=20Layout=20chapte?= =?UTF-8?q?r=20for=20structure=20of=20package?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/layout.qmd | 503 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 503 insertions(+) diff --git a/docs/layout.qmd b/docs/layout.qmd index 66ce05b..cf0f17b 100644 --- a/docs/layout.qmd +++ b/docs/layout.qmd @@ -1 +1,504 @@ # Package layout {#sec-layout} + +Like R, Python, Rust, or any other package, a data package needs to have a +specific layout and naming of the files and directories within the package. If +it doesn't have these, it isn't a package. In this chapter we'll do an overview +of what the structure of a data package is, what the files and directories are +for, and which chapters in this book cover more details about each. Each section +in this chapter will cover a specific directory in the package. For details +about the different tools we mention in this chapter, see @sec-tools. + +While the specific programming language doesn't *strictly* matter, we [recommend +using +Python](https://decisions.seedcase-project.org/why-python-for-data-engineering/) +for developing data packages. For this book, we'll use Python in the guide, +which means that some files and directories will be specific to Python projects. + +::: callout-tip +As we learn about and refine how to build data packages, we may include sections +on using R or Rust for building data packages. +::: + +## Root directory + +The root directory, which is the top-level directory of the package and named +after the package itself (``), requires certain files and +directories to be present. There are only two optional directories: `.github/` +and `requests/`. See @sec-setup for more information about creating this project +structure and what recommended files should be in the `<...>` placeholders in +the tree below. + +```text +/ +β”œβ”€β”€ .github/ # Optional +β”œβ”€β”€ .config/ +β”œβ”€β”€ src/ +β”œβ”€β”€ raw/ +β”œβ”€β”€ staging/ +β”œβ”€β”€ resources/ +β”œβ”€β”€ releases/ +β”œβ”€β”€ requests/ # Optional +β”œβ”€β”€ docs/ +β”œβ”€β”€ . +β”œβ”€β”€ pyproject.toml +β”œβ”€β”€ README.md +β”œβ”€β”€ LICENSE.md +β”œβ”€β”€ CHANGELOG.md +β”œβ”€β”€ +└── +``` + +We'll go over each directory below in individual sections, so we'll only +describe the `<...>` files in the next subsections. + +::: callout-important +A data package can have many more and different files and directories than those +listed above, however these are only the required and/or common files and +directories to effectively develop a data package. +::: + +::: content-hidden +The tree above was created using the below with this website +: + +```text +/ + .github/ + .config/ + src/ + raw/ + staging/ + resources/ + releases/ + requests/ + docs/ + . + pyproject.toml + README.md + LICENSE.md + CHANGELOG.md + + +``` +::: + +### `.` + +This is the metadata file for the package, which contains metadata about the +package itself as well as the data contained within it. The format and extension +will depend on the specific metadata standard being used. For example, a +`datapackage.json` file for the [Data Package](https://datapackage.org). While +`datapackage.json` shares the name with "data package", they are not the same +thing. The Data Package Standard (or specification) is a structured format to +storing metadata about data, but is not involved in how the data package itself +is built and developed. This file is covered in more detail in @sec-metadata. + +### `pyproject.toml` + +This contains the Python project configuration for the package, such as package +dependencies, name, authors, version, and other metadata. This file is required +for Python packages, which a data package is structured as to take advantage of +Python packaging tools and workflows. In @sec-src and @sec-config we'll describe +this file more and how to use it. + +### `README.md`, `LICENSE.md`, and `CHANGELOG.md` + +These are common files that are found in many open source projects, especially +in software projects. + +- The `README.md` file, as it name suggests, is the main file any person should + read when first checking out the project. + +- The `LICENSE.md` file contains the license for the project, which is required + in order for other people to use the project. In @sec-license we describe how + to choose a license for your project, as data packages require different + licensing compared to code or text. + +- The `CHANGELOG.md` file contains a list of changes made to the project within + each version update, which can be useful for users of the data package to + learn what things changed in specific versions. This file is covered in more + detail in @sec-build and @sec-release, as it is part of the release process + for the data package. + +### `` + +These are configuration files that may be required for the package, such as +`.gitignore`, `.editorconfig`, or `.zenodo.json`/`CITATION.cff` that are used +mostly by external tools (for those that can't store the config files in +`.config/`). We go over different types of config files that we recommend when +developing and releasing a data package in @sec-config and @sec-devex. + +### `` + +These are files related building various aspects of the data package. The main +build file is `justfile`, which is used to manage all the different build steps. +Other build-type files include `_quarto.yml` for building the website. We go +over some of these files in @sec-build related to the build process and in +@sec-docs for building the website. + +## `src/` Python code + +Aside from the `pyproject.toml` file, the `src/` directory is where all the +Python and other build-related source files are kept. The structure of this +directory resembles a Python package, with several `__init__.py` files to inform +Python that they should be treated as part of the Python project. While we go +over the `src/` directory in more detail in @sec-src, the general structure of +this directory is shown below. + +```text +src/ +└── / + β”œβ”€β”€ / + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ core.py + β”‚ └── / + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ .py + β”‚ └── core.py + β”œβ”€β”€ / + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ core.py + β”‚ └── / + β”‚ β”œβ”€β”€ __init__.py + β”‚ β”œβ”€β”€ .py + β”‚ └── core.py + β”œβ”€β”€ common/ + β”‚ └── __init__.py + β”œβ”€β”€ __init__.py + └── build.py +``` + +- The `` is the name of the Python package that is used to build + the data package, which is usually the same as the name of the data package + itself (using `_` instead of `-`). +- The `` and `` directories contain the Python code for + processing the metadata and data, respectively. +- The `` and `` directories are used to organize the + Python code by the source of the data and the eventual resource name. +- The `common/` directory contains Python code that is used across all sources + and resources. +- The `build.py` file contains the build tasks that are used to build the data + package. +- The `core.py` files within the subdirectories contain functions that are used + across specific sources and/or resources. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +src/ + / + / + __init__.py + core.py + / + __init__.py + .py + core.py + / + __init__.py + core.py + / + __init__.py + .py + core.py + common/ + __init__.py + __init__.py + build.py +``` +::: + +## `raw/` data + +The `raw/` folder contains the original (unprocessed) data files from their +original source locations (e.g. database or +[ftp](https://en.wikipedia.org/wiki/File_Transfer_Protocol) server) that will be +processed and built into the data package. We strongly recommend that the data +in `raw/` is not modified in any way, aside from renaming the files and +compressing them for storage purposes. Keeping them unprocessed and unmodified +ensures a clear and reproducible history of how the data was built into the data +package. We go over the `raw/` directory in @sec-raw and @sec-src. The general +structure of the `raw/` directory is shown below. + +```text +raw/ +└── / + β”œβ”€β”€ . + └── / + └── . # For, e.g., image files +``` + +Raw data is organised into directories by the source of the data +(``), for example, from [REDCap](https://www.project-redcap.org/) +as `redcap` or [Garmin wearables](https://www.garmin.com/en-US/) as `garmin`. +Within each source, the data is saved to files or directories with the timestamp +of when the data was downloaded from the source as its name. The timestamp is in +the ISO 8601 format (`YYYY-MM-DDTHH:MM:SSZ`), which is a standard format for +representing date and time. The details of whether to save to a file or +directory are covered in @sec-raw. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +raw/ + / + . + / + . # For, e.g., image files +``` +::: + +## `staging/` data + +Data in `staging/` is all the data in `raw/` that has been processed and +cleaned. There should be a one-to-one mapping between the timestamped files in +`raw/` and the timestamped files in `staging/`. This ensures that the data in +`staging/` is reproducible and traceable back to the original data in `raw/`, +and to allow parallel processing of the files from `raw/` to `staging/`. Staging +is necessary as it gets the data ready to be in the correct format to be used +and can allow metadata to be extracted, if needed, from prepared data rather +than from raw data. We go over the `staging/` directory in @sec-staging as well +as partially in @sec-build. The general structure of the `staging/` directory is +shown below. + +```text +staging/ +β”œβ”€β”€ .gitignore # Don't track staging data +└── / + └── / + β”œβ”€β”€ / + β”‚ └── . # For, e.g., image files + └── .parquet +``` + +The three differences from `raw/` are that the data: + +- Is saved as a [Parquet](https://parquet.apache.org/) file +- Is organised into directories by the eventual resource name + (``) that the data will be built into. A resource is a single + conceptual dataset that has some meaning to the researchers and/or users of + the data package. For example, the `redcap` source may have a resource called + `demographics` that contains the demographic data from the REDCap database + such as age, gender, and date of birth. +- Not tracked by Git, as the `raw/` data will already be tracked (during release + only), so downstream files don't need to be tracked as well. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +staging/ + .gitignore # Don't track staging data + / + / + / + . # For, e.g., image files + .parquet +``` +::: + +## `resources/` data + +```text +resources/ +β”œβ”€β”€ .gitignore # Don't track resources data +β”œβ”€β”€ .parquet +β”œβ”€β”€ / +β”‚ └── / +β”‚ └── . # For, e.g., image files +└── / + └── / + └── part-.parquet +``` + +::: content-hidden +The tree above was created using the below with this website +: + +```text +resources/ + .gitignore # Don't track resources data + .parquet + / + / + . # For, e.g., image files + / + / + part-.parquet +``` +::: + +## `releases/` build artifacts + +```text +releases/ +β”œβ”€β”€ .gitignore # Don't track releases +β”œβ”€β”€ _.tar +└── _.zip +``` + +::: content-hidden +The tree above was created using the below with this website +: + +```text +releases/ + .gitignore # Don't track releases + _.tar + _.zip +``` +::: + +## `docs/` documentation + +This directory contains the documentation for the data package. Not only is it +for showing the metadata in a human-friendly way, but also to document details +about the package itself, how it was made, and any contributing or operational +details. It can also contain information about who uses the data and how it is +being used (e.g. based on the content in `requests/`). We strongly recommend +that this documentation be built into a website, using a tool like +[Quarto](https://quarto.org/). Since it will be built into a website, some files +are required to be present in the `docs/` directory, such as `index.qmd` files. +Of the directories described in this chapter, this is the only one that has no +specific structure to follow. A basic structure for `docs/` might look like the +following (if rendering the metadata into the website): + +```text +docs/ +β”œβ”€β”€ index.qmd +└── metadata/ + β”œβ”€β”€ index.qmd + └── .qmd +``` + +The `metadata/` directory would contain the converted metadata from +machine-readable to human-readable using our tool +[Flower](https://flower.seedcase-project.org). Other than that, you are free to +organise the documentation in any way that makes sense for the website for the +data package. We'll cover documentation in @sec-docs. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +docs/ + index.qmd + metadata/ + index.qmd + .qmd +``` +::: + +## `requests/` documentation + +This directory contains any requests that data package owners receive for +obtaining subsets of the data package. These requests are created from our tool +[Propagate](https://propagate.seedcase-project.org/) and are stored in the +`requests/` directory. Each individual request also contains the data subset, +though it isn't tracked by Git. The structure of this directory is shown below. +We go over requests in @sec-requests and subsets in @sec-subsets. See +[Propagate](https://propagate.seedcase-project.org/) for more details on how to +make requests and subset data. + +```text +requests/ +└── / + β”œβ”€β”€ request.yaml + └── subset/ + β”œβ”€β”€ .gitignore # Don't track subset data + └── -.tar +``` + +The `` is the name of the research project that someone is doing, +and who wants to use a subset of the data package for that project. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +requests/ + / + request.yaml + subset/ + .gitignore # Don't track subset data + -.tar +``` +::: + +## `.github/` + +This directory may not exist if you don't develop the data package on GitHub (or +a similar service). We strongly recommend that you do, as it allows for much +easier collaboration and development of the data package. It also makes it +easier to build, release, and publish (at the minimal, just the metadata) the +data package. Other services (like Codeberg or GitLab) have similar features to +GitHub. But because GitHub is so widely used and popular, we focus on using it +in this book. We cover this directory in @sec-ci, @sec-devex, and partially in +@sec-release. The structure of this directory is shown below: + +```text +.github/ +β”œβ”€β”€ workflows/ +β”‚ β”œβ”€β”€ checks.yml +β”‚ β”œβ”€β”€ build-website.yml +β”‚ └── release.yml # Optional +└── +``` + +The `workflows/` directory contains the GitHub Actions workflows that are used +to build, check, and (optionally) release the data package. If the data is +subject to any legal or privacy restrictions, the `release.yml` workflow won't +be used. The `` are any other files that GitHub may use and that +are helpful to development, such as the `CODEOWNERS` file. + +::: content-hidden +The tree above was created using the below with this website +: + +```text +.github/ + workflows/ + checks.yml + build-website.yml + release.yml # Optional + +``` +::: + +## `.config/` + +This directory contains all the configuration files used for developing, +maintaining, managing, building, and releasing the data package. For example, +since we recommend using +[Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/) +and +[git-cliff](https://decisions.seedcase-project.org/why-changelog-with-git-cliff/) +for the release process, the configuration files for those tools will be kept in +this directory. Keeping them in this directory keeps the root directory cleaner +and organises the configuration files in one place. It also follows the XDG +[`.config/`](https://dot-config.github.io) specification. We go over the +`.config/` directory in several sections, such as @sec-devex and @sec-config. +The directory structure is pretty simple, as it is a flat (non-nested) directory +with only configuration files: + +```text +.config/ +└── +``` + +::: content-hidden +The tree above was created using the below with this website +: + +```text +.config/ + +``` +::: From 35cb13230cea7f6ea9d8d7fd6d73290c70ed9ddc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 14 Jul 2026 12:27:58 +0000 Subject: [PATCH 17/19] =?UTF-8?q?chore:=20=E2=9C=8F=EF=B8=8F=20automatic?= =?UTF-8?q?=20pre-commit=20hook=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- index.qmd | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/index.qmd b/index.qmd index 49bb6b8..45d88a4 100644 --- a/index.qmd +++ b/index.qmd @@ -28,9 +28,9 @@ the software package development cycle so that the final "data package" (or This guide mostly follows the [diΓ‘taxis](https://diataxis.fr/how-to-guides/) "how-to guide" style, though not strictly. It is a living and constantly evolving guide that is regularly updated as we learn and refine how we work and -develop data packages. We intend to continually update and release it with -every update to Zenodo and as GitHub releases. We don't expect this guide to -ever be considered "done". +develop data packages. We intend to continually update and release it with every +update to Zenodo and as GitHub releases. We don't expect this guide to ever be +considered "done". ::: ## Who you are @@ -67,8 +67,8 @@ the GitHub repository. ::: content-hidden -The PDF version of the guide is available in the releases page, as well as -the Zenodo archive. +The PDF version of the guide is available in the releases page, as well as the +Zenodo archive. ::: ## How the website is made From 7ff0a0520cbe72c73d7ab932ad631e2668de70cc Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Tue, 14 Jul 2026 15:07:52 +0200 Subject: [PATCH 18/19] refactor: :pencil2: edits from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Signe Kirk BrΓΈdbΓ¦k <40836345+signekb@users.noreply.github.com> --- docs/layout.qmd | 73 ++++++++++++++++++++++++------------------------- 1 file changed, 36 insertions(+), 37 deletions(-) diff --git a/docs/layout.qmd b/docs/layout.qmd index cf0f17b..8650893 100644 --- a/docs/layout.qmd +++ b/docs/layout.qmd @@ -1,10 +1,10 @@ # Package layout {#sec-layout} -Like R, Python, Rust, or any other package, a data package needs to have a -specific layout and naming of the files and directories within the package. If -it doesn't have these, it isn't a package. In this chapter we'll do an overview -of what the structure of a data package is, what the files and directories are -for, and which chapters in this book cover more details about each. Each section +Like R, Python, Rust, or any other package, a data package must follow a +specific directory and file layout and naming convention. If +it doesn't follow these, it isn't a package. In this chapter, we'll provide an overview +of the data package structure, its files and directories, +and which chapters in this book cover each of these in detail. Each section in this chapter will cover a specific directory in the package. For details about the different tools we mention in this chapter, see @sec-tools. @@ -14,15 +14,15 @@ Python](https://decisions.seedcase-project.org/why-python-for-data-engineering/) for developing data packages. For this book, we'll use Python in the guide, which means that some files and directories will be specific to Python projects. -::: callout-tip +::: callout-note As we learn about and refine how to build data packages, we may include sections on using R or Rust for building data packages. ::: ## Root directory -The root directory, which is the top-level directory of the package and named -after the package itself (``), requires certain files and +The root directory, which is the top-level directory of the package, should be named +after the package itself (``). This directory requires certain files and directories to be present. There are only two optional directories: `.github/` and `requests/`. See @sec-setup for more information about creating this project structure and what recommended files should be in the `<...>` placeholders in @@ -106,11 +106,11 @@ this file more and how to use it. These are common files that are found in many open source projects, especially in software projects. -- The `README.md` file, as it name suggests, is the main file any person should - read when first checking out the project. +- The `README.md` file, as it name suggests, is the first file any person should + read when checking out the project. - The `LICENSE.md` file contains the license for the project, which is required - in order for other people to use the project. In @sec-license we describe how + in order for other people to use the project. In @sec-license, we describe how to choose a license for your project, as data packages require different licensing compared to code or text. @@ -130,9 +130,9 @@ developing and releasing a data package in @sec-config and @sec-devex. ### `` -These are files related building various aspects of the data package. The main +These are files related to building various aspects of the data package. The main build file is `justfile`, which is used to manage all the different build steps. -Other build-type files include `_quarto.yml` for building the website. We go +Other build-type files include `_quarto.yml` for building a website for the data package. We go over some of these files in @sec-build related to the build process and in @sec-docs for building the website. @@ -175,7 +175,7 @@ src/ processing the metadata and data, respectively. - The `` and `` directories are used to organize the Python code by the source of the data and the eventual resource name. -- The `common/` directory contains Python code that is used across all sources +- The `common/` directory contains Python code that is used across multiple sources and resources. - The `build.py` file contains the build tasks that are used to build the data package. @@ -259,7 +259,7 @@ cleaned. There should be a one-to-one mapping between the timestamped files in `raw/` and the timestamped files in `staging/`. This ensures that the data in `staging/` is reproducible and traceable back to the original data in `raw/`, and to allow parallel processing of the files from `raw/` to `staging/`. Staging -is necessary as it gets the data ready to be in the correct format to be used +is necessary as it gets the data ready to be in the correct format to be included as a data resource and can allow metadata to be extracted, if needed, from prepared data rather than from raw data. We go over the `staging/` directory in @sec-staging as well as partially in @sec-build. The general structure of the `staging/` directory is @@ -275,17 +275,17 @@ staging/ └── .parquet ``` -The three differences from `raw/` are that the data: +The three differences from `raw/` are that the data in `staging/` is: -- Is saved as a [Parquet](https://parquet.apache.org/) file -- Is organised into directories by the eventual resource name +- Saved as a [Parquet](https://parquet.apache.org/) file. +- Organised into directories by the eventual resource name (``) that the data will be built into. A resource is a single conceptual dataset that has some meaning to the researchers and/or users of the data package. For example, the `redcap` source may have a resource called `demographics` that contains the demographic data from the REDCap database such as age, gender, and date of birth. - Not tracked by Git, as the `raw/` data will already be tracked (during release - only), so downstream files don't need to be tracked as well. + only), so downstream files in `staging/` don't need to be tracked as well. ::: content-hidden The tree above was created using the below with this website @@ -309,8 +309,7 @@ resources/ β”œβ”€β”€ .gitignore # Don't track resources data β”œβ”€β”€ .parquet β”œβ”€β”€ / -β”‚ └── / -β”‚ └── . # For, e.g., image files +β”‚ └── . # For, e.g., image files └── / └── / └── part-.parquet @@ -356,13 +355,13 @@ releases/ ## `docs/` documentation -This directory contains the documentation for the data package. Not only is it -for showing the metadata in a human-friendly way, but also to document details +This directory contains the documentation for the data package. It is not only +for showing the metadata in a human-friendly way, but also for documenting details about the package itself, how it was made, and any contributing or operational details. It can also contain information about who uses the data and how it is being used (e.g. based on the content in `requests/`). We strongly recommend -that this documentation be built into a website, using a tool like -[Quarto](https://quarto.org/). Since it will be built into a website, some files +that this documentation is built into a website, using a tool like +[Quarto](https://quarto.org/). If it is published as a website, some files are required to be present in the `docs/` directory, such as `index.qmd` files. Of the directories described in this chapter, this is the only one that has no specific structure to follow. A basic structure for `docs/` might look like the @@ -377,9 +376,9 @@ docs/ ``` The `metadata/` directory would contain the converted metadata from -machine-readable to human-readable using our tool +machine-readable to human-readable, e.g., using our tool [Flower](https://flower.seedcase-project.org). Other than that, you are free to -organise the documentation in any way that makes sense for the website for the +organise the documentation in any way that makes sense for your data package. We'll cover documentation in @sec-docs. ::: content-hidden @@ -395,7 +394,7 @@ docs/ ``` ::: -## `requests/` documentation +## `requests/` documentation (optional) This directory contains any requests that data package owners receive for obtaining subsets of the data package. These requests are created from our tool @@ -432,14 +431,14 @@ requests/ ``` ::: -## `.github/` +## `.github/` (optional) This directory may not exist if you don't develop the data package on GitHub (or a similar service). We strongly recommend that you do, as it allows for much easier collaboration and development of the data package. It also makes it -easier to build, release, and publish (at the minimal, just the metadata) the -data package. Other services (like Codeberg or GitLab) have similar features to -GitHub. But because GitHub is so widely used and popular, we focus on using it +easier to build, release, and publish the +data package, even if only the metadata is published. Other services (like Codeberg or GitLab) have similar features to +GitHub, but because GitHub is so widely used and popular, we focus on using it in this book. We cover this directory in @sec-ci, @sec-devex, and partially in @sec-release. The structure of this directory is shown below: @@ -456,7 +455,7 @@ The `workflows/` directory contains the GitHub Actions workflows that are used to build, check, and (optionally) release the data package. If the data is subject to any legal or privacy restrictions, the `release.yml` workflow won't be used. The `` are any other files that GitHub may use and that -are helpful to development, such as the `CODEOWNERS` file. +are helpful to development, such as a `CODEOWNERS` file. ::: content-hidden The tree above was created using the below with this website @@ -474,14 +473,14 @@ The tree above was created using the below with this website ## `.config/` -This directory contains all the configuration files used for developing, -maintaining, managing, building, and releasing the data package. For example, +This directory contains all the configuration files used for +the data package. For example, since we recommend using [Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/) and [git-cliff](https://decisions.seedcase-project.org/why-changelog-with-git-cliff/) -for the release process, the configuration files for those tools will be kept in -this directory. Keeping them in this directory keeps the root directory cleaner +for the release process, the configuration files for those tools should be kept in +this directory. Storing them in this directory keeps the root directory cleaner and organises the configuration files in one place. It also follows the XDG [`.config/`](https://dot-config.github.io) specification. We go over the `.config/` directory in several sections, such as @sec-devex and @sec-config. From 93b6fb1f8caaf580c53420b1e89dbc1cd49e2510 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 14 Jul 2026 13:09:01 +0000 Subject: [PATCH 19/19] =?UTF-8?q?chore:=20=E2=9C=8F=EF=B8=8F=20automatic?= =?UTF-8?q?=20pre-commit=20hook=20fixes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/layout.qmd | 103 ++++++++++++++++++++++++------------------------ 1 file changed, 51 insertions(+), 52 deletions(-) diff --git a/docs/layout.qmd b/docs/layout.qmd index 8650893..e05f1da 100644 --- a/docs/layout.qmd +++ b/docs/layout.qmd @@ -1,12 +1,12 @@ # Package layout {#sec-layout} Like R, Python, Rust, or any other package, a data package must follow a -specific directory and file layout and naming convention. If -it doesn't follow these, it isn't a package. In this chapter, we'll provide an overview -of the data package structure, its files and directories, -and which chapters in this book cover each of these in detail. Each section -in this chapter will cover a specific directory in the package. For details -about the different tools we mention in this chapter, see @sec-tools. +specific directory and file layout and naming convention. If it doesn't follow +these, it isn't a package. In this chapter, we'll provide an overview of the +data package structure, its files and directories, and which chapters in this +book cover each of these in detail. Each section in this chapter will cover a +specific directory in the package. For details about the different tools we +mention in this chapter, see @sec-tools. While the specific programming language doesn't *strictly* matter, we [recommend using @@ -21,12 +21,12 @@ on using R or Rust for building data packages. ## Root directory -The root directory, which is the top-level directory of the package, should be named -after the package itself (``). This directory requires certain files and -directories to be present. There are only two optional directories: `.github/` -and `requests/`. See @sec-setup for more information about creating this project -structure and what recommended files should be in the `<...>` placeholders in -the tree below. +The root directory, which is the top-level directory of the package, should be +named after the package itself (``). This directory requires +certain files and directories to be present. There are only two optional +directories: `.github/` and `requests/`. See @sec-setup for more information +about creating this project structure and what recommended files should be in +the `<...>` placeholders in the tree below. ```text / @@ -130,11 +130,11 @@ developing and releasing a data package in @sec-config and @sec-devex. ### `` -These are files related to building various aspects of the data package. The main -build file is `justfile`, which is used to manage all the different build steps. -Other build-type files include `_quarto.yml` for building a website for the data package. We go -over some of these files in @sec-build related to the build process and in -@sec-docs for building the website. +These are files related to building various aspects of the data package. The +main build file is `justfile`, which is used to manage all the different build +steps. Other build-type files include `_quarto.yml` for building a website for +the data package. We go over some of these files in @sec-build related to the +build process and in @sec-docs for building the website. ## `src/` Python code @@ -175,8 +175,8 @@ src/ processing the metadata and data, respectively. - The `` and `` directories are used to organize the Python code by the source of the data and the eventual resource name. -- The `common/` directory contains Python code that is used across multiple sources - and resources. +- The `common/` directory contains Python code that is used across multiple + sources and resources. - The `build.py` file contains the build tasks that are used to build the data package. - The `core.py` files within the subdirectories contain functions that are used @@ -259,11 +259,11 @@ cleaned. There should be a one-to-one mapping between the timestamped files in `raw/` and the timestamped files in `staging/`. This ensures that the data in `staging/` is reproducible and traceable back to the original data in `raw/`, and to allow parallel processing of the files from `raw/` to `staging/`. Staging -is necessary as it gets the data ready to be in the correct format to be included as a data resource -and can allow metadata to be extracted, if needed, from prepared data rather -than from raw data. We go over the `staging/` directory in @sec-staging as well -as partially in @sec-build. The general structure of the `staging/` directory is -shown below. +is necessary as it gets the data ready to be in the correct format to be +included as a data resource and can allow metadata to be extracted, if needed, +from prepared data rather than from raw data. We go over the `staging/` +directory in @sec-staging as well as partially in @sec-build. The general +structure of the `staging/` directory is shown below. ```text staging/ @@ -278,12 +278,12 @@ staging/ The three differences from `raw/` are that the data in `staging/` is: - Saved as a [Parquet](https://parquet.apache.org/) file. -- Organised into directories by the eventual resource name - (``) that the data will be built into. A resource is a single - conceptual dataset that has some meaning to the researchers and/or users of - the data package. For example, the `redcap` source may have a resource called - `demographics` that contains the demographic data from the REDCap database - such as age, gender, and date of birth. +- Organised into directories by the eventual resource name (``) + that the data will be built into. A resource is a single conceptual dataset + that has some meaning to the researchers and/or users of the data package. For + example, the `redcap` source may have a resource called `demographics` that + contains the demographic data from the REDCap database such as age, gender, + and date of birth. - Not tracked by Git, as the `raw/` data will already be tracked (during release only), so downstream files in `staging/` don't need to be tracked as well. @@ -356,14 +356,14 @@ releases/ ## `docs/` documentation This directory contains the documentation for the data package. It is not only -for showing the metadata in a human-friendly way, but also for documenting details -about the package itself, how it was made, and any contributing or operational -details. It can also contain information about who uses the data and how it is -being used (e.g. based on the content in `requests/`). We strongly recommend -that this documentation is built into a website, using a tool like -[Quarto](https://quarto.org/). If it is published as a website, some files -are required to be present in the `docs/` directory, such as `index.qmd` files. -Of the directories described in this chapter, this is the only one that has no +for showing the metadata in a human-friendly way, but also for documenting +details about the package itself, how it was made, and any contributing or +operational details. It can also contain information about who uses the data and +how it is being used (e.g. based on the content in `requests/`). We strongly +recommend that this documentation is built into a website, using a tool like +[Quarto](https://quarto.org/). If it is published as a website, some files are +required to be present in the `docs/` directory, such as `index.qmd` files. Of +the directories described in this chapter, this is the only one that has no specific structure to follow. A basic structure for `docs/` might look like the following (if rendering the metadata into the website): @@ -378,8 +378,8 @@ docs/ The `metadata/` directory would contain the converted metadata from machine-readable to human-readable, e.g., using our tool [Flower](https://flower.seedcase-project.org). Other than that, you are free to -organise the documentation in any way that makes sense for your -data package. We'll cover documentation in @sec-docs. +organise the documentation in any way that makes sense for your data package. +We'll cover documentation in @sec-docs. ::: content-hidden The tree above was created using the below with this website @@ -436,11 +436,11 @@ requests/ This directory may not exist if you don't develop the data package on GitHub (or a similar service). We strongly recommend that you do, as it allows for much easier collaboration and development of the data package. It also makes it -easier to build, release, and publish the -data package, even if only the metadata is published. Other services (like Codeberg or GitLab) have similar features to -GitHub, but because GitHub is so widely used and popular, we focus on using it -in this book. We cover this directory in @sec-ci, @sec-devex, and partially in -@sec-release. The structure of this directory is shown below: +easier to build, release, and publish the data package, even if only the +metadata is published. Other services (like Codeberg or GitLab) have similar +features to GitHub, but because GitHub is so widely used and popular, we focus +on using it in this book. We cover this directory in @sec-ci, @sec-devex, and +partially in @sec-release. The structure of this directory is shown below: ```text .github/ @@ -473,16 +473,15 @@ The tree above was created using the below with this website ## `.config/` -This directory contains all the configuration files used for -the data package. For example, -since we recommend using +This directory contains all the configuration files used for the data package. +For example, since we recommend using [Cocogitto](https://decisions.seedcase-project.org/why-semantic-release-with-cocogitto/) and [git-cliff](https://decisions.seedcase-project.org/why-changelog-with-git-cliff/) -for the release process, the configuration files for those tools should be kept in -this directory. Storing them in this directory keeps the root directory cleaner -and organises the configuration files in one place. It also follows the XDG -[`.config/`](https://dot-config.github.io) specification. We go over the +for the release process, the configuration files for those tools should be kept +in this directory. Storing them in this directory keeps the root directory +cleaner and organises the configuration files in one place. It also follows the +XDG [`.config/`](https://dot-config.github.io) specification. We go over the `.config/` directory in several sections, such as @sec-devex and @sec-config. The directory structure is pretty simple, as it is a flat (non-nested) directory with only configuration files: