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 diff --git a/README.md b/README.md index 7ad741e..9eaa770 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,25 @@ + + # An opinionated template for Data Packages built with Seedcase packages + + +[![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 +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,86 +27,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 - -You need these programs installed in order to use this template. - -- [Git](https://git-scm.com/) -- [Python](https://www.python.org/) -- [uv](https://docs.astral.sh/uv/) -- [just](https://just.systems/man/en/) - -Once you have these installed, open a terminal and 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 --trust gh:seedcase-project/template-data-package . -``` - -> [!CAUTION] -> This template runs some post-copy commands using your terminal. In order -> to run them, you need to use the `--trust` option. Review the -> [`copier.yml`](copier.yaml) file, under the `_tasks` key to see what -> commands will be run after copying the template, so you can know and trust -> what the commands are doing. Unfortunately, this template can't be used -> without the `--trust` option. - -### 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. - -After copying the template, while in the directory of the new Data Package, -run the following: - -``` bash -just install-precommit -``` - -Next, 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..494d82f --- /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 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. + +## 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/_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/docs/includes/_badges.qmd b/docs/includes/_badges.qmd new file mode 100644 index 0000000..2680f65 --- /dev/null +++ b/docs/includes/_badges.qmd @@ -0,0 +1,10 @@ + +[![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) +[![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) 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