Draft: draft-ietf-git-using-github

Commentary: does this all seem reasonable ? ( If you would prefer to defer reviewing until we push a draft , that 's OK . ) 
 I 'm thinking maybe there needs to be a heavy , medium and light . This text describes medium and heavy -- not light . I 'll start writing what I think is light today . The main problem is y' all are coming at this from the perspective of people with considerable GitHub expertise and comfort - level . I 'm coming at it from a perspective of " I 've no clue what I 'm doing ; it 's all magic . " Where there is one person like me , there are many . 
 Sounds good . I am probably incapable of seeing what a truly light option looks like . 
 Since proposing text to extend what 's in an un - merged PR is something I 'm really not comfortable with doing , I 'll just paste here what I was thinking about ultra - light . There are varying levels of GitHub expertise in IETF . It can not be assumed that ADs , chairs , authors or contributors have an existing login to GitHub or have ever used it . For some WGs , it may make sense to start with an ultra - light approach to using GitHub . This would allow draft authors to make use of basic GitHub functionality and allow WG chairs to get some initial experience ( if this is the level they are at in their GitHub journey ) . Independent of experience or knowledge , this approach may also be useful for a WG happy with its current way of doing work , that would like to make use of GitHub as a very simple tool to enhance existing methods of collaboration . GitHub can be used in an " ultra - light " manner by setting it up primarily for use by draft authors . They can use issues and comments to discuss the draft among themselves , and they can use it to provide WG members with a preview " Editor 's Copy " to confirm on - list comments have been adequately resolved ( prior to submitting to Datatracker ) . All WG discussion happens on the email list . Using GitHub in this manner is simplest if each draft has its own repository . The repository can be set up with the authors as a team with Write access . They can decide among themselves how they want to work . All other GitHub members have Read access . The WG is informed of the existence of the repository , but told that all issues are to be discussed on the list . The authors can choose to make full use of the available tools for automating processes , or manually perform Datatracker submissions and GitHub pages . If the draft is written using XML , it is even possible to avoid installing any tools . The on - line version of xml2rfc can be used to check the draft , and the GitHub UI can be used to upload draft versions . For users of Microsoft Windows , it is also possible to use to interact with GitHub for for all aspects of ultra - light interaction . 
 the proposed " Ultra Light " profile seems mostly the same as what  provides . I would remove all content regarding document editing and submission ( last paragraph ) , as it does not pertain to the purpose of this WG document . I might also move the contents of your first paragraph to the " Typical Working Group Policies " section in Martin 's change . That 's where information about choosing which mode is right seems best fit . what do you think ? please have a look . 
 In looking at this , I realize that there is a progressive thing at play more than we have a discrete " modes " of engagement . At the lightest end , we have people who just throw stuff up on GitHub as some place stable to keep some files . And that can progress to having issue tracking there for editor convenience , all the way to having the working group actively relying on the tracker . As people get more familiar with how things work , then you see more demand and use . I 'm wondering whether we should try to shave this down further and try to describe how the progression might work , recognizing that every group will have its own sweet spot on that and that is OK . 
 In principle , I think this is a fine idea . GitHub usage is certainly a spectrum , and defining that spectrum will be challenging . Maybe we can describe this concept loosely in the { { modes } } introduction to start ? 
 Perhaps the main difference between what  is suggesting and what  wrote is the expectation about issue discussion and resolution . I think the " ultra - light " description assumes no one will be opening issues aside from document editors , in which case the bit about having to be vigilant to return issue discussion to the list does n't really apply because the editors are just using the issue tracker for their own purposes . One further step in the progression is when WG participants start opening issues themselves , at which point someone needs to be responsible for directing discussion to the venue the WG has chosen ( issues vs. mailing list ) . Maybe this could be reflected in the description of the spectrum . 
 That seems reasonable to me . I do worry of us trying to enumerate each option in the spectrum , though , as there are undoubtedly many GitHub knobs to turn ! 
 Agreed , just focusing on the key differences in how a WG can engage with GitHub is sufficient . I do think this question of who is expected to file issues is one of them . 
 Thanks for all demonstrating how hard it is to avoid discussing things on pull requests :) Seriously though , that was very useful feedback . I 've tweaked this section to move it to three processes , with the third being considerably more complex . I hope that is clearer now . 
 can you please have a look at the latest changes ? I think this is ready to go . 
 Also requesting review from and if you have time . :-) 
 This looks good to me . "  " is an excellent way of talking / thinking about the styles of interaction , and much less " opinionated " ( ? ) than light / heavy / xxl . 
 Seems like a good start . I suspect all of this is going to evolve , but no harm in writing it down . Overall , I think this is a good way to frame it .
Paragraph (version A):
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.
Paragraph (version A):
This document is meant as an enhancement to RFC 2418 RFC2418.  It
provides guidance to working group chairs and participants on how
they can best use GitHub.  The small number of rules in this document
are there to ensure common usage patterns between working groups and
to avoid issues that have been encountered in the past.
Paragraph (version B):
The main purpose of this document is providing guidelines for how
Working Groups might integrate the capabilities provided by GitHub
into their processes for developing Internet-Drafts.
Paragraph (version B):
This document is meant as an supplement to existing Working Group
practices.  It provides guidance to Working Group chairs and
participants on how they can best use GitHub within the framework
established RFC 2418 RFC2418.  The small number of rules in this
document are there to ensure common usage patterns between working
groups and to avoid issues that have been encountered in the past.
Paragraph (version A):
Updating the README or CONTRIBUTING file in the repository with
details of the process ensures that the process is recorded in a
stable location other than the mailing list archive.  This also makes
any working group policies available to casual contributors who might
only interact with the GitHub repository.
Paragraph (version B):
Repositories MUST include a copy or reference to the policy that
applies to managing any documents they contain.  Updating the README
or CONTRIBUTING file in the repository with details of the process
ensures that the process is recorded in a stable location other than
the mailing list archive.  This also makes any Working Group policies
available to casual contributors who might only interact with the
GitHub repository.
Paragraph (version A):
In addition to the canonical XML format RFC7991, document editors
might choose to use a different input form for editing documents,
such as markdown.  The choice of input format is left to document
editors.
Paragraph (version B):
In addition to the canonical XML format RFC7991, document editors
might choose to use a different input form for editing documents,
such as markdown.  Markdown-based formats have proven to be more
accessible for new contributors, though ultimately decisions about
format is left to document editors.
Paragraph (version B):
Formats that are not text-based, SHOULD NOT be used, as these are
inimical to the sorts of interaction that revision control enables.
Paragraph (version A):
When deciding to use GitHub, Working Group Chairs MUST decide how the
GitHub issue tracker are used.  Use of the issue tracker could be
limited to recording the existence of issues, or it might be used as
the venue for substantial technical discussion between contributors.
Paragraph (version B):
When deciding to use GitHub, Working Group Chairs MUST decide how the
GitHub issue tracker is used.  Use of the issue tracker could be
limited to recording the existence of issues, or it might be used as
the venue for substantial technical discussion between contributors.
Paragraph (version B):
A Working Group policy MAY require that all substantive changes be
tracked using issues.  Suggested policies for the use of the GitHub
issue tracker are the primary subject of modes.
Paragraph (version A):
If labels are a core part of working group process, chairs MUST
communicate any process to the working group.  This includes the
semantics of labels, and who can apply and remove these labels.
Paragraph (version B):
If labels are a core part of working group process, chairs MUST
communicate any process to the working group.  This includes the
semantics of labels, and who can apply and remove these labels.
labels describes some basic strategies that might be adopted to
manage decision-making processes.
Paragraph (version B):
Restrictions on closing issues are generally not advisable until a
document has reached a certain degree of maturity.
Paragraph (version B):
Issues that have reached a resolution that has Working Group
consensus MUST NOT be reopened unless new information is presented.
Paragraph (version B):
For long-running work items, new contributors often raise issues that
have already been resolved.  Chairs need to assess whether the
arguments offered represent new information or not.  This can require
some discussion to determine accurately.  Resolved issues MUST remain
closed unless there is consensus to reopen an issue.
Paragraph (version A):
Editors SHOULD make pull requests for all substantial changes rather
than committing directly to the "master" branch of the repository.
Paragraph (version B):
Editors SHOULD make pull requests for all substantial changes rather
than committing directly to the "master" branch of the repository.
Pull requests that address substantive issues SHOULD mention the
issue they address in the opening comment.
Paragraph (version B):
Current experience with use of GitHub suggests a few different
approaches to greater use of the tool in Working Groups.
Paragraph (version B):
This section describes some basic modes for interacting with GitHub,
each progressively more involved.  This starts with a very
lightweight interaction where document management is the only feature
that is formally used, then progressively more intensive use of the
GitHub issue tracking capabilities are described.  These approaches
differ primarily in how discussion of substantive matters is managed.
Most of the advice in this document applies equally to all models.
Paragraph (version B):
Working Groups can adjust these policies to suit their needs, but are
advised to avoid gratuitous changes for the sake of consistency
across the IETF as a whole.
Paragraph (version B):
In this mode of interaction, GitHub repositories are used to manage
changes to documents, but the bulk of the work is conducted using
email, face-to-face meetings, and other more traditional
interactions.  The intent of this policy is to enable document and
issue management using GitHub while minimizing the complexity of the
process.
Paragraph (version B):
In the version of this mode with the least interaction with GitHub,
only the document repository is created and that is used by editors.
Editors might manage issues for their own benefit, or they might
choose to just use the respository to manage document revisions.
Paragraph (version B):
In addition to managing documents, the working group might choose to
use GitHub for tracking outstanding issues.  In this mode of
interaction, all substantive technical discussions are tracked as
issues in the issue tracker.  However, discussion of any substantial
matters is always conducted on mailing lists.
Paragraph (version B):
Under this mode, issues and pull requests can be opened by anyone,
but anything deemed substantive MUST be resolved exclusively on the
mailing list.  Discussion on GitHub is kept to a minimum.  Only
editorial matters can be resolved using the issue tracker.
Paragraph (version B):
Chairs and editors are given discretion in determining what issues
are substantive.  As documents mature, it is generally prudent to err
more toward consulting the mailing list where there is doubt.  As
with other Working Group decisions, chairs are the arbiters in case
of dispute.
Paragraph (version B):
A recurrent problem with this mode of interaction is the tendency for
discussions to spontaneously develop in the issue tracker.  This
requires a degree of discipline from chairs and editors to ensure
that any substantive matters are taken to the mailing list.
Paragraph (version B):
As mailing lists remain the primary venue for discussion of
substantive matters, this mode and the document management only modes
remain those most compatible with existing work practices for Working
Groups.  Participants in a Working Group that operates under either
model can reasonably be expected to receive all relevant
communication about the work of the group from the mailing list.
Paragraph (version B):
Though the mailing list is used for making decisions, the issue
tracker can still be a useful record of the state of issues.  It is
often useful if chairs or editors record details of decisions in
issue comments when closing issues as resolved.
Paragraph (version B):
This GitHub interaction mode differs from the other modes in that
discussion relating to substantive technical matters is allowed to
occur on GitHub issues.  Though decisions are always subject to
confirmation on the mailing list, participants are permitted to
conduct substantive discussions on the issue tracker.  In some cases,
this can include making some decisions without involving the Working
Group mailing list.
Paragraph (version B):
A Working Group mailing list remains a critical venue for decision
making, even where issue discussion occurs elsewhere.  Working Group
mailing lists generally include a wider audience than those who
follow issue discussion, so difficult issues always benefit from list
discussion.
Paragraph (version B):
Decisions about Working Group consensus MUST always be confirmed
using the Working Group mailing list.  However, depending on the
maturity of documents, this might be a more lightweight interaction,
such as sending an email confirmation for a set of resolutions made
using GitHub.
Paragraph (version B):
Using the mailing list to resolve difficult or controversial issues
is strongly encouraged.  In those cases, the issue tracker might be
used to more fully develop an understanding of problems before
initiating a discussion on the mailing list, along lines similar to
the design team process (see Section 6.5 of RFC2418).
Paragraph (version B):
As a more involved process, adopting this mode can require changes in
policies as documents become more mature.  It is possible to use
different processes for different documents in the Working Group.
Paragraph (version B):
Working Group chairs SHOULD confirm that the Working Group has
consensus to adopt any process.  In particular, the introduction of a
more tightly-controlled process can have the effect of privileging
positions already captured in documents, which might disadvantage
alternative viewpoints.
Paragraph (version B):
During early phases of the design of a protocol, chairs MAY allow
editors to manage all aspects of issues.  Editors are permitted to
make decisions about how to both identify and resolve technical
issues, including making any changes that editors feel necessary.
Paragraph (version B):
Chairs need to explicitly decide that this sort of process is needed
and announce the decision to the Working Group.  In many cases,
documents that are adopted by a Working Group are already
sufficiently mature that a looser process is not beneficial.  The
primary reason to grant editors more discretionary power is to
improve the speed with which changes can be made.  The risk is that
design changes might not always reflect the consensus of the Working
Group.
Paragraph (version B):
Changes made by editors under this process do not completely lack
oversight.  GitHub and git provide tools for ensuring that changes
are tracked and can be audited.  Within the usual Working Group
process it is expected that Internet-Drafts will receive regular
review.  Finally, process checkpoints like Working Group Last Call
(WGLC; Section 7.4 of RFC2418) provides additional safeguards against
abuse.
Paragraph (version B):
Working Groups are advised against allowing editors this degree of
flexibility for the entirety of a document lifecycle.  Once a
document is more stable and mature, it is likely appropriate to move
to a more tightly controlled process.
Paragraph (version B):
As a document matures, it becomes more important to understand not
just that the document as a whole retains the support of the working
group, but that changes are not made without wider consultation.
Paragraph (version B):
Chairs might choose to manage the process of deciding which issues
are substantive.  For instance, chairs might reserve the ability to
use the "design" label to new issues (see label-design) and to close
issues marked as "design".  Chairs should always allow document
editors to identify and address editorial issues as they see fit.
Paragraph (version B):
As documents mature further, explicit confirmation of technical
decisions with the Working Group mailing list becomes more important.
Paragraph (version B):
Gaining Working Group consensus about the resolution of issues can be
done in the abstract, with editors being permitted to capture the
outcome of discussions as they see fit.
Paragraph (version B):
More mature documents require not only consensus, but consensus about
specific text.  All substantive changes to documents that have passed
WGLC SHOULD be proposed as pull requests, and MUST be discussed on
the mailing list, and MUST have chairs explicitly confirm consensus.
Chairs MAY institute this stricter process prior to WGLC.
Paragraph (version B):
It is generally sufficient to trust editors to manage adherence
with these policies, aided by the transparency provided by the
version control system.  There are tools that can be used to more
tightly control access to repositories, but they can be overly
constraining.
Paragraph (version B):
Several schemes for use of issue labels in managing issues have been
used successfully.  This section outlines these strategies and how
they might be applied.
Paragraph (version B):
A design/editorial split (see label-design) is useful in all cases
that the issue tracking capability is used.  Working Groups that only
use GitHub for issue tracking might find that distinction sufficient
for their needs.
Paragraph (version B):
Working Groups or editors might use additional labels as they choose.
Any label that is used as part of a process requires that the process
be documented and announced by Working Group chairs.  Editors SHOULD
be permitted to use labels to manage issues without any formal
process significance being attached to those issues.
Paragraph (version B):
The most important distinction about an issue is whether it is
substantive.  The labels of "design" and "editorial" are used to
represent this distinction.
Paragraph (version B):
An issue labeled as "design" has or might have a substantive effect
on a document.  For protocol specifications, a "design" issue is one
that might affect implementations or interoperability requirements.
Addressing a "design" issue ultimately requires Working Group
consensus, even if the resolution is to make no change.
Paragraph (version B):
An issue labeled as "editorial" has no substantive effect on a
document, except to the extent that addressing the issue might make
understanding the specification easier.  Resolution of "editorial"
issues can be left to the discretion of editors.
Paragraph (version B):
This distinction can be applied to all types of document.  For
instance, a "design" issue for an Informational document might be
raised to discuss possible changes to important concepts in the
document.
Paragraph (version B):
Labels can be used to manage processes.  As documents mature and
issues become more numerous, labels can be used to clearly mark the
status of issues.  In particular, labelling of issues can be used to
help in managing Working Group decisions.
Paragraph (version B):
For documents that are less mature, issues with resolutions but no
specific proposals for changes to text might be marked "editor-ready"
as a way of signaling that there is consensus about an approach, but
no specific proposal.  Chairs might use this to signal that
discussion is complete and that editors are to be given discretion in
the construction of text.
Paragraph (version B):
In contrast, if specific text is a prerequisite for resolving issues,
as might be the case for more mature documents, a "proposal-ready"
label might be used by editors to mark issues that they believe to
have acceptable resolutions.
Paragraph (version B):
For resolved issues, a "has-consensus" label might be used by chairs
to mark issues for which formal Working Group decisions have been
made (Section 6.1 of RFC2418).
Paragraph (version B):
A "v2" or "next-version" label might be used to mark and thereby save
issues for a future version of or extension to a protocol,
particularly where a resolution is made to take no action.
Paragraph (version B):
Repositories with multiple interrelated documents or a complex
document with multiple logical components might benefit from labels
that identify different aspects of the work.  The choice of
appropriate labels for components will depend on the structure of
specific documents.
Paragraph (version B):
Other labels can be used depending on the needs of editors and
Working Group processes.  For example,
Paragraph (version B):
An "invalid" label might be used for issues that were raised in
error.
Paragraph (version B):
A "blocked" label might indicate an issue is awaiting resolution
of an external process or related issue.
Paragraph (version B):
A "parked" label might be used to indicate issues that do not
require immediate working group attention.