Re: [Tools-discuss] Template repository for GitHub

Martin Thomson <mt@lowentropy.net> Wed, 21 July 2021 02:35 UTC

Return-Path: <mt@lowentropy.net>
X-Original-To: tools-discuss@ietfa.amsl.com
Delivered-To: tools-discuss@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id AA9B13A0D3A for <tools-discuss@ietfa.amsl.com>; Tue, 20 Jul 2021 19:35:37 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -2.8
X-Spam-Level:
X-Spam-Status: No, score=-2.8 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=lowentropy.net header.b=IclRWWIv; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=BOwpn/7/
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id X296D492a7af for <tools-discuss@ietfa.amsl.com>; Tue, 20 Jul 2021 19:35:31 -0700 (PDT)
Received: from wout2-smtp.messagingengine.com (wout2-smtp.messagingengine.com [64.147.123.25]) (using TLSv1.2 with cipher ADH-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id F40523A0D38 for <tools-discuss@ietf.org>; Tue, 20 Jul 2021 19:35:30 -0700 (PDT)
Received: from compute5.internal (compute5.nyi.internal [10.202.2.45]) by mailout.west.internal (Postfix) with ESMTP id A097E32001BB; Tue, 20 Jul 2021 22:35:29 -0400 (EDT)
Received: from imap41 ([10.202.2.91]) by compute5.internal (MEProxy); Tue, 20 Jul 2021 22:35:29 -0400
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=lowentropy.net; h=mime-version:message-id:in-reply-to:references:date:from:to :subject:content-type; s=fm2; bh=blFSkN8AhtGNQqQe9dQcjkNj300hBfM xBq8eXfkOyRQ=; b=IclRWWIvchR/bOWlTH3YmQyegH99acb0m6AdnmvBYd8FPql KX57NKMZgesVWrztXa5UUJZn9wSJ7N1zIpKyewuh6MIAxkipuObE+dsQ72gvC4F/ 6RjF99KSPgCe8M1IGhsQCOunmZbtPQ06tgDrWWw8O/U1Rz3dB6dBNoUptA51eEJF O8r357XABuGGLGv/zWveMsDD5DyHSmmUEvyjZo44UKynaXTYYqjuGDwOYnbPVMT4 qavw2C2IGQEtBb5YlEO0hKb2adAbOv+X9o0SNIyqwrYQl4U6O1CYs7mLj2/cGSxl sAJSEdVDcud2ye48RP3uGo2PQBMJOgruIaZHguw==
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-type:date:from:in-reply-to :message-id:mime-version:references:subject:to:x-me-proxy :x-me-proxy:x-me-sender:x-me-sender:x-sasl-enc; s=fm3; bh=blFSkN 8AhtGNQqQe9dQcjkNj300hBfMxBq8eXfkOyRQ=; b=BOwpn/7/c1EgJ8f19Oz2LS MiaLZQx1Hi3GYmMJWzrCA3+tLHVQsrQ3nuFXYy5/tOyg0wYZa1Kea8Whvuvhg8Lo jp8/cBRObf+OvX03G2jazChIUJ2OKSxqx/e7eaGq87IHDgklQ4784xmMBCuYBd0e 1oJSQOX/v4N7sIQ94PE5dfIhchgG9ftuLWH+hyzmoWxKhsnNxboA5bjTJmhV21fO dY1VgSMTjrq/9rH6CwYRxmCJdyOgQrnwRdImeZccJQRhoSsgqUhK7t8OGohDechy dCNfGIE5ipyHSfaN8+FM1mCgP+R8I8b3jTwfErHgXK5eIege1lV/G24NaqY5INNA ==
X-ME-Sender: <xms:8If3YNLiLQJATQsSUA4RPiDtqCQXk4Vyxkexu1XxRWns5a25QEfAbw> <xme:8If3YJJb4KTuSdumIXLigC06G565H6-NM2GVC6Z_lRA6IU3T_5BvfswBF3Q9ZBp27 KbuFemVTXXnidc8szg>
X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrfeefgdehudcutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpefofgggkfgjfhffhffvufgtsehttdertderredtnecuhfhrohhmpedfofgrrhht ihhnucfvhhhomhhsohhnfdcuoehmtheslhhofigvnhhtrhhophihrdhnvghtqeenucggtf frrghtthgvrhhnpeekteeuieektdekleefkeevhfekffevvdevgfekgfeluefgvdejjeeg ffeigedtjeenucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhroh hmpehmtheslhhofigvnhhtrhhophihrdhnvght
X-ME-Proxy: <xmx:8If3YFuBxMOW5c-g087FNq9G-xgo2YczSoVKa_B9keI3--bpvuXzGQ> <xmx:8If3YOZBqlUMNXm5fWAZ_3wjGPoGoWqfuUADD4ZbzZyBrrgzU_mp3g> <xmx:8If3YEZ3_uCZahJoq5K8bDorNDMRA8RSk3FAL4wFQeB68KPukUP0rw> <xmx:8Yf3YK2uqfPHAHvp37Ig6ZCeLHieaLCW5jnCgLBQP3o2mJ_JJW69OA>
Received: by mailuser.nyi.internal (Postfix, from userid 501) id BC9583C0F5D; Tue, 20 Jul 2021 22:35:28 -0400 (EDT)
X-Mailer: MessagingEngine.com Webmail Interface
User-Agent: Cyrus-JMAP/3.5.0-alpha0-533-gf73e617b8a-fm-20210712.002-gf73e617b
Mime-Version: 1.0
Message-Id: <1f1a792d-fb21-4f01-8c5a-107570757e08@www.fastmail.com>
In-Reply-To: <da3ef933-0a21-c596-efeb-016333c7e4db@nostrum.com>
References: <5391988e-7180-49d3-989b-3cf40e395408@www.fastmail.com> <da3ef933-0a21-c596-efeb-016333c7e4db@nostrum.com>
Date: Wed, 21 Jul 2021 12:34:58 +1000
From: "Martin Thomson" <mt@lowentropy.net>
To: "Robert Sparks" <rjsparks@nostrum.com>, tools-discuss@ietf.org
Content-Type: text/plain
Archived-At: <https://mailarchive.ietf.org/arch/msg/tools-discuss/xKTLVvIX__dlBnHcbTrY3wSfc7k>
Subject: Re: [Tools-discuss] Template repository for GitHub
X-BeenThere: tools-discuss@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: IETF Tools Discussion <tools-discuss.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/tools-discuss/>
List-Post: <mailto:tools-discuss@ietf.org>
List-Help: <mailto:tools-discuss-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/tools-discuss>, <mailto:tools-discuss-request@ietf.org?subject=subscribe>
X-List-Received-Date: Wed, 21 Jul 2021 02:35:38 -0000

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.