diff --git a/copier.yaml b/copier.yaml index 85eea46..d42cd23 100644 --- a/copier.yaml +++ b/copier.yaml @@ -1,95 +1,41 @@ -_subdirectory: template +_subdirectory: "template" # Message to show after generating or regenerating the project successfully _message_after_copy: | - Your project "{{ github_repo }}" has been created successfully! + Your project "{{ github_repo }}" has been created successfully! See + the template's guide as well as the "TODO.md" file in the newly created + project for more details on the next steps. - See the [guide](https://template-python-package.seedcase-project.org/docs/guide) for more detail - on the next steps. Briefly: - - 1. Change directory to the project root: - - ``` bash - cd {{ _copier_conf.dst_path | realpath }} - ``` - - 2. Install the pre-commit hooks, add (called "update" here) the Quarto extension, - and build the README: - - ``` bash - just install-precommit update-quarto-theme build-readme - ``` - - 3. Install [`spaid`](https://github.com/seedcase-project/spaid) and run these setup steps: - - ``` bash - 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: - - ``` bash - just list-todos - ``` - -# Questions: -is_seedcase_project: +# Questions +for_seedcase: type: bool help: "Is this package part of the Seedcase Project?" - default: true + default: false github_user: type: str - help: "What is the name of the GitHub user or organisation where the repository will be or is stored?" - default: "{{ 'seedcase-project' if is_seedcase_project else '' }}" + help: | + What is the name of the GitHub user or organization where the + package repository will be or is stored? + default: >- + {{ "seedcase-project" if for_seedcase else "" }} github_repo: type: str - help: "What is the name of the GitHub repository where the website will be or is stored? We strongly recommend using the default given." + help: | + What is the name of the GitHub repository where the package will be or + is stored? We strongly recommend using the default given. default: "{{ _folder_name }}" hosting_provider: type: str - help: "What hosting provider will you use for the documentation website?" + help: "What hosting provider will you use for the package's website?" choices: - netlify - gh-pages - -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 %} + default: >- + {{ "netlify" if for_seedcase else "gh-pages" }} # Configurations not asked github_repo_snake_case: @@ -106,8 +52,3 @@ copyright_year: type: str default: "{{ copyright_year | default('%Y' | strftime) }}" when: false - -homepage: - type: str - default: "https://{{ github_repo }}.{{ github_user }}.org" - when: false diff --git a/justfile b/justfile index 62cc956..e747c1b 100644 --- a/justfile +++ b/justfile @@ -53,8 +53,8 @@ format-md: uvx rumdl fmt --silent **/*.qmd.jinja **/*.md.jinja # Test template creation with specific parameters: LIST -test is_seedcase_project="true" hosting_provider="netlify": - sh ./test-template.sh {{ is_seedcase_project }} {{ hosting_provider }} +test for_seedcase="true" hosting_provider="netlify": + sh ./test-template.sh {{ for_seedcase }} {{ hosting_provider }} # Test template creation through use of the question approach test-manual: diff --git a/template/.github/workflows/add-to-project.yml.jinja b/template/.github/workflows/add-to-project.yml.jinja index 955b8d5..54ec674 100644 --- a/template/.github/workflows/add-to-project.yml.jinja +++ b/template/.github/workflows/add-to-project.yml.jinja @@ -20,7 +20,8 @@ jobs: permissions: pull-requests: write with: - board-number: {{ github_board_number }} + # TODO: Fill in the board number. + board-number: "" app-id: {{ '${{ vars.ADD_TO_BOARD_APP_ID }}' }} secrets: add-to-board-token: {{ '${{ secrets.ADD_TO_BOARD }}' }} diff --git a/template/404.qmd.jinja b/template/404.qmd.jinja index fd84eef..dd0c07c 100644 --- a/template/404.qmd.jinja +++ b/template/404.qmd.jinja @@ -1,19 +1,22 @@ --- -{% if is_seedcase_project -%} +{% if for_seedcase -%} title: "You've entered the garden of missing pages" {% else -%} title: "The page you are looking for does not exist" {% endif -%} --- -{% if is_seedcase_project -%} +{% if for_seedcase -%} 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} + {%- else -%} -This page does not exist, go back to the [homepage](/index.qmd) or check the URL for typos. +This page does not exist, go back to the [homepage](/index.qmd) or check +the URL for typos. {%- endif %} diff --git a/template/CITATION.cff.jinja b/template/CITATION.cff.jinja index c1444d2..9166665 100644 --- a/template/CITATION.cff.jinja +++ b/template/CITATION.cff.jinja @@ -3,9 +3,9 @@ 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. + # TODO: Add author information. + - family-names: "" + given-names: "" orcid: "" affiliation: "" # TODO: Add more authors as needed. @@ -22,5 +22,5 @@ keywords: license: MIT message: "If you use this Python package, please cite it using these metadata." repository-code: "https://github.com/{{ github_repo_spec }}" -# TODO: Confirm URL -url: "{{ homepage }}" +# TODO: Add URL to a website. +url: "" diff --git a/template/CONTRIBUTING.md.jinja b/template/CONTRIBUTING.md.jinja index de13063..ae4a2bf 100644 --- a/template/CONTRIBUTING.md.jinja +++ b/template/CONTRIBUTING.md.jinja @@ -9,7 +9,7 @@ issue on our GitHub repository. ## :pencil2: Adding or modifying content -{% if is_seedcase_project -%} +{% if for_seedcase -%} If you would like to contribute content, please check out our [guidebook](https://guidebook.seedcase-project.org/) for more specific details on how we work and develop. It is a regularly evolving document, diff --git a/template/TODO.md b/template/TODO.md new file mode 100644 index 0000000..341ff86 --- /dev/null +++ b/template/TODO.md @@ -0,0 +1,46 @@ +- Review the + [template guide](https://t-squared.seedcase-project.org/docs/guide/) + for more information on how to use the template and the next steps + after copying the project. +- Run `git init -b main` to create the project as a Git repository. +- Install these packages + `uv add --dev pre-commit ruff typos pytest bandit commitizen genbadge jupyter pytest-cov quartodoc types-tabulate mypy vulture` +- Run `just list-todos` and complete all the TODO items. +- Run `just install-precommit` to install the pre-commit hooks. +- Run `just build-readme` to build the Markdown version of the README. + {%- if for_seedcase -%} +- Run `just update-quarto-theme` to add the Seedcase Quarto extension. +- Install the [`spaid`](https://github.com/seedcase-project/spaid) CLI + tool and run these setup steps: + - `spaid_gh_create_repo_from_local -h` to create a GitHub repository + from the local repository. + - `spaid_gh_set_repo_settings -h` to set the repository settings. + - `spaid_gh_ruleset_basic_protect_main -h` to protect the main branch. + - `spaid_gh_ruleset_require_pr -h` to require pull requests for + changes to the main branch. +- Install or add 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 if you haven't already and connect them to the + repository. + - Create an `UPDATE_VERSION_APP_ID` and `ADD_TO_BOARD_APP_ID` variable + of the GitHub Apps' IDs if you haven't already and connect them to + the repository. + {%- else -%} +- Install the [gh CLI](https://cli.github.com/) to create the GitHub + repository from the command line by using + `gh repo create {{ github_repo_spec }} --source=. --public`. + {%- endif %} + {% if hosting_provider == "netlify" %} +- Connect the repository to Netlify and turn off the builds on Netlify, + since you will be using GitHub Actions to build and deploy the + website. + {%- elif hosting_provider == "gh-pages" -%} +- Run `quarto publish gh-pages` to setup and start publishing the + website to GitHub Pages. + {%- endif %} +- If relevant, connect [GoatCounter](https://www.goatcounter.com/). +- If relevant, connect [pre-commit.ci](https://pre-commit.ci/) to the + repository and enable the pre-commit hooks. diff --git a/template/_quarto.yml.jinja b/template/_quarto.yml.jinja index d7ea44a..f4f5dbb 100644 --- a/template/_quarto.yml.jinja +++ b/template/_quarto.yml.jinja @@ -16,7 +16,7 @@ website: navbar: pinned: true title: false - {%- if is_seedcase_project %} + {%- if for_seedcase %} logo: "_extensions/seedcase-project/seedcase-theme/logos/{{ github_repo }}/navbar.svg" logo-alt: "{{ github_repo }} logo: Main page" {%- else %} @@ -37,7 +37,7 @@ website: - icon: github href: "https://github.com/{{ github_repo_spec }}" aria-label: "GitHub icon: Source code" - {%- if is_seedcase_project %} + {%- if for_seedcase %} - icon: house href: "https://seedcase-project.org" aria-label: "House icon: Main website for the Seedcase Project" @@ -75,7 +75,7 @@ metadata-files: - docs/reference/_sidebar.yml format: - {% if is_seedcase_project -%} + {% if for_seedcase -%} seedcase-theme-html: theme: - brand diff --git a/template/justfile.jinja b/template/justfile.jinja index 1c24d65..efe61a4 100644 --- a/template/justfile.jinja +++ b/template/justfile.jinja @@ -8,7 +8,7 @@ @_builds: build-contributors build-website build-readme # Run all build-related recipes in the justfile -{%- if is_seedcase_project %} +{%- if for_seedcase %} run-all: install-deps update-quarto-theme format-python format-md _checks _tests _builds {%- else %} run-all: install-deps format-python _checks _tests _builds @@ -32,7 +32,7 @@ install-precommit: # Update versions of pre-commit hooks uvx pre-commit autoupdate -{%- if is_seedcase_project %} +{%- if for_seedcase %} # Update the Quarto seedcase-theme extension update-quarto-theme: # Add theme if it doesn't exist, update if it does diff --git a/template/pyproject.toml.jinja b/template/pyproject.toml.jinja index cda9b22..1f8a98f 100644 --- a/template/pyproject.toml.jinja +++ b/template/pyproject.toml.jinja @@ -4,12 +4,12 @@ version = "0.1.0" # TODO: Add a description of the package. description = "" authors = [ - {name = "{{ author_given_name }} {{ author_family_name }}", email = "{{ author_email }}" }, - # TODO: Add more authors as needed. + # TODO: Add author information. + {name = "FIRST LAST", email = "" }, ] maintainers = [ - {name = "{{ author_given_name }} {{ author_family_name }}", email = "{{ author_email }}" }, - # TODO: Add more maintainers as needed. + # TODO: Add maintainer information. + {name = "FIRST LAST", email = "" }, ] readme = "README.md" license = "MIT" @@ -18,8 +18,8 @@ requires-python = ">=3.12" dependencies = [] [project.urls] -# TODO: Confirm URL -homepage = "{{ homepage }}" +# TODO: Add URLs relevant to the project. +homepage = "" repository = "https://github.com/{{ github_repo_spec }}" changelog = "https://github.com/{{ github_repo_spec }}/blob/main/CHANGELOG.md" issues = "https://github.com/{{ github_repo_spec }}/issues" diff --git a/test-template.sh b/test-template.sh index 99436fe..932dcdd 100644 --- a/test-template.sh +++ b/test-template.sh @@ -2,21 +2,21 @@ # Needs these arguments: # -# 1. is_seedcase_project: true or false +# 1. for_seedcase: true or false # 2. hosting_provider: e.g., "github", "gitlab", etc. # Argument naming ----- -is_seedcase_project="${1}" +for_seedcase="${1}" hosting_provider="${2}" -if [ -z "$is_seedcase_project" ] || [ -z "$hosting_provider" ]; then - echo "Usage: sh $0 " +if [ -z "$for_seedcase" ] || [ -z "$hosting_provider" ]; then + echo "Usage: sh $0 " echo "Example: sh $0 true netlify" exit 1 fi # Set up variables and functions for the test ----- -test_name="$is_seedcase_project-$hosting_provider" +test_name="$for_seedcase-$hosting_provider" test_dir="$(pwd)/_temp/auto/$test_name" template_dir="$(pwd)" @@ -29,14 +29,9 @@ copy () { uvx copier copy $1 $2 \ -r HEAD \ --defaults \ - --data is_seedcase_project=$is_seedcase_project \ + --data for_seedcase=$for_seedcase \ --data github_user="first-last" \ --data hosting_provider=$hosting_provider \ - --data author_given_name="First" \ - --data author_family_name="Last" \ - --data author_email="first.last@example.com" \ - --data review_team="@first-last/developers" \ - --data github_board_number=22 \ --overwrite } @@ -48,7 +43,7 @@ mkdir -p $test_dir # Check initial creation ----- # TODO: Find some way to test the `update` command # Any step that fails will exit the script with an error and not continue -echo "Testing copy for new projects when: 'is_seedcase_project'='$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" +echo "Testing copy for new projects when: 'for_seedcase'='$for_seedcase', 'hosting_provider'='$hosting_provider' -----------" ( cd $test_dir && copy $template_dir $test_dir && @@ -56,7 +51,7 @@ echo "Testing copy for new projects when: 'is_seedcase_project'='$is_seedcase_pr git add . && git commit --quiet -m "test: initial copy" && # Check that recopy works ----- - echo "Testing recopy when: 'is_seedcase_project'='$$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" && + echo "Testing recopy when: 'for_seedcase'='$for_seedcase', 'hosting_provider'='$hosting_provider' -----------" && rm .gitignore && git add . && git commit --quiet -m "test: preparing to recopy from the template" && @@ -67,7 +62,7 @@ echo "Testing copy for new projects when: 'is_seedcase_project'='$is_seedcase_pr --skip-tasks \ --trust && # Check that copying onto an existing project works ----- - echo "Testing copy in existing projects when: 'is_seedcase_project'='$is_seedcase_project', 'hosting_provider'='$hosting_provider' -----------" && + echo "Testing copy in existing projects when: 'for_seedcase'='$for_seedcase', 'hosting_provider'='$hosting_provider' -----------" && rm .gitignore .copier-answers.yml && git add . && git commit --quiet -m "test: preparing to copy onto an existing project" &&