Re: [Tools-discuss] Template repository for GitHub

[Martin Thomson <[e-mail]>]

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.

On Wed, Jul 21, 2021, at 08:16, Robert Sparks wrote:
> 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?)

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

> * 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 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.

> * 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

Yep, that's something a comment might help.

> * 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.

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.

> * The run fail messages are really going to scare someone new (to 
> 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.

> * 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'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.

> * 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?)

I'll fix that.

> * 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?

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.