Convert repository to GitHub Template

[slackline]

Hi,

Only came across Manubot recently, can't believe its taken me so long, it looks ideal and the automatic handling of links/citations is really neat.

Having this repository as a template is incredibly useful and makes getting things up and running really simple.

I was wondering though whether it would be worth making this repository a template repository to simplify even further the process of using it as a basis for others to use.

It wouldn't negate people forking the repository to make contributions but would mean that those using the repository wouldn't inherit the history when they use the Template.

[agitter]

Thanks for the suggestion @slackline. The manubot Python package currently assumes that the full rootstock repository commit history is available (#398). We briefly experimented with squashing commits (#65) and alternate configurations, but currently we find it easiest to update a Manubot manuscript with the latest rootstock updates if the full rootstock commit history is there.

Ultimately we agree that a template repository would be a more user-friendly. There is a placeholder repository with an issue outlining some thoughts in that direction (manubot/template#1). It isn't under active development recently, but I would still like to see us move in that direction someday.

[slackline]

Ah, sorry for not searching for past issues and digging those up, thanks for the pointer.

I hadn't thought about keeping forks up-to-date with master from which they had branched which with a template based approach would be trickier.

I'll keep an eye on things as I investigate and find out more about Manubot, know a bit of Python so might even be able to contribute.

Cheers,

@slackline

[agitter]

Part of my reason for linking those old issues is that there wasn't any single consolidated place to discuss GitHub templates, and it was hard to find old related issues. This issue will be easier to find via search.

We're happy to use issues to discuss how Manubot works or potential contributions.

[castedo]

@agitter It might be of interest the way I am using a repository template for a knock-off of manubot (roughtly speaking) [1].

I am using a very minimal template [1] together with a GitHub Action [2]. The .github/workflows file in the template [1] points to the GitHub Action [2]. Most of the logic is in the GitHub Action (well technically it's in an OCI/Docker image [4], but that is another thread).

There is no flow of template updates to repositories created from the template. The template content is very simple and mostly "throw-away" example stuff. The reusable complicated stuff stays in the GitHub Action which is versioned via git tags. So consumers point to particular git tag of the action and can upgrade by pointing to a new git tag of the action rather than merging updates from a rootstock.

Another nice feature is the URL params to this form page URL:

https://github.com/new?template_owner=castedo&template_name=basecastbot-example

So it makes it really easy to have a big button in docs (like in [3]) that lead the visitor to a standard GitHub form to create a repo from the template and the template fields get pre-populated.

A less obvious feature of GitHub Actions worth pointing out is that dependents (users/clients) of the GitHub Action are reported in GitHub Insights. This provides a benefit like that of seeing how many forks there are of a non-template rootstock.

I'm optimistic this template+action approach will work well.

Thank you for Manubot; it is a major inspiration!

[1] https://github.com/castedo/basecastbot-example/
[2] https://github.com/castedo/basecast-build-action/
[3] https://baseprints.singlesource.pub/basecast/
[4] https://gitlab.com/castedo/basecast/-/tree/main/oci_images