search

PreTeXtBook / pretext-codespace

A template for creating a PreTeXt project that runs in GitHub Codespaces
MIT License
10 stars 10 forks source link

Manage this template repo as part of the CLI release process #4

Closed StevenClontz closed 1 year ago

StevenClontz commented 1 year ago

This is one solution to the current problem that our devcontainers use different images and thus install different versions of SageMath.

But I think ultimately for 99% of users anything but the default container is useless given GitHub's current UI for Codespaces, so I think just having the Lite configuration and adding a button to PreTeXt-tools to install the extra stuff is the best solution anyway.

StevenClontz commented 1 year ago

Sort of related - maybe this codespace should do nothing but provision the latest version of PreTeXt CLI, which already manages its own codespace configuration? Then the Codespace needs to be rebuilt, but at least we won't have things out of sync? Hmm...

StevenClontz commented 1 year ago

Per edited title: I think the real solution here is that when we cut a CLI release, part of that process should be to create an automated update of this repository. That way we don't even have to do a new pretext new after the Codespace is provisioned, and the devcontainer stuff here matches exactly what pretext new does in the latest CLI release.

oscarlevin commented 1 year ago

I started working on this today and ran into two issues:

  1. The README file that gets generated with a pretext new will not be helpful for someone coming to the template repository, and it doesn't make sense to have have the template instructions copied over to the forked repository.
  2. Similarly, it would make sense to include a LICENSE on the template repository (current MIT) that is not an appropriate license for a book.
StevenClontz commented 1 year ago

  1. I think the README for this template repo should be the current instructions or similar. We can maintain what that looks like in https://github.com/PreTeXtBook/pretext-cli. What we can do is have our release action run pretext new, then copy over its README with the template repo README.

  2. For this, I'd add a postCreateCommand that deletes the LICENSE file. It's unclear to me what we should be doing to add a LICENSE for authors. I'm tempted to toss CC 4.0 BY-SA by default, though we should warn folks that they should review whether that's appropriate for their project.

oscarlevin commented 1 year ago

I agree with both those points, but I'm still not understanding how to manage this template and its LICENCE and README files with this workflow. Let me try to describe that workflow here:

  1. When we create a new release of the CLI, a GitHub action gets triggered that runs pretext new and commits those changes to this repository. Except that it doesn't commit changes to the README (and keeps the LICENCE from this repository).
  2. Thus this repository has the most recent book template files, the most recent .devcontainer/devcontainer.json (the same one that is created with pretext new). It also has a README with info about how to use the template (not a template for a README for a new book) and a MIT LICENCE for the template itself.
  3. When a user creates a new repository from this template, they get all those files. If they then create a codespace from that repository, it is provisioned according to devcontainer.json just like it would be after a user does a pretext init --refresh or pretext new.

So what happens to the README and LICENCE from the template? They are still there and need to be deleted/replaced/edited manually.

Or we maintain a separate postCreateCommand that does this. But then it will delete the LICENCE and swap the README every time a codespace is created.

So it seems like maybe a better workflow would be to tell the user they need to create a new pretext project right after creating a repo/codespace from the template. And make pretext new manage the LICENCE/README.

oscarlevin commented 1 year ago

Here is the plan: set up a workflow that updates this template every time the cli is deployed, and overwrite the readme with instructions.

Rename this pretext-template and create a pretext-demo with almost the same structure (but with new demo).

Also, we should use .devcontainer.json instead of having it in a folder.

oscarlevin commented 1 year ago

I've figured out how to create a github action that does what we want, but to commit to a different repository, we need to start a secret: the Personal Access Token assigned to this repo. That will require coordination with an owner of the repo, I believe, or maybe the owner of the organization.

StevenClontz commented 1 year ago

@rbeezer can you elevate Oscar and me in the PreTeXtBook organization to have sufficient permission for this?

oscarlevin commented 1 year ago

I got this figured out! Turns out I don't need an organization PAT, just mine, since I have push permissions I'm guessing (I made a "classic" token, not the per-repo token they are suggesting now.

So in the CLI repo, any time we run the deploy-stable action, it will trigger a second workflow (which you can also run manually) called deploy-codespace-template. That checks out this repo, installs the latest pretext, deletes the project.ptx so it can run pretext new -d ., and then finally uses git to revert the previous readme (and commits and pushes, of course).

Thanks @StevenClontz and @bjones1 for your help figuring this out.