Re: [Tools-discuss] Template repository for GitHub

[Robert Sparks <[e-mail]>]

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:
> 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.
>
> ___________________________________________________________
> Tools-discuss mailing list - [e-mail]
> This list is for discussion, not for action requests or bug reports.
> * Report datatracker and mailarchive bugs to: [e-mail]
> * Report tools.ietf.org bugs to: [e-mail]
> * Report all other bugs or issues to: [e-mail]
> List info (including how to Unsubscribe): https://www.ietf.org/mailman/listinfo/tools-discuss