From nobody Sun Aug 4 05:55:10 2019 Return-Path: X-Original-To: ietf-and-github@ietfa.amsl.com Delivered-To: ietf-and-github@ietfa.amsl.com Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 717F7120045 for ; Sun, 4 Aug 2019 05:55:09 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -2.001 X-Spam-Level: X-Spam-Status: No, score=-2.001 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_PASS=-0.001] autolearn=ham autolearn_force=no Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (1024-bit key) header.d=ericsson.com 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 YJUzRMlIVAIW for ; Sun, 4 Aug 2019 05:55:06 -0700 (PDT) Received: from EUR02-HE1-obe.outbound.protection.outlook.com (mail-eopbgr10042.outbound.protection.outlook.com [40.107.1.42]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 1868C12003E for ; Sun, 4 Aug 2019 05:55:05 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; s=arcselector9901; d=microsoft.com; cv=none; b=frZV7Pf4FBvleJ/EdVUcmZE2nq3h9ADjnT8J4eKwNPkQBe70K77rHqTaU2pDgkSE7AVlDz2WpU7RtY+JhUlHVoVURC+0WvihKycArJscnr8PIuInptRAhHGJl5JwGQxKplk/CD9LTzqgF3DxCOuu0HqJqOUsnI9Y9cUOkbYZ8Y0FlBVN6GG/HKyhgrdwGpo5PzHjiLQ9WoN9ugiIohk0ZZBkkTIR4/9e065eni3MGlmgkRd9YKHSN7hOShsA4US0POJQ8A7+tXvzkY+zZUV8ye3BFZkWkHfi0H/SAIdpp/kHPOKG/I7fdOHh7sC6ooj0mdeYJC5A/7MDn1zDXQhnVg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=microsoft.com; s=arcselector9901; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=lpIFq2DTdy+rYYqoKnRx/xH4dLPWvj217B3zmsGtp6c=; b=d9fCggf0L6I3NgJvgKxoyLksL2rKmriemxxhaIaX+z9YZkjT2thnBU6C41YVXYCiMPmw0uzEjWqeD5S+jglaMUD0e+WPhklSwE/d3KuUJuB3BWb1JpzdSFXiexn/KyhpJbjHu3aqnib3DwoAs7UL+KVzBfq3muLTRqUEV6z+1IuPQTbCwXOnboadOom6Wpqor+qEvjQGhW9ojE/GlsZaNLTxyaEnuukEjUSPTo18ol575SKWzrpiYsCklrUQDc9PVrHJq6LZ6vDQ8fo2NjUuMVGKdQiy/aEvfQd/ZelPiaeufCixFT3hCRUkz/GFDpugZzzgMWSNVZiXyyhG4NclEA== ARC-Authentication-Results: i=1; mx.microsoft.com 1; spf=pass smtp.mailfrom=ericsson.com; dmarc=pass action=none header.from=ericsson.com; dkim=pass header.d=ericsson.com; arc=none DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=ericsson.com; s=selector2; h=From:Date:Subject:Message-ID:Content-Type:MIME-Version:X-MS-Exchange-SenderADCheck; bh=lpIFq2DTdy+rYYqoKnRx/xH4dLPWvj217B3zmsGtp6c=; b=fpvm92WV5mltrjLSgFljmfLdG2k9E5CAxvnACSLUIAdpjpbYMQY9JxNF16NTw/mYG86IJ3E0jYoTtHcSYKfekkzAoVYlWp6aBUp/ZGK74g4BWaca2TVFCW2AEMUOXyAi6QjyUeqBv6Tz+kOB5WftLQFbYDDwHIekz07VJQue+Jo= Received: from HE1PR07MB3161.eurprd07.prod.outlook.com (10.170.245.23) by HE1PR07MB4426.eurprd07.prod.outlook.com (20.176.167.143) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.20.2157.11; Sun, 4 Aug 2019 12:55:03 +0000 Received: from HE1PR07MB3161.eurprd07.prod.outlook.com ([fe80::ec0d:f9d3:7159:ba7]) by HE1PR07MB3161.eurprd07.prod.outlook.com ([fe80::ec0d:f9d3:7159:ba7%6]) with mapi id 15.20.2136.018; Sun, 4 Aug 2019 12:55:03 +0000 From: Christer Holmberg To: "ietf-and-github@ietf.org" Thread-Topic: Comments on draft-ietf-git-using-github-00 Thread-Index: AdVHejPyioRISfyKSqWqlBOWkVVHMQ== Date: Sun, 4 Aug 2019 12:55:02 +0000 Message-ID: Accept-Language: en-US Content-Language: fi-FI X-MS-Has-Attach: X-MS-TNEF-Correlator: authentication-results: spf=none (sender IP is ) smtp.mailfrom=christer.holmberg@ericsson.com; x-originating-ip: [79.134.118.162] x-ms-publictraffictype: Email x-ms-office365-filtering-correlation-id: 3ac2bff2-fd1b-4279-ba1b-08d718daf79d x-microsoft-antispam: BCL:0; PCL:0; RULEID:(2390118)(7020095)(4652040)(8989299)(4534185)(4627221)(201703031133081)(201702281549075)(8990200)(5600148)(711020)(4605104)(1401327)(2017052603328)(7193020); SRVR:HE1PR07MB4426; x-ms-traffictypediagnostic: HE1PR07MB4426: x-microsoft-antispam-prvs: x-ms-oob-tlc-oobclassifiers: OLM:10000; x-forefront-prvs: 0119DC3B5E x-forefront-antispam-report: SFV:NSPM; SFS:(10009020)(4636009)(366004)(376002)(346002)(136003)(39860400002)(396003)(199004)(189003)(64756008)(256004)(66574012)(25786009)(790700001)(6116002)(316002)(14444005)(3846002)(71190400001)(71200400001)(2351001)(33656002)(8676002)(55016002)(81156014)(5640700003)(52536014)(26005)(2501003)(186003)(2906002)(76116006)(9326002)(53936002)(99286004)(54896002)(6306002)(14454004)(66476007)(5660300002)(6436002)(7696005)(74316002)(81166006)(8936002)(6916009)(66066001)(66946007)(478600001)(68736007)(102836004)(66556008)(66446008)(86362001)(9686003)(44832011)(7736002)(486006)(476003)(6506007); DIR:OUT; SFP:1101; SCL:1; SRVR:HE1PR07MB4426; H:HE1PR07MB3161.eurprd07.prod.outlook.com; FPR:; SPF:None; LANG:en; PTR:InfoNoRecords; A:1; MX:1; received-spf: None (protection.outlook.com: ericsson.com does not designate permitted sender hosts) x-ms-exchange-senderadcheck: 1 x-microsoft-antispam-message-info: q/EujHLjHWUrEvA7RToWMMbgEqluIM4V07LSUzyF33VxFJuBQwqzEiG/fZ7qJkXoqjKPKmGqKetE3BwcFvEYPTHMKkztR8b8kj1wGFAS26PLGXmHX7/Y0sJCVhSq7h3nF+d2aDQ2IIjjDbpvzceYxv6kHj90OKr/2wJ+J3YtH5knRJaanRMB1chPRuQbCimY23fm2lY3dJDSY1pDUKGIyjJDOfVyrm0RtGjD0Yim2ZBDL7b5L5SOiSYQI6mcHHMjiRtdljSZ3vHhfDw2q8ysIPiofMyQlqaLRO8TVVo66TTQ4nOSi98WWSR9sr/RcShOm/YGJpqg19kWvsIzftVT+wJ+mPd1IKgx7Mj7t4Dtdvx+omjYGY5GQcIcZLQIGKm0OSSjLiv3AxC6PucGIusKs9Us/cz/3TBV6dxwodJumyo= x-ms-exchange-transport-forked: True Content-Type: multipart/alternative; boundary="_000_HE1PR07MB31617EB0168EC768D0C791EA93DB0HE1PR07MB3161eurp_" MIME-Version: 1.0 X-OriginatorOrg: ericsson.com X-MS-Exchange-CrossTenant-Network-Message-Id: 3ac2bff2-fd1b-4279-ba1b-08d718daf79d X-MS-Exchange-CrossTenant-originalarrivaltime: 04 Aug 2019 12:55:02.1065 (UTC) X-MS-Exchange-CrossTenant-fromentityheader: Hosted X-MS-Exchange-CrossTenant-id: 92e84ceb-fbfd-47ab-be52-080c6b87953f X-MS-Exchange-CrossTenant-mailboxtype: HOSTED X-MS-Exchange-CrossTenant-userprincipalname: christer.holmberg@ericsson.com X-MS-Exchange-Transport-CrossTenantHeadersStamped: HE1PR07MB4426 Archived-At: Subject: [Ietf-and-github] Comments on draft-ietf-git-using-github-00 X-BeenThere: ietf-and-github@ietf.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Discussion of using GitHub in IETF activities, particularly for Working Groups" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 04 Aug 2019 12:55:10 -0000 --_000_HE1PR07MB31617EB0168EC768D0C791EA93DB0HE1PR07MB3161eurp_ Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: quoted-printable Hi, I have read the draft, and I have some comments. --- Section 1: The text says: "This document describes how the IETF uses GitHub through the development of Internet-Drafts. This concentrates on the work that occurs within IETF working groups. Recommendations for working groups and their chairs are made for integrating these tools with their processes." Q1_1: What is the meaning of this paragraph? The main purpose of the docume= nt is to give guidance when a WG decides to use GitHub, which is described = in the following paragraph, and in Section 1.4. --- Section 2: Q2_1: Does this section (including sub sections) belong to this document? T= o me it seems like it belongs to draft-ietf-git-github-wg-configuration, an= d e.g., section 2.1 is very similar to section 2.1 of draft-ietf-git-github= -wg-configuration-01. --- Section 3: The text says: "Chairs SHOULD involve Area Directors any decision to use GitHub for anythi= ng more than managing of drafts." Q3_1: I think the sentence belongs to Section 3.1. Q3_2: What exactly does "managing of drafts" mean? If it means using GitHub= for anything else than what is described in the draft, maybe it would be b= etter to say so? Q3_3: I also think that it would be good that the ADs are always informed a= bout a WG using GitHub, and how it is used. --- Section 3.2: Q3-2_1: I think it shall be a MUST to provide the information on how the WG= is going to use GitHub also in the repo (e.g., README/CONTRIBUTING). To me= the text now only says it's a good idea. --- Section 3.3: Q3-3_1: Does this section belong in to draft-ietf-git-github-wg-configurati= on? Q3-3_2: More generally, is there a need for draft-ietf-git-github-wg-config= uration to begin with? --- Section 3.5: Q3-5_1: I think it would be useful to point out that the document format ne= eds to be text based - at least if people are expected to provide pull requ= ests. Q3-5_2: I think it would be useful to point out that the WGs should choose = a document format that the community can be considered being familiar with = (unless the community agree on trying out something new). Also, in order to= contribute, the document format should not mandate the installation of lot= s of software, and it should be possible to contribute on any major OS. --- Section 4.1: Q4-1_1: I suggest to rename the section to "Issue Tracker". "Issues" should= be a section where it is described what to do, or whom to contact, if a WG= has problems with using GitHub etc :) Q4-1_2: Section 4.2 provides guidance on how pull requests are discussed, b= ut there is nothing similar for Issues. There are two way to discuss Issues= : in the Issue tracker, and on the list. --- Section 4.1.1: Q4-1-1_1: I think it would be useful to give examples of how labels have be= en used. Appendix A.2 describes how labels are used for the QUIC WG, so may= be adding a reference. --- Section 4.2: Q4-2_1: When a pull request is created, I think one should always provide s= ome background data on what triggered the pull request. If there is a GitHu= b issue and/or email discussion associated with the pull request I think it= would be good to include a link to the issue/email discussion. If there is= a meeting discussion associated with the pull request I think it would be = good to include a link to the minutes. Q4-2_2: This question is not only related to pull requests, but to the usag= e of branches in general. Unless I've missed it, the document does not talk= about usage of branches (apart from the ones used for pull requests). The = text mentions the "master" branch. So, is the assumption that the work (pul= l requests etc) is always going to be done against the "master" branch? Wha= t if a WG wants to create a separate branch for each new version of a draft= , submit all pull requests etc against that branch, and then merge that bra= nch with the master once the new version of the draft has been submitted? T= hat way the master branch would always reflect the latest version of the dr= aft. I am not saying whether that is better or worse, but the document curr= ently doesn't say anything about it. The document either needs to specify h= ow branches are used, or specify that the WG chairs need to decide how bran= ches are used within their WG. --- Section 4.2.2: Q4-2-2_1: I think it would be good to inform the community (using the WG ma= iling list) when a pull request is about to be merged - especially if it's = related to a technical topic, and/or a topic that has triggered lots of dis= cussions. Q4-2-2_2: I agree with the statement saying that a merge does not always ne= cessarily need to reflect WG consensus. However, I do think that it should = be possible (e.g., using git tags) to find the revision that is associated = with a given version of a draft. --- Section 5: Q5_1: Is there something GitHub specific with this section? To me it looks = like normal IETF procedures. The text says: "Editors SHOULD create a new Internet-Draft submission two weeks prior to e= very session (see Section 7.1 of [RFC2418])." Q5_2: This is not how I read 2418. It says that all information shall be av= ailable two weeks prior to every session. That may of course include submit= ting a new version of a draft, but that depends on whether there is anythin= g new to submit. Q5_3: In my opinion, this section should talk about the GitHub specifics on= submitting a new version. For example, how/if a new version can be submitt= ed if there are open Issues and/or pull requests. Q5_4: As indicated in Q4-2-2_2, when a revision is used for a new draft ver= sion I think it should be properly marked/tagged. Q5_5: When a new draft version is submitted, would it be useful to include = links to all pull requests that have been merged for the new draft version?= This makes it easier in future to look back when/why/if certain changes we= re doing. ---- Regards, Christer --_000_HE1PR07MB31617EB0168EC768D0C791EA93DB0HE1PR07MB3161eurp_ Content-Type: text/html; charset="us-ascii" Content-Transfer-Encoding: quoted-printable

Hi,

 

I have read the draft, and I have some comments.

 

---

 

Section 1:

 

The text says:

 

    “This document describes ho= w the IETF uses GitHub through the

   development of Internet-Drafts.  T= his concentrates on the work that

   occurs within IETF working groups. = ; Recommendations for working

   groups and their chairs are made for in= tegrating these tools with

   their processes.”

 

Q1_1: What is the meaning of this paragraph? The mai= n purpose of the document is to give guidance when a WG decides to use GitH= ub, which is described in the following paragraph, and in Section 1.4.=

 

---

 

Section 2:

 

Q2_1: Does this section (including sub sections) bel= ong to this document? To me it seems like it belongs to draft-ietf-git-gith= ub-wg-configuration, and e.g., section 2.1 is very similar to section 2.1 o= f draft-ietf-git-github-wg-configuration-01.

 

---

 

Section 3:

 

The text says:

 

“Chairs SHOULD involve Area Directors any deci= sion to use GitHub for anything more than managing of drafts.”

 

Q3_1: I think the sentence belongs to Section 3.1.

 

Q3_2: What exactly does “managing of drafts= 221; mean? If it means using GitHub for anything else than what is describe= d in the draft, maybe it would be better to say so?

 

Q3_3: I also think that it would be good that the AD= s are always informed about a WG using GitHub, and how it is used.

 

---

 

Section 3.2:

 

Q3-2_1: I think it shall be a MUST to provide the in= formation on how the WG is going to use GitHub also in the repo (e.g., READ= ME/CONTRIBUTING). To me the text now only says it’s a good idea.=

 

---

 

Section 3.3:

 

Q3-3_1: Does this section belong in to draft-ietf-gi= t-github-wg-configuration?

 

Q3-3_2: More generally, is there a need for draft-ie= tf-git-github-wg-configuration to begin with?

 

---

 

Section 3.5:

 

Q3-5_1: I think it would be useful to point out that= the document format needs to be text based – at least if people are = expected to provide pull requests.

 

Q3-5_2: I think it would be useful to point out that= the WGs should choose a document format that the community can be consider= ed being familiar with (unless the community agree on trying out something = new). Also, in order to contribute, the document format should not mandate the installation of lots of softwar= e, and it should be possible to contribute on any major OS.

 

---

 

Section 4.1:

 

Q4-1_1: I suggest to rename the section to “Is= sue Tracker”. “Issues” should be a section where it is de= scribed what to do, or whom to contact, if a WG has problems with using Git= Hub etc :)

 

Q4-1_2: Section 4.2 provides guidance on how pull re= quests are discussed, but there is nothing similar for Issues. There are tw= o way to discuss Issues: in the Issue tracker, and on the list.<= /p>

 

---

 

Section 4.1.1:

 

Q4-1-1_1: I think it would be useful to give example= s of how labels have been used. Appendix A.2 describes how labels are used = for the QUIC WG, so maybe adding a reference.

 

---

 

Section 4.2:

 

Q4-2_1: When a pull request is created, I think one = should always provide some background data on what triggered the pull reque= st. If there is a GitHub issue and/or email discussion associated with the = pull request I think it would be good to include a link to the issue/email discussion. If there is a meeting dis= cussion associated with the pull request I think it would be good to includ= e a link to the minutes.

 

Q4-2_2: This question is not only related to pull re= quests, but to the usage of branches in general. Unless I’ve missed i= t, the document does not talk about usage of branches (apart from the ones = used for pull requests). The text mentions the “master” branch. So, is the assumption that the work (pull= requests etc) is always going to be done against the “master” = branch? What if a WG wants to create a separate branch for each new version= of a draft, submit all pull requests etc against that branch, and then merge that branch with the master once the new version of the dra= ft has been submitted? That way the master branch would always reflect the = latest version of the draft. I am not saying whether that is better or wors= e, but the document currently doesn’t say anything about it. The document either needs to specify how branches a= re used, or specify that the WG chairs need to decide how branches are used= within their WG.

 

---

 

Section 4.2.2:

 

Q4-2-2_1: I think it would be good to inform the com= munity (using the WG mailing list) when a pull request is about to be merge= d – especially if it’s related to a technical topic, and/or a t= opic that has triggered lots of discussions.

 

Q4-2-2_2: I agree with the statement saying that a m= erge does not always necessarily need to reflect WG consensus. However, I d= o think that it should be possible (e.g., using git tags) to find the revis= ion that is associated with a given version of a draft.

 

---

 

Section 5:

 

Q5_1: Is there something GitHub specific with this s= ection? To me it looks like normal IETF procedures.

 

The text says:

 

“Editors SHOULD create a new Internet-Draft su= bmission two weeks prior to every session (see Section 7.1 of [RFC2418]).&#= 8221;

 

Q5_2: This is not how I read 2418. It says that all = information shall be available two weeks prior to every session. That may o= f course include submitting a new version of a draft, but that depends on w= hether there is anything new to submit.

 

Q5_3: In my opinion, this section should talk about = the GitHub specifics on submitting a new version. For example, how/if a new= version can be submitted if there are open Issues and/or pull requests.

 

Q5_4: As indicated in Q4-2-2_2, when a revision is u= sed for a new draft version I think it should be properly marked/tagged.

 

Q5_5: When a new draft version is submitted, would i= t be useful to include links to all pull requests that have been merged for= the new draft version? This makes it easier in future to look back when/wh= y/if certain changes were doing.

 

----

 

Regards,

 

Christer

 

--_000_HE1PR07MB31617EB0168EC768D0C791EA93DB0HE1PR07MB3161eurp_-- From nobody Mon Aug 19 00:24:36 2019 Return-Path: X-Original-To: ietf-and-github@ietfa.amsl.com Delivered-To: ietf-and-github@ietfa.amsl.com Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id 36ABB120233 for ; Mon, 19 Aug 2019 00:24:35 -0700 (PDT) X-Virus-Scanned: amavisd-new at amsl.com X-Spam-Flag: NO X-Spam-Score: -2.701 X-Spam-Level: X-Spam-Status: No, score=-2.701 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-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=kjRjja9q; dkim=pass (2048-bit key) header.d=messagingengine.com header.b=mitawzSi 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 f4naeNxYNLPS for ; Mon, 19 Aug 2019 00:24:32 -0700 (PDT) Received: from out2-smtp.messagingengine.com (out2-smtp.messagingengine.com [66.111.4.26]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 7E93112022A for ; Mon, 19 Aug 2019 00:24:32 -0700 (PDT) Received: from compute1.internal (compute1.nyi.internal [10.202.2.41]) by mailout.nyi.internal (Postfix) with ESMTP id EDABF21EC3 for ; Mon, 19 Aug 2019 03:24:30 -0400 (EDT) Received: from imap2 ([10.202.2.52]) by compute1.internal (MEProxy); Mon, 19 Aug 2019 03:24:30 -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:content-transfer-encoding; s=fm3; bh=YtH9t JBQ247toocOiCg3rcf3dJNu1YaMgiSrhepHHiU=; b=kjRjja9qhVR+3FINsk98H rASM+LEzP570l6P+tI860ZYMQ/TmhCT9EsprAju2s4qjLr8nWHCe9VXj6ME9wUkz uDoz+X+VvzNrFEStsIYVIoIdx23sBaeQuUT0kFlM3i0LBF2AdvQqVgtyeEO5Euc3 Xs6LeCVAYl6tzyu+/fDgozV44bkyv9LMVD+y0OI93i2LFh6KocfgNlU4yPrrE0Ow GN0MrnB9SPIIMPma9oP1qyfE+zAmi3LXbi6nOtfWOBLo8Bu1QbTFCrtan8QuUBBT eFLItLSfejSE3Ar8aC5rIM9f6jDfSZBETbO1kIEnho/19aOeQFhhN0sOe91Yy696 A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=content-transfer-encoding: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=YtH9tJBQ247toocOiCg3rcf3dJNu1YaMgiSrhepHH iU=; b=mitawzSij8vpCAg7OBzNSs/ks17ReggOObAD9fcBDEKX1ZKTkSkcFWiYJ QobSMjgylVsjKy2Om7SWt7c6WTDqlRNb1D3rERKMNxSveA0Ex4UtSNLyODI4vewn /iT0U2vmUFdpHhuJgzlp2bhO+Ri5gFKeuUNIOmWVegfvM5Fo3RXjr8v3OdjKlorT zdM27bCZBgY5zhzAUxbKKkdD45N5YxOzsoZ/Dyu91lcgRq1Bn+53+BQEEPuCcVpR vkw60WJq09L6304JzKxmF7qxFA+O83VWS1rW5hlLC3GCJlsVNUQdXCW19Qyk9Ll2 0J133OTfq/uGpaBOd114S3VCU/E4A== X-ME-Sender: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeduvddrudefkedguddukecutefuodetggdotefrod ftvfcurfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfgh necuuegrihhlohhuthemuceftddtnecuogfuuhhsphgvtghtffhomhgrihhnucdlgeelmd enucfjughrpefofgggkfgjfhffhffvufgtgfesthhqredtreerjeenucfhrhhomhepfdfo rghrthhinhcuvfhhohhmshhonhdfuceomhhtsehlohifvghnthhrohhphidrnhgvtheqne cuffhomhgrihhnpehgihhthhhusgdrihhopdhgihhthhhusgdrtghomhenucfrrghrrghm pehmrghilhhfrhhomhepmhhtsehlohifvghnthhrohhphidrnhgvthenucevlhhushhtvg hrufhiiigvpedt X-ME-Proxy: Received: by mailuser.nyi.internal (Postfix, from userid 501) id 8F61DE00A3; Mon, 19 Aug 2019 03:24:30 -0400 (EDT) X-Mailer: MessagingEngine.com Webmail Interface User-Agent: Cyrus-JMAP/3.1.6-877-g11309a8-fmstable-20190819v1 Mime-Version: 1.0 Message-Id: <223da1fa-8f2e-4334-9899-87bd0b9af9fd@www.fastmail.com> In-Reply-To: References: Date: Mon, 19 Aug 2019 17:24:30 +1000 From: "Martin Thomson" To: ietf-and-github@ietf.org Content-Type: text/plain;charset=utf-8 Content-Transfer-Encoding: quoted-printable Archived-At: Subject: Re: [Ietf-and-github] Comments on draft-ietf-git-using-github-00 X-BeenThere: ietf-and-github@ietf.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Discussion of using GitHub in IETF activities, particularly for Working Groups" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 19 Aug 2019 07:24:35 -0000 Thanks for reviewing Christer, and apologies for taking so long to get b= ack to this. On Sun, Aug 4, 2019, at 22:55, Christer Holmberg wrote: > Q1_1: What is the meaning of this paragraph? The main purpose of the=20= > document is to give guidance when a WG decides to use GitHub, which is= =20 > described in the following paragraph, and in Section 1.4. This paragraph is to explain the purpose of the document. I've reworded= in my copy slightly. > Q2_1: Does this section (including sub sections) belong to this=20 > document? To me it seems like it belongs to=20 > draft-ietf-git-github-wg-configuration, and e.g., section 2.1 is very=20= > similar to section 2.1 of draft-ietf-git-github-wg-configuration-01. I've started the process of cutting this out. There are probably still = a few items in an ambiguous state between the two drafts, but we'll sort= that out in time. > Q3_3: I also think that it would be good that the ADs are always=20 > informed about a WG using GitHub, and how it is used. Yeah. > Q3-2_1: I think it shall be a MUST to provide the information on how=20= > the WG is going to use GitHub also in the repo (e.g.,=20 > README/CONTRIBUTING). To me the text now only says it=E2=80=99s a good= idea. Yep. > Q3-3_1: Does this section belong in to draft-ietf-git-github-wg-config= uration? I don't think so. Though it's not clear where the line between these do= cs will end up. > Q3-3_2: More generally, is there a need for=20 > draft-ietf-git-github-wg-configuration to begin with?=20 It might be that that document never gets published. It's a very target= ed set of instructions that might not have value as something on permane= nt record. Once we have tools in place, embedding practices in those to= ols is probably more valuable than in the RFC series. But that's just m= y opinion. > Q3-5_1: I think it would be useful to point out that the document=20 > format needs to be text based =E2=80=93 at least if people are expecte= d to=20 > provide pull requests. Definitely. I can't think of anything worse than having to deal with a = pull request on a PDF. > Q3-5_2: I think it would be useful to point out that the WGs should=20= > choose a document format that the community can be considered being=20= > familiar with (unless the community agree on trying out something new)= .=20 > Also, in order to contribute, the document format should not mandate=20= > the installation of lots of software, and it should be possible to=20 > contribute on any major OS. There's a host of things that might be said about accessibility here. I= 've changed this to be a little more assertive about using markdown, but= I don't want to over-rotate and prescribe something too closely. A com= mon format for content is probably sufficient. And none of the tools we= currently use have portability issues (even if installation on some pla= tforms can leave a little to be desired). > Q4-1_1: I suggest to rename the section to =E2=80=9CIssue Tracker=E2=80= =9D. =E2=80=9CIssues=E2=80=9D=20 > should be a section where it is described what to do, or whom to=20 > contact, if a WG has problems with using GitHub etc :) Done. > Q4-1_2: Section 4.2 provides guidance on how pull requests are=20 > discussed, but there is nothing similar for Issues. There are two way=20= > to discuss Issues: in the Issue tracker, and on the list. That's the subject of new material. See https://github.com/ietf-gitwg/= using-github/pull/15 > Q4-1-1_1: I think it would be useful to give examples of how labels=20= > have been used. Appendix A.2 describes how labels are used for the QUI= C=20 > WG, so maybe adding a reference. The above new work has more on that. > Q4-2_1: When a pull request is created, I think one should always=20 > provide some background data on what triggered the pull request. If=20= > there is a GitHub issue and/or email discussion associated with the=20= > pull request I think it would be good to include a link to the=20 > issue/email discussion. If there is a meeting discussion associated=20= > with the pull request I think it would be good to include a link to th= e=20 > minutes. Done. > Q4-2_2: This question is not only related to pull requests, but to the= =20 > usage of branches in general. Unless I=E2=80=99ve missed it, the docum= ent does=20 > not talk about usage of branches (apart from the ones used for pull=20= > requests). The text mentions the =E2=80=9Cmaster=E2=80=9D branch. So, = is the assumption=20 > that the work (pull requests etc) is always going to be done against=20= > the =E2=80=9Cmaster=E2=80=9D branch? What if a WG wants to create a se= parate branch for=20 > each new version of a draft, submit all pull requests etc against that= =20 > branch, and then merge that branch with the master once the new versio= n=20 > of the draft has been submitted? That way the master branch would=20 > always reflect the latest version of the draft. I am not saying whethe= r=20 > that is better or worse, but the document currently doesn=E2=80=99t sa= y=20 > anything about it. The document either needs to specify how branches=20= > are used, or specify that the WG chairs need to decide how branches ar= e=20 > used within their WG. I don't think that we need to make too many recommendations there. I'd = rather concentrate on the one branch and let people who want to do speci= al things work out how to do that on their own. I've added a disclaimer= about that. > Q4-2-2_1: I think it would be good to inform the community (using the=20= > WG mailing list) when a pull request is about to be merged =E2=80=93 e= specially=20 > if it=E2=80=99s related to a technical topic, and/or a topic that has = triggered=20 > lots of discussions. This is part of the new stuff (https://github.com/ietf-gitwg/using-githu= b/pull/15) too. > Q4-2-2_2: I agree with the statement saying that a merge does not=20 > always necessarily need to reflect WG consensus. However, I do think=20= > that it should be possible (e.g., using git tags) to find the revision= =20 > that is associated with a given version of a draft. I've added that. Thanks. > Q5_1: Is there something GitHub specific with this section? To me it=20= > looks like normal IETF procedures. I've taken some of your suggestions, which means that it isn't really as= bereft of useful information as before. > Q5_5: When a new draft version is submitted, would it be useful to=20 > include links to all pull requests that have been merged for the new=20= > draft version? This makes it easier in future to look back when/why/if= =20 > certain changes were doing. I didn't include this. I think that policies about where to find change= logs are a per-working group thing. We meticulously build them for QUI= C and it's annoying to do so, even if it's a valuable service editors pr= ovide. Everyone will have to make their own call. You can find updated drafts (and proposal text) here: https://ietf-gitwg= .github.io/using-github/