Skip to content

Commit 339a75d

Browse files
ednolanednolan
committed
Add stamp.sh script for new libraries and README instructions
Previously, users needing to create a new Beman library properly would need to follow the following set of (undocumented) instructions: - Go to the 'exemplar' repo, click 'use this template,' click 'create a new repository' - create and checkout the new repository - `cd cookiecutter` - `python3 -m pip install cookiecutter` - `cookiecutter .` - Go through the prompts to populate the template - Copy the resulting directory somewhere outside of your repo - Blow away all the files in the repo (careful to include hidden files like .github while still including .git) and replace them with the contents of the directory that `cookiecutter` produced The new stamp.sh script now automates all but the first two above steps, and the new instructions in the README.md explain to users how to use it.
1 parent aa6b1a6 commit 339a75d

5 files changed

Lines changed: 136 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,47 @@
1+
# How to Use This Template
2+
3+
To create a new Beman library, first click the "Use this template" dropdown in the
4+
top-right and select "Create a new repository":
5+
6+
<table><tr><td>
7+
<img src="images/use-this-template.png" width="400px">
8+
</td></tr></table>
9+
10+
This will create a new repository that's an exact copy of exemplar. The next step is to
11+
customize it for your use case.
12+
13+
To do so, execute the bash script `stamp.sh`. This script will prompt for parameters like
14+
the new library's name, paper number, and description. Then it will replace your exemplar
15+
copy with a stamped-out template containing these parameters and create a corresponding
16+
git commit and branch:
17+
18+
```
19+
$ ./stamp.sh
20+
[1/8] project_name (my_project_name): example_library
21+
[2/8] maintainer (your_github_username): your_username
22+
[3/8] minimum_cpp_build_version (20):
23+
[4/8] paper (PnnnnRr): P9999R9
24+
[5/8] description (Short project description.):
25+
[6/8] godbolt_link (https://www.example.com):
26+
[7/8] Select library_type
27+
1 - interface
28+
2 - static
29+
Choose from [1/2] (1):
30+
[8/8] Select unit_test_library
31+
1 - gtest
32+
2 - catch2
33+
Choose from [1/2] (1):
34+
Switched to a new branch 'stamp'
35+
Successfully stamped out exemplar template to the new branch 'stamp'.
36+
Try 'git push origin stamp' to push the branch upstream,
37+
then create a pull request.
38+
```
39+
40+
From there, you can simply fill in all the remaining parts of the repository that are
41+
labeled 'todo'.
42+
43+
What follow is an example of a Beman library README.
44+
145
# beman.exemplar: A Beman Library Exemplar
246

347
<!--

‎cookiecutter/check_cookiecutter.sh‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,9 @@ function check_consistency() {
3636
cp "$script_dir"/../.github/workflows/static_exemplar_test.yml "$out_dir_path"/exemplar/.github/workflows
3737
cp "$script_dir"/../.github/workflows/catch2_exemplar_test.yml "$out_dir_path"/exemplar/.github/workflows
3838
cp "$script_dir"/../.github/workflows/todo_exemplar_test.yml "$out_dir_path"/exemplar/.github/workflows
39+
mkdir "$out_dir_path"/exemplar/images
40+
cp "$script_dir"/../images/use-this-template.png "$out_dir_path"/exemplar/images/use-this-template.png
41+
cp "$script_dir"/../stamp.sh "$out_dir_path"/exemplar/stamp.sh
3942
local diff_path
4043
diff_path=$(mktemp)
4144
diff -r "$script_dir/.." "$out_dir_path/exemplar" \

‎cookiecutter/{{cookiecutter.project_name}}/README.md‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,49 @@
1+
{% if cookiecutter._generating_exemplar %}
2+
# How to Use This Template
3+
4+
To create a new Beman library, first click the "Use this template" dropdown in the
5+
top-right and select "Create a new repository":
6+
7+
<table><tr><td>
8+
<img src="images/use-this-template.png" width="400px">
9+
</td></tr></table>
10+
11+
This will create a new repository that's an exact copy of exemplar. The next step is to
12+
customize it for your use case.
13+
14+
To do so, execute the bash script `stamp.sh`. This script will prompt for parameters like
15+
the new library's name, paper number, and description. Then it will replace your exemplar
16+
copy with a stamped-out template containing these parameters and create a corresponding
17+
git commit and branch:
18+
19+
```
20+
$ ./stamp.sh
21+
[1/8] project_name (my_project_name): example_library
22+
[2/8] maintainer (your_github_username): your_username
23+
[3/8] minimum_cpp_build_version (20):
24+
[4/8] paper (PnnnnRr): P9999R9
25+
[5/8] description (Short project description.):
26+
[6/8] godbolt_link (https://www.example.com):
27+
[7/8] Select library_type
28+
1 - interface
29+
2 - static
30+
Choose from [1/2] (1):
31+
[8/8] Select unit_test_library
32+
1 - gtest
33+
2 - catch2
34+
Choose from [1/2] (1):
35+
Switched to a new branch 'stamp'
36+
Successfully stamped out exemplar template to the new branch 'stamp'.
37+
Try 'git push origin stamp' to push the branch upstream,
38+
then create a pull request.
39+
```
40+
41+
From there, you can simply fill in all the remaining parts of the repository that are
42+
labeled 'todo'.
43+
44+
What follow is an example of a Beman library README.
45+
46+
{% endif %}
147
# beman.{{cookiecutter.project_name}}: {{cookiecutter.description}}
248

349
<!--

‎images/use-this-template.png‎

50.2 KB
Loading

‎stamp.sh‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
#!/usr/bin/env bash
2+
3+
{
4+
if [[ "$1" == "-h" || "$1" == "--help" ]] ; then
5+
cat <<-'EOF'
6+
stamp.sh -- beman exemplar template library creation tool
7+
8+
This script is intended to be run on a fork of exemplar.
9+
10+
It sets up cookiecutter, runs it on the cookiecutter template, replaces the
11+
repository's current contents with the result, runs pre-commit,
12+
switches to a new branch 'stamp', and creates a git commit.
13+
14+
All parameters are passed through to the cookiecutter invocation.
15+
EOF
16+
fi
17+
set -eu
18+
if ! type -P python3 >/dev/null ; then
19+
echo "Couldn't find python3 in PATH" >&2
20+
exit 1
21+
fi
22+
declare repo_dir=$(realpath $(dirname "$BASH_SOURCE"))
23+
cd "$repo_dir"
24+
declare cookiecutter_venv_path
25+
cookiecutter_venv_path=$(mktemp --directory --dry-run)
26+
python3 -m venv "$cookiecutter_venv_path"
27+
source "$cookiecutter_venv_path/bin/activate"
28+
python3 -m pip install cookiecutter pre-commit >& /dev/null
29+
declare cookiecutter_out_path
30+
cookiecutter_out_path=$(mktemp --directory)
31+
python3 -m cookiecutter "$repo_dir/cookiecutter" -o "$cookiecutter_out_path" "$@"
32+
git rm -rf . &>/dev/null
33+
cp -r "$cookiecutter_out_path"/*/. .
34+
git add . &>/dev/null
35+
pre-commit run --all-files &>/dev/null || true
36+
git add . &>/dev/null
37+
git checkout -b stamp
38+
git commit -q -m "Stamp out exemplar template"
39+
echo "Successfully stamped out exemplar template to the new branch 'stamp'."
40+
echo "Try 'git push origin stamp' to push the branch upstream,"
41+
echo "then create a pull request."
42+
rm -r "$cookiecutter_venv_path" "$cookiecutter_out_path"
43+
}; exit

0 commit comments

Comments
 (0)