Subject: [Tools-discuss] Template repository for GitHub

From: "Martin Thomson" <[email-masked]>
Date: Fri, 16 Jul 2021 13:14:04 +1000

Hey,

Anyone who has setup a new GitHub repository for an Internet-Draft knows that it can be a little tricky, particularly if you use the toolchain I support.

Not any more.  I've created a template repository that makes setup very simple.  Just create a new repository using the template, rename your draft, enable GitHub Pages, and you are ready to go.

You can run all of this from the web UI that GitHub provides.  That includes publishing drafts to datatracker, which is done by creating a release[*].

Some credit here is owed to Mallory Knodel for complaining loudly enough about how unfriendly this whole setup was and motivating me to spend a couple of hours on finally doing this.

Documentation here:
https://github.com/martinthomson/i-d-template/blob/main/doc/TEMPLATE.md

As always contributions and bug reports are welcome.

Cheers,
Martin

[*] This bit isn't completely tested yet, I'll confess.

---

From: Michael Richardson <[email-masked]>
Date: Fri, 16 Jul 2021 12:19:15 -0400

Martin Thomson <[email-masked]> wrote:
    > Anyone who has setup a new GitHub repository for an Internet-Draft
    > knows that it can be a little tricky, particularly if you use the
    > toolchain I support.

    > Not any more.  I've created a template repository that makes setup very
    > simple.  Just create a new repository using the template, rename your
    > draft, enable GitHub Pages, and you are ready to go.

So, as I understand it, this is just an empty git repo that github provides
some sugar around it.  I could equally well glone the template to my computer
and git clone form there.

    > As always contributions and bug reports are welcome.

I'd like to contribute a template for work with YANG models.
That assumes I get my process working to my satisfaction first :-)

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Robert Sparks <[email-masked]>
Date: Tue, 20 Jul 2021 17:16:19 -0500

Martin -

I tried to pretend I didn't know anything about IDs and started a new 
draft using this template, making some notes along the way. I'll share 
them here before they're lost. I don't think any of the points are quite 
cooked enough to go in as Issues, but if so, feel free to just transcode 
them or tell me to do so.

* A new person won't know about the -latest convention. Something should 
be really obvious in the startup that tells them to leave that part of 
the name alone (maybe as a comment block in the template?)

* Is it possible to have an initial workflow that asks the new author 
for the draft name and target wg at least and does the initial 
alteration of the template md for them, waiting to start the other 
actions (that would build that md) until that's already been done?

* Something that made it quickly clear what the stuff (kramdown-2629 
input) in the .md template is would help - I think a complete new person 
won't be able to find that soon enough to not walk away

* The enabling github pages step is not intuitive to github newbies. I 
don't know if there's enough control that an action could do that for 
them? (maybe that's on the other side of "get an api key"). If not, 
perhaps the documentation example could show the place they should touch 
in the default theme, and maybe words-circles-and-arrows to help with 
the handholding.

* The run fail messages are really going to scare someone new (to 
github) away. Maybe the above suggestion can help people avoid them.

* Would it be useful to start a "something broke, how do I fix it" FAQ? 
For instance, when I tried, the submission window was closed, so 
creating a release led to an expected failure. I've done this enough to 
know that I can delete that release and try to make another one when the 
window opens, but I don't think someone new would know to try that? 
Maybe the submission step could delete the release for them if the API 
returns an error? (Won't help for the "some other author cancelled the 
submission" possibility).

* I wonder when we should abstract the template examples away from real 
people? (Has Hannes ever had to reject (or otherwise chase) something he 
wasn't actually invovled in?)

* It will take someone awhile to find .note.xml and know what to do with 
it. The setup for a non-wg submission isn't obvious - maybe it could be 
made simpler for a complete newcomer?

RjS

On 7/15/21 10:14 PM, Martin Thomson wrote:
> ___________________________________________________________
> Tools-discuss mailing list - [email-masked]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [email-masked]
> * Report tools.ietf.org bugs to: [email-masked]
> * Report all other bugs or issues to: [email-masked]
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 21 Jul 2021 12:34:58 +1000

Thanks for taking the time Robert.

I'll see what can be done to improve the process, but there are some hard limits on what I can do here.  Maybe there will be some tricks we can employ to get around those roadblocks over time; I'm still learning how this all works.

> the name alone (maybe as a comment block in the template?)

A comment block in the template seems like the right way to deal with this.  I've done that.

> actions (that would build that md) until that's already been done?

Something like this might be possible, but in order to do something like that a lot of manual and awkward setup needs to be done first.  For instance, you can't just run a GitHub Action without a bunch of prior setup (cloning a repository that contains the repository, creating a personal access token, installing that token as a secret in that repository).  This is where I ended up.

> won't be able to find that soon enough to not walk away

Yep, that's something a comment might help.

> in the default theme, and maybe words-circles-and-arrows to help with 

I worked it out.  If you "Include all branches" when creating the repository from the template, this step isn't needed.  I've updated the instructions.

> github) away. Maybe the above suggestion can help people avoid them.

Yeah, I'm aware of how bad it is, but this is one of the hard constraints I hit.  I've deployed a trick (that should also allow the action to be used for people who just have drafts sitting in a repo) that will suppress one of those, but I can't do that for the others without a major rewrite and that's not feasible right now.  I'll open an issue to track it.

The fact that actions are effectively immutable (without user intervention from the command line) makes this a tough thing to manage.

> submission" possibility).

I've added something, but it will probably not be enough.  BTW, thanks for testing releases; I wasn't 100% confident about that, but it sounds like it worked as expected.

> wasn't actually invovled in?)

I'll fix that.

> made simpler for a complete newcomer?

Not sure what you mean by non-wg submission here.  If you mean that the output when the draft doesn't target a working group is poor, yes, that could be improved.  Most people won't need to worry about this file, though they are free to just delete it.  I've tweaked the construction slightly so it should appear to be less broken.