You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: copier/MAINTAINERS.md
+10-10Lines changed: 10 additions & 10 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,6 @@
1
1
# Maintaining the Copier Template
2
2
3
-
This document provides instructions for maintainers of the `exemplar` repository on how to test, update, and manage the `copier` template generation infrastructure.
3
+
This document provides instructions for maintainers of the `exemplar` repository on how to test, update, and manage the `copier` template generation infrastructure.
4
4
5
5
For instructions on how entirely *new* users should invoke the template template using `uvx` and `copier` to start a new project, see the [main README.md](../README.md).
6
6
@@ -10,7 +10,7 @@ The `exemplar` repository serves a dual purpose:
10
10
1. It is a fully functional, canonical Reference implementation of a Beman Library (the root codebase).
11
11
2. It contains the Jinja-based template used by downstream Beman projects (the `template/` directory).
12
12
13
-
To ensure that downstream templates are highly functional and that the template never falls out of sync with the reference implementation, we require that the `template/` output (`generating_exemplar=true`) perfectly recreates the root project repository, barring acceptable omissions.
13
+
To ensure that downstream templates are highly functional and that the template never falls out of sync with the reference implementation, we require that the `template/` output (`generating_exemplar=true`) perfectly recreates the root project repository, barring acceptable omissions.
14
14
15
15
## Utilities and Scripts
16
16
@@ -35,13 +35,13 @@ Performs a strict byte-for-byte validation ensuring that the `template/` generat
35
35
While `check_copier.sh` is tailored to the `exemplar` structure, this script provisions completely neutral, third-party libraries (`generating_exemplar=false`).
36
36
- Provisions instances utilizing different testing frameworks (e.g. `gtest` and `catch2`).
37
37
- Tests matrix conditions (e.g. C++ Modules on vs. off).
38
-
- Re-runs the CMake configure/build/ctest lifecycle on every variant to ensure downstream clients will not experience build breakages.
38
+
- Re-runs the CMake configure/build/ctest lifecycle on every variant to ensure downstream clients will not experience build breakages.
39
39
40
40
## Workflow: Updating the Templates
41
41
42
42
When you make changes to the C++ code, CMake infrastructure, or CI processes within `exemplar`, you must propagate those updates to the Copier template:
43
43
44
-
1.**Make changes in the canonical root directory.** Modify source, tests, workflows, etc., directly in the `exemplar` repository.
44
+
1.**Make changes in the canonical root directory.** Modify source, tests, workflows, etc., directly in the `exemplar` repository.
45
45
2.**Propagate via script:** Execute `./copier/update_templates.py`. This covers 90% of file replication seamlessly.
46
46
3.**Manually reconcile complex templates:** Look at the warnings generated by the Python script to see if structural Jinja templates (like `CMakeLists.txt.jinja` or `.github/CODEOWNERS.jinja`) require manual hand-editing.
47
47
4.**Validate Parity:** Run `./copier/check_copier.sh`. Continue fixing template logic until the script emits `Success: Template matches project exactly.`.
@@ -51,14 +51,14 @@ When you make changes to the C++ code, CMake infrastructure, or CI processes wit
51
51
52
52
The `copier` test scripts run in GitHub Actions underneath `ci_tests.yml`.
53
53
54
-
-**`check_copier.sh` fails in CI:**
55
-
You updated a file in the root repository (e.g. a submodule bump, a new workflow, modified C++) but forgot to update the corresponding `.jinja` file in the `template/` directory.
54
+
-**`check_copier.sh` fails in CI:**
55
+
You updated a file in the root repository (e.g. a submodule bump, a new workflow, modified C++) but forgot to update the corresponding `.jinja` file in the `template/` directory.
56
56
**Solution:** Pull the branch locally and run `./copier/update_templates.py`. Check for regressions using `./copier/check_copier.sh` and push.
57
57
58
58
-**`test_standard_project.sh` (or `copier-test` CI Job) fails:**
59
-
The `exemplar` generation works, but something breaks when the project generates for *other* people (`generating_exemplar=false`).
60
-
**Solution:** Check the specific variant that failed.
61
-
-*Did `catch2` break?* You might have modified `template/tests/beman/{{project_name}}/CMakeLists.txt.jinja` using `gtest` specifics that aren't guarded properly.
59
+
The `exemplar` generation works, but something breaks when the project generates for *other* people (`generating_exemplar=false`).
60
+
**Solution:** Check the specific variant that failed.
61
+
-*Did `catch2` break?* You might have modified `template/tests/beman/{{project_name}}/CMakeLists.txt.jinja` using `gtest` specifics that aren't guarded properly.
62
62
-*Did Modules break?* The CI test runs C++ modules using `ghcr.io/bemanproject/infra-containers-clang:latest`. Ensure the CMake module directives conditional branches haven't drifted.
63
-
63
+
64
64
Locally, you can simulate specific container behaviors by targeting a custom CMake preset or enabling actions mode: `GITHUB_ACTIONS=true ./copier/test_standard_project.sh llvm-release`.
0 commit comments