Project scaffolding from templates
Starting from a maintained community template gives a research software
project the whole quality baseline - packaging, tests, CI, linting,
citation files, docs - in one step, encoded the way its community
actually practices it. The skill here is threefold: pick the right
generator, generate (or retrofit) honestly, and keep the project in
sync as the template evolves.
Choosing a generator
- Copier: templates are versioned;
copier update can replay template
improvements into an already-generated project later. Prefer it when
the template supports it - staying current is the hard part of
template use, and Copier is built for it.
- cookiecutter: widest ecosystem of templates; generation is one-shot
(no built-in update path), so treat the result as a starting point
you own from day one.
Prefer a template maintained by a research software community over a
generic one: it will encode citation files, FAIR practices and
research-specific CI that generic templates omit.
The NLeSC python-template (reference implementation)
The Netherlands eScience Center's Copier template
(https://github.com/NLeSC/python-template, Apache-2.0, actively
maintained) is a strong default for research Python packages:
pipx install copier
copier copy https://github.com/nlesc/python-template.git path/to/project
copier update # later: pull template improvements
- Three profiles: Minimum (essentials), Recommended (curated defaults),
or fully custom - match the profile to the software tier (analysis
code -> Minimum; shared tools -> Recommended).
- It can also retrofit structure onto EXISTING code: run
copier copy
into the existing directory and reconcile.
- What it encodes (Recommended): src/ layout, setuptools +
setuptools-scm build backend, pytest with branch coverage, tox matrix
following the SPEC 0 version policy (three most recent Python
minors), ruff as single linter/formatter/import-sorter, type checking
(Pyright default, Mypy optional), pre-commit, EditorConfig,
CITATION.cff plus a cffconvert CI check, Zenodo DOI instructions,
Sphinx docs with Read the Docs, SonarCloud analysis, changelog,
community files, and a
next_steps.yml workflow that opens onboarding
issues for the manual setup steps (Zenodo, SonarCloud, Read the Docs).
- Expect opinionated defaults (line length 79, SonarCloud rather than
other coverage services); accept them unless the project has a
reason not to - fighting a template forfeits
copier update.
Choosing a build backend
When scaffolding by hand or answering template questions:
- setuptools + setuptools-scm: the template's default; version derived
from git tags; battle-tested.
- hatchling: modern, minimal configuration; good default for new
hand-rolled packages.
- poetry / PDM: bring their own dependency workflow; choose them only
when the team wants that workflow, not just a build backend.
Whatever the choice, keep all tool configuration in pyproject.toml
sections rather than scattered dotfiles where the tools support it.
After scaffolding
Generation is the start, not the finish:
- Work through the template's onboarding steps (the NLeSC template
opens them as GitHub issues) instead of leaving badges broken.
- Delete generated options the project will not use rather than letting
them rot; record the answers file (.copier-answers.yml) in git so
copier update works.
- Route the per-practice follow-ups to the sibling skills: tests
(rseng-testing), CI (rseng-ci-cd), docs (rseng-documentation), citation
(rseng-citation-metadata), releases (rseng-publishing-releasing), FAIR
posture (rseng-fair-software, rseng-fairguard).
Working with this skill
This skill is source-independent: its authority is the template and
generator documentation linked below, not a bundled content source.
Learn more (verified):
Related skills
Check whether any of these applies before moving on:
- rseng-ci-cd - generated workflow files need understanding
- rseng-citation-metadata - template ships CITATION.cff and cffconvert check
- rseng-dependency-management - keeping generated tooling current
- rseng-fair-software - templates encode the FAIR baseline
- rseng-project-kickoff - management-side project start
- rseng-publishing-releasing - packaging and release setup follow-up
1---2name: rseng-project-scaffolding3description: Covers starting research software projects from maintained templates and keeping them in sync: choosing a generator (Copier, cookiecutter), scaffolding a Python package, retrofitting template structure, pulling template upgrades into generated projects, and picking a pyproject build backend. Use when the user starts a new research software codebase, asks for a template or boilerplate, wants a src/ layout or pyproject.toml scaffold, mentions copier or cookiecutter, or chooses between setuptools, hatchling, poetry or PDM. For hand-rolled layout see rseng-code-quality; for the management side see rseng-project-kickoff.4license: CC-BY-4.05---67# Project scaffolding from templates89Starting from a maintained community template gives a research software10project the whole quality baseline - packaging, tests, CI, linting,11citation files, docs - in one step, encoded the way its community12actually practices it. The skill here is threefold: pick the right13generator, generate (or retrofit) honestly, and keep the project in14sync as the template evolves.1516## Choosing a generator1718- Copier: templates are versioned; `copier update` can replay template19 improvements into an already-generated project later. Prefer it when20 the template supports it - staying current is the hard part of21 template use, and Copier is built for it.22- cookiecutter: widest ecosystem of templates; generation is one-shot23 (no built-in update path), so treat the result as a starting point24 you own from day one.2526Prefer a template maintained by a research software community over a27generic one: it will encode citation files, FAIR practices and28research-specific CI that generic templates omit.2930## The NLeSC python-template (reference implementation)3132The Netherlands eScience Center's Copier template33(https://github.com/NLeSC/python-template, Apache-2.0, actively34maintained) is a strong default for research Python packages:3536```bash37pipx install copier38copier copy https://github.com/nlesc/python-template.git path/to/project39copier update # later: pull template improvements40```4142- Three profiles: Minimum (essentials), Recommended (curated defaults),43 or fully custom - match the profile to the software tier (analysis44 code -> Minimum; shared tools -> Recommended).45- It can also retrofit structure onto EXISTING code: run `copier copy`46 into the existing directory and reconcile.47- What it encodes (Recommended): src/ layout, setuptools +48 setuptools-scm build backend, pytest with branch coverage, tox matrix49 following the SPEC 0 version policy (three most recent Python50 minors), ruff as single linter/formatter/import-sorter, type checking51 (Pyright default, Mypy optional), pre-commit, EditorConfig,52 CITATION.cff plus a cffconvert CI check, Zenodo DOI instructions,53 Sphinx docs with Read the Docs, SonarCloud analysis, changelog,54 community files, and a `next_steps.yml` workflow that opens onboarding55 issues for the manual setup steps (Zenodo, SonarCloud, Read the Docs).56- Expect opinionated defaults (line length 79, SonarCloud rather than57 other coverage services); accept them unless the project has a58 reason not to - fighting a template forfeits `copier update`.5960## Choosing a build backend6162When scaffolding by hand or answering template questions:6364- setuptools + setuptools-scm: the template's default; version derived65 from git tags; battle-tested.66- hatchling: modern, minimal configuration; good default for new67 hand-rolled packages.68- poetry / PDM: bring their own dependency workflow; choose them only69 when the team wants that workflow, not just a build backend.7071Whatever the choice, keep all tool configuration in pyproject.toml72sections rather than scattered dotfiles where the tools support it.7374## After scaffolding7576Generation is the start, not the finish:7778- Work through the template's onboarding steps (the NLeSC template79 opens them as GitHub issues) instead of leaving badges broken.80- Delete generated options the project will not use rather than letting81 them rot; record the answers file (.copier-answers.yml) in git so82 `copier update` works.83- Route the per-practice follow-ups to the sibling skills: tests84 (rseng-testing), CI (rseng-ci-cd), docs (rseng-documentation), citation85 (rseng-citation-metadata), releases (rseng-publishing-releasing), FAIR86 posture (rseng-fair-software, rseng-fairguard).8788## Working with this skill8990This skill is source-independent: its authority is the template and91generator documentation linked below, not a bundled content source.9293Learn more (verified):94 - https://github.com/NLeSC/python-template - the template95 - https://research-software-directory.org/software/nlesc-python-template -96 its Research Software Directory entry97 - https://copier.readthedocs.io/en/stable/ - Copier documentation9899<!-- related-skills:begin -->100101## Related skills102103Check whether any of these applies before moving on:104105- rseng-ci-cd - generated workflow files need understanding106- rseng-citation-metadata - template ships CITATION.cff and cffconvert check107- rseng-dependency-management - keeping generated tooling current108- rseng-fair-software - templates encode the FAIR baseline109- rseng-project-kickoff - management-side project start110- rseng-publishing-releasing - packaging and release setup follow-up111112<!-- related-skills:end -->
fdiblen