Draft: draft-thomson-github-bcp

Commentary: Added various text to intro , pulled out IETF - wide considerations from WG considerations
Paragraph (version A):
Developing a specification shares a great deal in common with the
development of software.  Modern engineering practices that favor
rapid iteration find that the use of version control systems is
critical in managing changes.
Paragraph (version B):
The IETF has an open and transparent process for developing
standards; the use of github, when used as part of this process as
appropriate, can have several objectives.  For some technology areas,
it can broaden the community that is reviewing and improving the
specifications.  Github provides useful tools to speed up and manage
a rapid iteration process for managing changes and tracking issues.
Using tools that reduce the friction in rapidly improving documents
and getting more relevant reviews can help improve the speed at which
a Working Group completes its specifications.
Paragraph (version A):
Git is a distributed version control system.  Each instance of a
repository contains a number of revisions.  Each revision stores the
complete state of a set of files.  Users are able to create new
revisions in their copy of a repository and share revisions between
copies of repositories.
Paragraph (version A):
Github is a service operated at https://github.com/ [2].  Github
provides a centralized store for git repositories.
Paragraph (version A):
The primary function of Github is to provide a simplified interface
to the underlying revision control system.  In addition, Github
provides basic user management, an issue tracker, a wiki, and web
hosting for projects.
Paragraph (version B):
Different version control systems are a critical component of
software engineering and are quite useful also for document editing.
The IETF datatracker can currently provide an svn repository for each
Working Group for its version control system, but git is also
possible.
Paragraph (version B):
Git is a distributed version control system and both GitLab and
GitHub are based around git.  Each instance of a repository contains
a number of revisions.  Each revision stores the complete state of a
set of files.  Users are able to create new revisions in their copy
of a repository and share revisions between copies of repositories.
Paragraph (version B):
GitLab provides a simplified and integrated interface to not only
git, but also provides basic user management, an issue tracker,
associated wiki, project hosting, and more.  GitLab is a commercial
integrated software product that can be hosted and run by different
organizations; a community version is also available.
Paragraph (version B):
Github is a service operated at https://github.com/ [2].  Github
provides a centralized store for git repositories.  Github is freely
accessible on the open Internet, albeit currently only via IPv6.
Paragraph (version B):
There are a large number of projects at GitHub and associated a very
large community of contributors.  One way in which some IETF Working
Groups have seen benefit is in the increased reviews and associated
issues and improvements that come from broader participation by
facilitating those in this community to participate.
Paragraph (version A):
The decision to use Github formally is the responsibility of a
working group chair.  Chairs SHOULD involve area directors in this
decision if they intend to use Github for anything more than managing
of edits.
Paragraph (version A):
A document editor can still use Github independently for documents
that they edit even if the working group does not expressly choose to
use Github.  This recognizes that editors have traditionally chosen
their own methods for managing the documents they edit.
Paragraph (version B):
The following administrative rules provide the necessary oversight
and transparency.  They apply whether GitHub or a publicly-available
GitLab instance is used by the Working Group.  Working Groups that do
not decide to use GitHub or a publicly-available GitLab instance are
not impacted.
Paragraph (version B):
Each Working Group SHOULD create a new organization for the working
group.  It SHOULD be named consistently so that it can be found.  For
instance, the name could be IETF-area-wgname.  A single organization
SHOULD NOT be used for all IETF activity, or all activity within an
area.  Large organizations create too much overhead for general
management tasks, particularly when there is a need to maintain and
is discouraged.
Paragraph (version B):
Since an organization must have some owners, that should be done via
a team that is given owner privileges.  This team MUST include the
Area Directors and/or delegates of the Area Directors.  This team
SHOULD include the Working Group Chairs.  A team with administrator
access SHOULD be created and MAY include the Working Group Chairs and
WG Secretary.  Administrator access is preferable, since this does
not also include the ability to push to all repositories and
ownership does not grant any other significant privileges.
Paragraph (version B):
When an Area Director changes, the outgoing Area Director MUST be
removed from the organization's ownership team.  This can be done by
the continuing AD, the outgoing AD or the WG Chairs.  The incoming
Area Director and/or delegate MUST be added to the organization's
ownership team.  When a WG Chair changes, the responsible Area
Director or a delegate MUST remove the previous WG Chair from the
organization's ownersip or administrative team and SHOULD add the new
WG Chair to that team.
Paragraph (version B):
When a Working Group is closed, the responsible Area Director is
responsible for ensuring that the organization MUST either be closed
and associated repositories removed or, if the repository state is
desired to be preserved in its original location, the organization's
description MUST be updated along with the associated repositories to
indicate that they are no longer under development.
Paragraph (version B):
When an IETF Working Group is closed and even when the associated
mailing lists are closed, the associated mail archives and
datatracker information are backed up and accessible.  If a working
group has used Github or GitLab, at least the repository, issues
tracking information, and any discussion SHOULD be backed up on IETF
resources.  It is desirable for those to be accessible via the
Working Group's data-tracker page.  For example, this might be via
URLs listed in the More Info section on the WG Charter page.
Paragraph (version B):
The IETF MAY decide to backup information associated with a Working
Group's organization periodically.  This decision MAY be made
differently per Working Group in consultation with the responsible
Area Director.
Paragraph (version B):
One important policy is the IETF IPR policy (see RFC5378, RFC3979,
and RFC4879).  Part of this policy requires making contributors aware
of the policy.
Paragraph (version B):
The wording and details of how to do so are specified at
https://trustee.ietf.org/license-for-open-source-repositories.html.
The details are copied below, but the IETF web-site is authorative.
Paragraph (version A):
Working groups that choose to use Github SHOULD create a new
organization for the working group.  A single organization SHOULD NOT
be used for all IETF activity, or all activity within an area.  Large
organizations create too much overhead for general management tasks,
particularly when there is a need to maintain and is discouraged.
Paragraph (version A):
Working group chairs and responsible area directors MUST be assigned
administrator or owner privileges for the organization.  The other
area director for an area SHOULD be made an administrator.
Administrator access is preferable, since this does not also include
the ability to push to all repositories and ownership does not grant
any other significant privileges.
Paragraph (version A):
When area directors or chairs change, the incoming individual should
first be added to the organization and granted privileges.  The
outgoing party can then leave, or reduce their own privilege, as
appropriate.
Paragraph (version B):
Each Working Group MAY set its own policy as to whether and how it
uses GitHub or GitLab.  It is important that occasional participants
in the WG and others accustomed to IETF tools be able to determine
this and easily find the policy and GitHub or GitLab organization.
Paragraph (version B):
A simple example of how to do this is to include a link to the GitHub
organization on the WG Charter page in the Datatracker under More
Info.  Similarly, if there are multiple mailing list options, links
to those mailing lists should be given.  An example of this is at
https://datatracker.ietf.org/wg/quic/charter/.
Paragraph (version B):
A Working Group Chairs are responsible for determining how to best
accomplish the Charter in an open and transparent fashion.  The WG
Chairs are responsible for determining if there is interest in using
GitHub or GitLab and making a consensus call to determine if a the
proposed policy and use is acceptable.  Chairs SHOULD involve area
directors in this decision if they intend to use Github for anything
more than managing of edits.
Paragraph (version B):
While a document editor can still use Github independently for
documents that they edit, even if the working group does not
expressly choose to use Github, any such public respository MUST
follow https://trustee.ietf.org/license-for-open-source-
repositories.html, which describes including Note Well details in the
CONTRIBUTING file.  This recognizes that editors have traditionally
chosen their own methods for managing the documents they edit but
preserves the need for transparent contributions with awareness of
IPR considerations.
Paragraph (version A):
Monitoring activity on Github could require a greater time commitment
than following a mailing list.  This is because there is an increased
volume of activity to follow.  Participants who wish to limit this
time commitment might follow Github activity selectively, either by
following only specific issues or by occasionally reviewing the state
of the document.  Chairs are reminded that assessing consensus based
on Github content alone might not always reach all interested
participants.
Paragraph (version B):
Monitoring activity on Github could require a greater time commitment
than following a mailing list.  This is because there is an increased
volume of activity to follow.  Participants who wish to limit this
time commitment might follow Github activity selectively, either by
following only specific issues or by occasionally reviewing the state
of the document.  Chairs are reminded that assessing consensus based
on Github content alone MUST NOT be assumed to reach all interested
participants.
Paragraph (version A):
A working group chair SHOULD consult the working group mailing list
for any issue that is potentially contentious.  Relying on input
provided through Github alone might result in gaining input from a
narrower set of participants.  This includes important milestones
like working group last-call, where review from the widest possible
audience ensures a higher quality document.
Paragraph (version B):
A working group chair SHOULD consult the working group mailing list
for any issue that is potentially contentious.  Relying on input
provided through Github alone might result in gaining input from a
narrower set of participants.  This includes important milestones
like working group last-call, where review from the widest possible
audience ensures a higher quality document.  Managing input from
multiple sources towards consensus is similar to what is needed when
balancing mailing list discussion versus in-person meeting
discussion.