I'm proposing a new organization for our existing lsst/templates Git repository.

Design principles

• Support many templates for many different types of projects, not just the single stack package example that lsst/templates currently has.
• Support both "project templates" and "file templates." File templates are individual files, or parts of files, that you can drop into many different types of projects or multiple times in the same project. Examples are COPYRIGHT/LICENSE/CONTRIBUTING and test file boilerplate.
• Adopt Jinja2 and cookiecutter for template source to enable automation in the future, similar to the cookiecutter and sqrbot Slack commands for creating technotes today.
• Standardize template documentation to document every file and template variable in README files located alongside the template source.
• For every template, have an example that can be rendered precisely from the template itself.
• Adopt GitHub or a Git checkout as the primarily UI for finding templates, looking at documentation and examples, and using the templates themselves.

Prototype

You can see it for yourself:

• The prototype branch on GitHub shows the proposed organization.
• The README describes the organization.
• The CONTRIBUTING.md file describes how we'd add new templates.

Discussion

The current example stack package and Pybind11 documentation

The existing lsst/templates repository has an example stack package that contains a set of example Pybind11 modules. While this content is great, it doesn't have a place in a templates repository per se.

With this reorganization, we'd remove the Pybind11 examples from the stack package template. I'm proposing that we move the Pybind11 examples to a dedicated example_pybind11 repository in the lsst-dm GitHub organization. As a benefit, the example_pybind11 package will be added to lsstsw and made testable in CI.

Note that in the prototype ticket, the stack package template only contains an example based on the existing lsst/templates repository. This will be replaced by a cookiecutter template (like the lsst-technote-bootstrap) and an example package that is built from that cookiecutter template. This work will be in a triggered ticket.

Build system for examples

The examples provided with templates show what the templates look like when rendered. These examples are useful for folks who are browsing templates and possibly retrofitting existing projects. The examples are committed to the repository because GitHub/Git is the UI. I plan for us to have a build system that regenerates all example files and directories from the source templates. The build system might be either Scons or Makefiles that ultimately run Jinja2 and cookiecutter. The exact implementation of the build system is beyond the scope of this RFC, but this RFC does state that it will exist.

Consolidation of templates

One of the things that this RFC enables is a consolidation of all file and project templates across the DM subsystem. Such consolidation would make it easier to implement Slack bots to bootstrap files and projects. It's beyond the scope of this RFC, but we might consolidate the lsst-technote-bootstrap repository into templates. Similarly for templates in lsst-texmf. But again, the specific decisions to move these existing templates is beyond the scope of the current RFC.

New template work enabled by this organization

These are examples of tickets and projects that would benefit from this re-organization:

• RFC-45 to provide new COPYRIGHT and LICENSE files and boilerplate for C++ and Python modules.
• DM-7097: README and CONTRIBUTING files for LSST repositories.
• Templates for user documentation files in the DMTN-030 implementation.

Overall, a robust ecosystem of templates will be good for DM. Basing new files and projects off of existing ones can lead to cargo-culting. Publishing clear, definitive, and well-documented templates will help us introduce new best-practices more quickly.