From f8b6bb18b7f899c825f48c3b61c72c51893493aa Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Thu, 24 Jul 2025 17:43:11 +0200 Subject: [PATCH 1/5] docs: :memo: use Quarto for README creation, to insert citation --- README.md | 124 +++++++++++++++++++------------------- README.qmd | 58 ++++++++++++++++++ docs/includes/_badges.qmd | 9 +++ 3 files changed, 128 insertions(+), 63 deletions(-) create mode 100644 README.qmd create mode 100644 docs/includes/_badges.qmd diff --git a/README.md b/README.md index c1247ee..5b35aa9 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,24 @@ + + # An opinionated template for Data Packages built with Seedcase packages + + +[![GitHub +License](https://img.shields.io/github/license/seedcase-project/template-data-package)](https://github.com/seedcase-project/template-data-package/blob/main/LICENSE.md) +[![GitHub +Release](https://img.shields.io/github/v/release/seedcase-project/template-data-package)](https://github.com/seedcase-project/template-data-package/releases/latest) +[![Test](https://github.com/seedcase-project/template-data-package/actions/workflows/test.yml/badge.svg)](https://github.com/seedcase-project/template-data-package/actions/workflows/build-package.yml) +[![Build +documentation](https://github.com/seedcase-project/template-data-package/actions/workflows/build-website.yml/badge.svg)](https://github.com/seedcase-project/template-data-package/actions/workflows/build-website.yml) +[![CodeQL](https://github.com/seedcase-project/template-data-package/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/seedcase-project/template-data-package/actions/workflows/github-code-scanning/codeql) +[![pre-commit.ci +status](https://results.pre-commit.ci/badge/github/seedcase-project/template-data-package/main.svg)](https://results.pre-commit.ci/latest/github/seedcase-project/template-data-package/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: Active – The project has reached a stable, usable +state and is being actively +developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) + This repository contains a template for setting up a new [Data Package](https://datapackage.org/) following the Seedcase structure. Use this template to quickly get started with a new Data Package with all @@ -7,66 +26,45 @@ the necessary files and configurations in place, including for developing the Data Package. See the features section below for details on what is included in this template. -## Using this template - -We strongly recommend using this template with -[uv](https://docs.astral.sh/uv/). Once you have it installed, move into -the directory where you want to create the new Data Package and run the -following command: - -``` bash -# Copy into the current directory with "." -uvx copier copy gh:seedcase-project/template-data-package . -``` - -### Post-creation setup - -These steps are mainly for us in the Seedcase Project to set up the -repository with the settings we use, but you can follow them if you want -to set up your Data Package in a similar way. - -Install [`spaid`](https://github.com/seedcase-project/spaid) and use the -following commands to run the next setup steps: - -``` bash -spaid_gh_create_repo_from_local -h -spaid_gh_set_repo_settings -h -spaid_gh_ruleset_basic_protect_main -h -``` - -Some configuration is needed after copying this template to a new -repository, including configuration external to the repository. - -- The template file `.github/workflows/release-package.yml` requires - installing the - [auto-release-token](https://github.com/apps/auto-release-token) - GitHub App to be installed, as well as a GitHub secret called - `UPDATE_VERSION_TOKEN` and a variable called `UPDATE_VERSION_APP_ID` - to be set up in the repository (or organization) settings. See this - [guide](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens) - for more details on how to set this up. - -## Features - -- Use [uv](https://docs.astral.sh/uv/) to manage the Data Package. -- Use [Polars](https://www.pola.rs/) for data manipulation. -- Use [Seedcase Sprout](https://sprout.seedcase-project.org/) to - create and modify the Data Package. -- Licensed under the open data license TODO. This is added by default, - but you can delete or modify it if it isn't what you want or can - use. -- Build management with [justfile](https://just.systems/man/en/). -- Check typos with [typos](https://github.com/crate-ci/typos). -- Code formatting and linting with - [ruff](https://docs.astral.sh/ruff/). -- Pre-commit hooks with [pre-commit](https://pre-commit.com/). -- GitHub workflows for automatically adding Pull Requests and Issues - to a project board. -- Pull Request template for easy creation of new Pull Requests. -- VS Code settings for common settings for contributors using VS Code. -- EditorConfig for common cross-editor settings for contributors. -- `CITATION.cff` file for citation information. -- Website generation with [Quarto](https://quarto.org/). -- Folder and file structure that mimics a Python package to take - advantage of Python's packaging ecosystem. -- `pyproject.toml` for tracking dependencies and project metadata. +Check out our +[website](https://template-data-package.seedcase-project.org/) for more +information, such as an how to use it +[guide](https://template-data-package.seedcase-project.org/docs/guide/). +For a list of changes, see our +[changelog](https://template-data-package.seedcase-project.org/docs/releases/) +page. + +## Contributing + +Check out our [contributing +page](https://template-data-package.seedcase-project.org/CONTRIBUTING/) +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](https://github.com/seedcase-project/.github/blob/main/CODE_OF_CONDUCT.md). +By participating in this project you agree to abide by its terms. + +## Licensing + +This project is licensed under the [MIT +License](https://github.com/seedcase-project/template-data-package/blob/main/LICENSE.md). + +## Citing + +This project is part of the Seedcase Project, which is a collaborative +effort to create a framework for data management and analysis in +research. If you use this project in your work, please cite it as +follows: + +Johnston L.W., Brødbæk S.K., Beicher K., Vago M. Template Data Package: +An opinionated setup for making FAIR and structured data using Seedcase +Python packages URL: https://template-data-package.seedcase-project.org + +Or as a BibTeX entry: + + @misc{YourReferenceHere, + author = {Johnston, Luke William and Brødbæk, Signe Kirk and Beicher, Kristiane and Vago, Marton}, + title = {Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase Python packages}, + url = {https://template-data-package.seedcase-project.org} + } diff --git a/README.qmd b/README.qmd new file mode 100644 index 0000000..b7e93c8 --- /dev/null +++ b/README.qmd @@ -0,0 +1,58 @@ +--- +format: gfm +execute: + echo: false +jupyter: python3 +repo: "template-data-package" +--- + +# An opinionated template for Data Packages built with Seedcase packages + +{{< include /docs/includes/_badges.qmd >}} + +This repository contains a template for setting up a new [Data +Package](https://datapackage.org/) following the Seedcase structure. Use +this template to quickly get started with a new Data Package with all +the necessary files and configurations in place, including for +developing the Data Package. See the features section below for details +on what is included in this template. + +Check out our [website](https://{{< meta repo >}}.seedcase-project.org/) for more +information, such as an +how to use it [guide](https://{{< meta repo >}}.seedcase-project.org/docs/guide/). +For a list +of changes, see our +[changelog](https://{{< meta repo >}}.seedcase-project.org/docs/releases/) page. + +## Contributing + +Check out our [contributing page](https://{{< meta repo >}}.seedcase-project.org/CONTRIBUTING/) +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](https://github.com/seedcase-project/.github/blob/main/CODE_OF_CONDUCT.md). +By participating in this project you agree to abide by its terms. + +## Licensing + +This project is licensed under the [MIT +License](https://github.com/seedcase-project/{{< meta repo >}}/blob/main/LICENSE.md). + +## Citing + +This project is part of the Seedcase Project, which is a collaborative +effort to create a framework for data management and analysis in +research. If you use this project in your work, please cite it as +follows: + +```{python} +#| output: asis +!uvx --quiet cffconvert --format apalike +``` + +Or as a BibTeX entry: + +```{python} +!uvx --quiet cffconvert --format bibtex +``` diff --git a/docs/includes/_badges.qmd b/docs/includes/_badges.qmd new file mode 100644 index 0000000..a811168 --- /dev/null +++ b/docs/includes/_badges.qmd @@ -0,0 +1,9 @@ + +[![GitHub License](https://img.shields.io/github/license/seedcase-project/{{< meta repo >}})](https://github.com/seedcase-project/{{< meta repo >}}/blob/main/LICENSE.md) +[![GitHub Release](https://img.shields.io/github/v/release/seedcase-project/{{< meta repo >}})](https://github.com/seedcase-project/{{< meta repo >}}/releases/latest) +[![Test](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/test.yml/badge.svg)](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/build-package.yml) +[![Build documentation](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/build-website.yml/badge.svg)](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/build-website.yml) +[![CodeQL](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main)](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/github-code-scanning/codeql) +[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/seedcase-project/{{< meta repo >}}/main.svg)](https://results.pre-commit.ci/latest/github/seedcase-project/{{< meta repo >}}/main) +[![lifecycle](https://lifecycle.r-lib.org/articles/figures/lifecycle-experimental.svg)](https://lifecycle.r-lib.org/articles/stages.html#experimental) +[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) From 2fa3902b3170576cb8bc097c66c7a024ddfaa0fb Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Thu, 24 Jul 2025 17:43:24 +0200 Subject: [PATCH 2/5] docs: :pencil2: add `.` to end of title --- CITATION.cff | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CITATION.cff b/CITATION.cff index ab82d36..d8aaf9b 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -1,4 +1,4 @@ -title: "Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase Python packages" +title: "Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase Python packages." abstract: "A template for making a Git repository that follows strongly opinionated practices for building and managing a data package. These practices include using Seedcase Python packages, such as Seedcase Sprout, and the Frictionless Data Package standard." authors: - family-names: Johnston From 7f54a2ee1a639ff6e3881e41a214d88a588ba086 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Thu, 24 Jul 2025 20:53:26 +0200 Subject: [PATCH 3/5] build: :hammer: rebuild README with a justfile recipe --- README.md | 4 ++-- _quarto.yml | 1 - justfile | 6 +++++- 3 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 5b35aa9..8214c2f 100644 --- a/README.md +++ b/README.md @@ -59,12 +59,12 @@ follows: Johnston L.W., Brødbæk S.K., Beicher K., Vago M. Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase -Python packages URL: https://template-data-package.seedcase-project.org +Python packages. URL: https://template-data-package.seedcase-project.org Or as a BibTeX entry: @misc{YourReferenceHere, author = {Johnston, Luke William and Brødbæk, Signe Kirk and Beicher, Kristiane and Vago, Marton}, - title = {Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase Python packages}, + title = {Template Data Package: An opinionated setup for making FAIR and structured data using Seedcase Python packages.}, url = {https://template-data-package.seedcase-project.org} } diff --git a/_quarto.yml b/_quarto.yml index 68a3628..3262f53 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -1,7 +1,6 @@ project: type: seedcase-theme pre-render: - - quarto render README.qmd --to gfm - sh ./tools/get-contributors.sh render: # Don't render anything in the template directory. diff --git a/justfile b/justfile index a4c3466..dd28c88 100644 --- a/justfile +++ b/justfile @@ -2,7 +2,7 @@ just --list --unsorted # Run all build-related recipes in the justfile -run-all: check-spelling check-commits test build-website +run-all: check-spelling check-commits test build-website build-readme # Install the pre-commit hooks install-precommit: @@ -58,3 +58,7 @@ cleanup: # Build the website using Quarto build-website: uvx --from quarto quarto render + +# Re-build the README file from the Quarto version +build-readme: + uvx --from quarto quarto render README.qmd --to gfm From 8ea4fcd9007df4435aafc53527966344edf1027e Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Fri, 25 Jul 2025 09:30:06 +0200 Subject: [PATCH 4/5] refactor: :recycle: add Copier badge --- README.md | 1 + docs/includes/_badges.qmd | 1 + 2 files changed, 2 insertions(+) diff --git a/README.md b/README.md index 8214c2f..9eaa770 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,7 @@ +[![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)](https://github.com/copier-org/copier) [![GitHub License](https://img.shields.io/github/license/seedcase-project/template-data-package)](https://github.com/seedcase-project/template-data-package/blob/main/LICENSE.md) [![GitHub diff --git a/docs/includes/_badges.qmd b/docs/includes/_badges.qmd index a811168..2680f65 100644 --- a/docs/includes/_badges.qmd +++ b/docs/includes/_badges.qmd @@ -1,4 +1,5 @@ +[![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)](https://github.com/copier-org/copier) [![GitHub License](https://img.shields.io/github/license/seedcase-project/{{< meta repo >}})](https://github.com/seedcase-project/{{< meta repo >}}/blob/main/LICENSE.md) [![GitHub Release](https://img.shields.io/github/v/release/seedcase-project/{{< meta repo >}})](https://github.com/seedcase-project/{{< meta repo >}}/releases/latest) [![Test](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/test.yml/badge.svg)](https://github.com/seedcase-project/{{< meta repo >}}/actions/workflows/build-package.yml) From 5467b5dd29e2e541579aaedbb54709de3c608316 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Fri, 25 Jul 2025 11:11:57 +0200 Subject: [PATCH 5/5] docs: :pencil2: edit from review Co-authored-by: martonvago <57952344+martonvago@users.noreply.github.com> --- README.qmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.qmd b/README.qmd index b7e93c8..494d82f 100644 --- a/README.qmd +++ b/README.qmd @@ -18,8 +18,8 @@ developing the Data Package. See the features section below for details on what is included in this template. Check out our [website](https://{{< meta repo >}}.seedcase-project.org/) for more -information, such as an -how to use it [guide](https://{{< meta repo >}}.seedcase-project.org/docs/guide/). +information, such as a +[guide](https://{{< meta repo >}}.seedcase-project.org/docs/guide/) for using the template. For a list of changes, see our [changelog](https://{{< meta repo >}}.seedcase-project.org/docs/releases/) page.