Add workflow to cleanup after project was created from template

[LtdSauce]

PR was moved to cpp-best-practices/cpp_boilerplate_project#3.

[LtdSauce]

As an example i have created a project from my template here

One link in the readme is falsly changed. But i think it should be removed either way as it is only of interest in the template repository itself.

[lefticus]

@LtdSauce I'm very excited about this! I'm doing a reorg of the README on another branch which might solve the problem you have with the broken link. I'll get back to this in the next day or two

[codecov-commenter]

Codecov Report

Merging #197 (0982177) into main (687c3d2) will not change coverage. The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     cpp-best-practices/cpp_starter_project#197   +/-   ##
=======================================
  Coverage   80.00%   80.00%           
=======================================
  Files           3        3           
  Lines          30       30           
=======================================
  Hits           24       24           
  Misses          6        6           

Flag	Coverage Δ
Linux	?
Windows	80.00% <ø> (ø)
macOS	∅ <ø> (∅)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report at Codecov.

Legend - Click here to learn more Δ = absolute <relative> (impact), ø = not affected, ? = missing data Powered by Codecov. Last update 687c3d2...0982177. Read the comment docs.

[lefticus]

@LtdSauce let me know how I can help you get this wrapped up. I just resolved some merge conflicts that I created with my README reorganization.

I see how the split-up of the different types of starter_project definitely complicates things for you.

[LtdSauce]

I try catch up on the changes this weekend.

[lefticus]

I try catch up on the changes this weekend.

Just let me know if you want any help testing or anything.

[LtdSauce]

@lefticus my next step will be trying to find out if the Info that a project was created from a template (and which) is available insider a github workflow (the project on the github UI knows it... Hopefully we can get access to that info)

Without that info a merge from the boilerplate template into the starter template is likely to messup everything :/

When that info is available, changing the build badges should be straight forward and scalable to other templates. At least if both templates are inside the same github org or account.

Renaming the cmake project i would postpown until the above is working.

Sadly, i fear that i won't be able to get to my computer this weekend.

[lefticus]

@lefticus my next step will be trying to find out if the Info that a project was created from a template (and which) is available insider a github workflow (the project on the github UI knows it... Hopefully we can get access to that info)

Without that info a merge from the boilerplate template into the starter template is likely to messup everything :/

Ideally we would like that cleanup to work regardless of who owned the fork, too. So people can maintain their own forks easily.

I was thinking earlier that maybe this can all be simplified if we put some sort of marker or tag in the codebase, to make the replacement easier?

Or maybe if we have just a simple TEMPLATE_NAME file in the root that is the only thing that has to be updated for each fork?

[LtdSauce]

@lefticus the idea with the TEMPLATE_NAME file came to my mind too.

I am not sure if a github workflow can be disabled by the content of a file. That is the only caveat i can currently think of with the TEMPLATE_NAME file (besides maintaining another file)

Another idea i had was to put something like a "known_templates" variable inside the workflow itself.

When creating a fork of the template to create a new template from it, one has to append that list in their template.

But i think both solutions have the problem, that the workflow would remove itself bevor either changing the file or appending the list. The info if its a template could stop that behavior (if that is supported) because it will trigger as soon as the name of the project changes. So changing that should be done apart from github i think 🤔

[LtdSauce]

I have Updated the PR description with the goals. Currently nothing is checked as i don't know if anything got broken by the recent changes to the template.

@lefticus do you have anything to add to the goals?

[lefticus]

I added a few things plus one that's 1/2 goal 1/2 suggestion. Maybe we just provide a README-template.md that's specifically designed to be the replacement, and it has specific placeholder strings in it. It can be mv'd into position during the cleanup script, then script deletes itself and everything can move forward?

Update: I just did some quick grep'ing and I'm 99% sure that would be a clean way to do this.

put in placeholders that are "myorg/myproject" and leave the "myproject" that's currently in src and CMake files (or similar)

Then we know exactly what to regex replace

[LtdSauce]

Initialy i wanted to avoid the readme template as i thought maintaining another file would be tedious. But i can see that the readme for the template itself and the readme for the new project will have different scopes.

@lefticus do you think changing the build badges for new templates created from this template should be automated? I feal that this could be just handled inside a HOW_TO_CREATE_NEW_TEMPLATE file which explains where changes have to be made? I think that would be okay, because creating a new template should probably be done by cloning it locally, applying the changes and then pushing it to a new project template. What do you think?

[LtdSauce]

Maybe someday https://github.com/github/feedback/discussions/5336 will get implemented by github itself.

PS: i put that link into the PR description. Just for the record, as this is somehow a workaround.

[lefticus]

Yeah I think we're at risk for conflating two needs

1. easy ability to create a project from a template
2. easy ability to create a new template

Let's focus on the first one, and try to do it in a way that does make the second one harder than it needs to be.

I think for 1) we just need to:

• swap in the new README
• delete appropriate files in the to-do list
• swap out the placeholder project names with the sed script or similar

for 2) .... maybe we do just have a MAKING_A_NEW_TEMPLATE guide, like you suggest?

I guess it's possible for 2) to make a different action that tries to detect if it needs to fix up the template names?

But I think 1) should be our priority, so we don't get too far ahead of ourselves. Once that's working nicely, look at 2)

[LtdSauce]

Let's focus on the first one, and try to do it in a way that does make the second one harder than it needs to be.

Hopefully you have a typo there. Making it even harder seems a bit evil :D

I think for 1) we just need to:

• swap in the new README
• delete appropriate files in the to-do list
• swap out the placeholder project names with the sed script or similar

Agreed. I would put all files (and directories) that should be deleted in a seperate TO_DELETE file.

for 2) .... maybe we do just have a MAKING_A_NEW_TEMPLATE guide, like you suggest?

Agreed. And yes i'd probably do that in another PR. I had the idea to just enforce that new templates should have the "_template" suffix in their names :shrug: EDIT: not sure if it is possible to turn a project into a template using the github cli... If that is possible i would turn the created project into a template if the name contains the suffix and we are done :thinking:. A quick scan of the docs: its possible with the --template flag to the gh repo edit command.

[LtdSauce]

I would use the gh repo view command to extract the description and put it in the readme. With this we could have "commands" in the description...

[LtdSauce]

I extended an idea how to do automatic testing of the workflow to the goals.

[LtdSauce]

@lefticus i have worked on this a bit and updated the description with checkmarks i think i now have covered. The current result can be seen in this repo: https://github.com/LtdSauce/template-creation-test

I plan on using the github meta infos to determine if the repo is a template. If so the workflow should be run as a test. Currently this is done by checking if the project name equals the tempalte name (which is a hardcoded variable). If that is used, then it would be easy to focus on the template from template stuff in another PR. I decided to just use a variable inside the workflow instead of a file containing only the TEMPLATE_NAME.

[lefticus]

@LtdSauce Awesome, I love how it's looking so far.

One annoying request... how hard would it be to move this PR over to cpp_boilerplate_project?

Don't worry about the README.md changes, just stick to the templated files and ci run.

I'll review further shortly

[lefticus]

I see that other projects do use _template as a convention for projects like this (which I knew nothing about when I created it).

@aminya @ddalcino how do you feel about renaming each of these projects to "<>_template"

• to make it more explicit to the github users that these are templates
• to make it easier to correctly deploy this cleanup process

@LtdSauce if we do that, then it solves the 2 top remaining issues, right?

[LtdSauce]

@aminya @ddalcino how do you feel about renaming each of these projects to "<>_template"

• to make it more explicit to the github users that these are templates
• to make it easier to correctly deploy this cleanup process

@LtdSauce if we do that, then it solves the 2 top remaining issues, right?

@lefticus It would solve them. But i still would want to call the github api and extract the "is_template" field from the payload in my workflow... It feals a bit more explicit?

[LtdSauce]

@LtdSauce Awesome, I love how it's looking so far.

One annoying request... how hard would it be to move this PR over to cpp_boilerplate_project?

Don't worry about the README.md changes, just stick to the templated files and ci run.

I'll review further shortly

@lefticus i guess i can just open a new PR and sqaush merge these changes into it. It is only one line which references the starter_project.

[lefticus]

@lefticus It would solve them. But i still would want to call the github api and extract the "is_template" field from the payload in my workflow... It feals a bit more explicit?

I agree, but I think it creates a race condition.

If someone forks, then the actions might immediately execute, before they have the opportunity to press the "make this a template" button.

Since, AFAIK, there's no way to fork a template as another template. If I'm wrong, just ignore me here.

[LtdSauce]

@lefticus i had the idea to use the suffix as an indicator that the action should turn the project into a template (if not already) (see gh repo edit - - template). But after that use the "is_template" for everything else.

Because ultimatly the "is_template" field is the real indicator if it is a template. The suffix is more of "this is supposed to be a template". What do you think?

[lefticus]

So two workflows exist:

1. User forks template
   • _template name is automatically kept, there's no way around that
   • your process runs and converts fork into a template project
2. User uses template to create a project
   • _template name is probably not kept
   • your process runs, which swaps out template files, and fills in info from new project's description

In any case, if project already is_template, then no process runs.

Sounds like it should work

[LtdSauce]

In the first case it stays a template either way! Forking a template results in a template afaik.. 🤷‍♂️ (at least my fork is a template... And i cannot remember making it a template by hand 🤔)

Yes and for the second one the user has the option to chose if it should be a template or not by providing the suffix (or not)

[lefticus]

In the first case it stays a template either way! Forking a template results in a template afaik.. 🤷‍♂️

This whole time I assumed it did not. It's shockingly hard to test creating a fork, since there's no way to fork-and-rename at the same time. I have to keep creating/deleting in other organizations.

[LtdSauce]

Thats why i added the diff and the ls command... 😅

Just forked the boilerplate project and it stayed a project template. So that is verified.

[LtdSauce]

@lefticus i opened a PR in the boilerplate project with a little bit of cleaning done to the commits (and already got bitten by my unfinished action which cleaned up the project because i had forgotton to change the template name in the action).

I will work on the remaining issues in the new PR soon. I'll leave it to you if you want to close it. Maybe it can be reused later to merge the changes from the boilerplate into this project.

[lefticus]

I'm going to close this PR, since the other one on boiler_plate is open and looking great.