feat: ✨ add files with copier variables (#127)

# Description

This PR adds `copier.yaml` and template files that depend on it.
Some related config is also tidied up.

Closes #33 

## Checklist

- [x] Added or updated tests
- [x] Updated documentation
- [x] Ran `just run-all`

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Luke W. Johnston <[email protected]>

Author: 3 people

.gitignore

@@ -2,6 +2,7 @@
 _ignore
 bin/
 dev/
+_temp/
 
 # Temporary files
 *.tmp

.vscode/settings.json

@@ -30,6 +30,7 @@
   "python.languageServer": "Pylance",
   "files.insertFinalNewline": true,
   "files.associations": {
+    "justfile.jinja": "plaintext",
     "*.yml.jinja": "jinja-yaml",
     "*.cff.jinja": "jinja-yaml",
     "*.toml.jinja": "jinja-toml",

copier.yaml

@@ -0,0 +1,109 @@
+_subdirectory: template
+
+# Post-copy commands:
+_tasks:
+  # Add dev dependencies
+  - command: "git init -b main; uv add --dev pre-commit ruff typos pytest bandit commitizen genbadge jupyter pytest-cov quartodoc types-tabulate mypy vulture"
+    when: "{{ _copier_operation == 'copy' }}"
+
+# Message to show after generating or regenerating the project successfully
+_message_after_copy: |
+
+  Your project "{{ package_name }}" has been created successfully!
+
+  Next steps:
+
+  1. Change directory to the project root:
+
+    $ cd {{ _copier_conf.dst_path }}
+
+  2. Install the pre-commit hooks:
+
+    $ just install-precommit
+
+  3. Install [`spaid`](https://github.com/seedcase-project/spaid) and run these commands to upload and configure your project on GitHub:
+
+    $ spaid_gh_create_repo_from_local -h
+    $ spaid_gh_set_repo_settings -h
+    $ spaid_gh_ruleset_basic_protect_main -h
+
+  4. Configure GitHub following this
+    [guide](https://guidebook.seedcase-project.org/operations/security#using-github-apps-to-generate-tokens):
+
+    - Install the [auto-release-token](https://github.com/apps/auto-release-token)
+      and [add-to-board-token](https://github.com/apps/add-to-board-token) GitHub Apps
+    - Create an `UPDATE_VERSION_TOKEN` and `ADD_TO_BOARD_TOKEN` secret for the GitHub Apps
+    - Create an `UPDATE_VERSION_APP_ID` and `ADD_TO_BOARD_APP_ID` variable of the GitHub Apps' IDs
+
+  5. List and complete all TODO items in the repository:
+
+    $ just list-todos
+
+# Questions:
+package_github_repo:
+  type: str
+  help: "What is or will be the GitHub repository spec for the project?"
+  placeholder: "user/repo"
+  validator: |
+    {% if package_github_repo and not (package_github_repo | regex_search('^[\w.-]+\/[\w.-]+$')) %}
+    Must be in the format `user/repo` and contain only alphanumeric characters and `_`, `-`, or `.`.
+    {% endif %}
+
+github_user:
+  type: str
+  default: "{{ package_github_repo.split('/')[0] if package_github_repo else '' }}"
+  when: false
+
+package_name:
+  type: str
+  help: "What is the name of the package?"
+  default: "{{ _copier_conf.dst_path | basename }}"
+  validator: |
+    {% if package_name and not (package_name | regex_search('^[\w.-]+$')) %}
+    Must contain only alphanumeric characters and `_`, `-`, or `.`.
+    {% endif %}
+
+package_name_snake_case:
+  type: str
+  default: "{{package_name | replace('-', '_') | replace('.', '_')}}"
+  when: false
+
+is_seedcase_project:
+  type: bool
+  help: "Is this package part of the Seedcase Project?"
+  default: "{{ github_user == 'seedcase-project' }}"
+
+homepage:
+  type: str
+  help: "What is the homepage of your project?"
+  default: "{{ 'https://%s.seedcase-project.org' % package_name if is_seedcase_project else '' }}"
+
+author_given_name:
+  type: str
+  help: "What is your first/given name?"
+
+author_family_name:
+  type: str
+  help: "What is your last/family name?"
+
+author_email:
+  type: str
+  help: "What is your email address?"
+
+review_team:
+  type: str
+  help: What GitHub team is responsible for reviewing pull requests?
+  default: "{{ '@%s/developers' % github_user if github_user else '' }}"
+
+github_board_number:
+  type: str
+  help: "What is the GitHub project board number to add issues and PRs to?"
+  validator: |
+    {% if github_board_number and not github_board_number.isdigit() %}
+    The board number must be an integer.
+    {% endif %}
+
+copyright_year:
+  type: str
+  default: "{{ copyright_year | default('%Y' | strftime) }}"
+  when: false

docs/guide.qmd

@@ -136,6 +136,8 @@ Project, run:
 just update-quarto-theme
 ```
 
+Then set `seedcase-theme` as your project `type` in `_quarto.yml`.
+
 This adds the `seedcase-theme` Quarto theme to the website, which
 provides a consistent look and feel across all Seedcase Project
 websites, including for Python package websites.

justfile

@@ -2,10 +2,12 @@
     just --list --unsorted
 
 @_checks: check-spelling check-commits
+# Test Seedcase and non-Seedcase projects
+@_tests: (test "true") (test "false")
 @_builds: build-contributors build-website build-readme
 
 # Run all build-related recipes in the justfile
-run-all: update-quarto-theme update-template _checks test _builds
+run-all: update-quarto-theme update-template _checks _tests _builds
 
 # Install the pre-commit hooks
 install-precommit:
@@ -26,7 +28,7 @@ update-template:
   mkdir -p template/tools
   cp tools/get-contributors.sh template/tools/
   cp .github/pull_request_template.md template/.github/
-  cp .github/workflows/build-website.yml .github/workflows/dependency-review.yml template/.github/workflows/
+  cp .github/workflows/dependency-review.yml template/.github/workflows/
 
 # Check the commit messages on the current branch that are not on the main branch
 check-commits:
@@ -45,9 +47,59 @@ check-spelling:
   uvx typos
 
 # Test and check that a Python package can be created from the template
-# TODO: add test for copier
-test:
-  echo "copier test"
+test is_seedcase_project:
+  #!/bin/zsh
+  test_name="test-python-package"
+  test_dir="$(pwd)/_temp/{{ is_seedcase_project }}/$test_name"
+  template_dir="$(pwd)"
+  commit=$(git rev-parse HEAD)
+  rm -rf $test_dir
+  # vcs-ref means the current commit/head, not a tag.
+  uvx copier copy $template_dir $test_dir \
+    --vcs-ref=$commit \
+    --defaults \
+    --trust \
+    --data package_github_repo="first-last/repo" \
+    --data is_seedcase_project={{ is_seedcase_project }} \
+    --data author_given_name="First" \
+    --data author_family_name="Last" \
+    --data author_email="[email protected]" \
+    --data review_team="@first-last/developers" \
+    --data github_board_number=22
+  # Run checks in the generated test Python package
+  cd $test_dir
+  git add .
+  git commit -m "test: initial copy"
+  just check-python check-spelling
+  # TODO: Find some way to test the `update` command
+  # Check that recopy works
+  echo "Testing recopy command -----------"
+  rm .cz.toml
+  git add .
+  git commit -m "test: preparing to recopy from the template"
+  uvx copier recopy \
+    --vcs-ref=$commit \
+    --defaults \
+    --overwrite \
+    --trust
+  # Check that copying onto an existing Python package works
+  echo "Using the template in an existing package command -----------"
+  rm .cz.toml .copier-answers.yml LICENSE.md
+  git add .
+  git commit -m "test: preparing to copy onto an existing package"
+  uvx copier copy \
+    $template_dir $test_dir \
+    --vcs-ref=$commit \
+    --defaults \
+    --trust \
+    --overwrite \
+    --data package_github_repo="first-last/repo" \
+    --data is_seedcase_project={{ is_seedcase_project }} \
+    --data author_given_name="First" \
+    --data author_family_name="Last" \
+    --data author_email="[email protected]" \
+    --data review_team="@first-last/developers" \
+    --data github_board_number=22
 
 # Clean up any leftover and temporary build files
 cleanup:
@@ -64,4 +116,4 @@ build-readme:
 
 # Generate a Quarto include file with the contributors
 build-contributors:
-  sh ./tools/get-contributors.sh seedcase-project/template-workshop
+  sh ./tools/get-contributors.sh seedcase-project/template-python-project

template/.github/CODEOWNERS.jinja

@@ -0,0 +1,2 @@
+# All members on Developers team get added to review PRs
+* {{ review_team }}

template/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    versioning-strategy: increase-if-necessary
+    commit-message:
+      prefix: build
+      include: scope

template/.github/workflows/add-to-project.yml.jinja

@@ -0,0 +1,27 @@
+name: Add to project board
+
+on:
+  issues:
+    types:
+      - opened
+      - reopened
+      - transferred
+  pull_request:
+    types:
+      - reopened
+      - opened
+
+# Limit token permissions for security
+permissions: read-all
+
+jobs:
+  add-to-project:
+    uses: seedcase-project/.github/.github/workflows/reusable-add-to-project.yml@main
+    permissions:
+      pull-requests: write
+    with:
+      board-number: {{ github_board_number }}
+      app-id: {{ '${{ vars.ADD_TO_BOARD_APP_ID }}' }}
+    secrets:
+      add-to-board-token: {{ '${{ secrets.ADD_TO_BOARD }}' }}
+      gh-token: {{ '${{ secrets.GITHUB_TOKEN }}' }}

template/CITATION.cff.jinja

@@ -0,0 +1,24 @@
+# TODO: Add title of Python package.
+title: ""
+# TODO: Add abstract of Python package.
+abstract: ""
+authors:
+  - family-names: {{ author_family_name }}
+    given-names: {{ author_given_name }}
+  # TODO: Add ORCID and affiliation for the author.
+    orcid: ""
+    affiliation: ""
+  # TODO: Add more authors as needed.
+  # - family-names: ""
+  #   given-names: ""
+  #   orcid: ""
+  #   affiliation: ""
+cff-version: 1.2.0
+# doi:
+keywords:
+  # TODO: Add keywords relevant to the project.
+  - ""
+license: MIT
+message: "If you use this Python package, please cite it using these metadata."
+repository-code: "https://github.com/{{ package_github_repo }}"
+url: "{{ homepage }}"

template/LICENSE.md.jinja

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) {{ copyright_year }} {{ package_name }} authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.