Draft: draft-ietf-git-using-github

Commentary: Fix a few nits from review : Make the use of Working Group capitalization consistent ( if you want it the other way that 's fine too ) Update BCP 14 reference Various typos / editorial nits The one content - based changed is changing the requirement for all working group document repositories to be public , to clarify that this is for repositories that are managed by the WG organization . The sentence previously seemed to also include a requirement on working group documents for working groups not officially using GitHub ; I do n't think we can make a requirement for people who happen to use a private GitHub repo to manage a working group document that 's not officially using GitHub . 
 LGTM -- thanks !
Paragraph (version A):
Different version control systems are a critical component of
software engineering and are quite useful also for document editing.
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 B):
Version control systems are a critical component of software
engineering and are quite useful also for document editing.
Paragraph (version B):
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/ [3].  GitHub
provides a centralized store for git repositories.  GitHub is freely
accessible on the open Internet (see shame), albeit currently only
via IPv4.
Paragraph (version A):
GitHub provides a simplified and integrated interface to not only
git, but also provides basic user management, an issue tracker,
associated wiki, project hosting, and other features.
Paragraph (version A):
There are a large number of projects at GitHub and 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 B):
GitHub is a service operated at https://github.com/ [3].  GitHub
provides centralized storage for git repositories.  GitHub is freely
accessible on the open Internet (see shame), albeit currently only
via IPv4.
Paragraph (version B):
GitHub provides a simplified and integrated interface to not only
git, but also provides basic user management, an issue tracker,
associated wikis, project hosting, and other features.
Paragraph (version B):
There are a large number of projects at GitHub and a very large
community of contributors.  One way in which some IETF Working Groups
have benefited is through increased numbers of reviews and associated
issues, along with other improvements that come from broader
participation by facilitating those in the community to participate.
Paragraph (version A):
The words "MUST", "MUST NOT", "SHOULD", and "MAY" are used in this
document.  It's not shouting; when they are capitalized, they have
the special meaning defined in RFC2119.
Paragraph (version B):
The words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are
used in this document.  It's not shouting; when they are capitalized,
they have the special meaning defined in BCP 14 RFC2119 RFC8174.
Paragraph (version A):
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):
GitHub prominently links to the CONTRIBUTING on certain pages.  This
file SHOULD be used in preference to the README for information that
new contributors need.  A link to the CONTRIBUTING file from the
README is advised.
Paragraph (version A):
All repositories for working group documents MUST be public.
Repositories for private documents MAY be kept private, but only
where there is a specific reason for doing so.  For instance, a
document that details a security vulnerability might be kept private
prior to its initial publication as an Internet-Draft.  Once an
Internet-Draft is published, repositories SHOULD be made public.
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 Working Group policies
available to casual contributors who might only interact with the
GitHub repository.
Paragraph (version B):
GitHub prominently links to the CONTRIBUTING file on certain pages.
This file SHOULD be used in preference to the README for information
that new contributors need.  A link to the CONTRIBUTING file from the
README is advised.
Paragraph (version B):
All repositories for Working Group documents within the Working Group
organization MUST be public.  Repositories for private documents MAY
be kept private, but only where there is a specific reason for doing
so.  For instance, a document that details a security vulnerability
might be kept private prior to its initial publication as an
Internet-Draft.  Once an Internet-Draft is published, repositories
SHOULD be made public.
Paragraph (version A):
Maintaining multiple documents in the same repository can add
overhead that negatively affects individual documents.  For instance,
issues might require additional markings to identify the document
that they affect.  Also, because editors all have write access to the
repository, managing the set of people with write access to a larger
repository is more difficult.
Paragraph (version B):
Maintaining multiple documents in the same repository can add
overhead that negatively affects individual documents.  For instance,
issues might require additional markings to identify the document
that they affect.  Also, because editors all have write access to the
repository, managing the set of people with write access to a larger
repository is more difficult (editors).
Paragraph (version A):
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 B):
Formats that are not text-based SHOULD NOT be used, as these are ill-
disposed to the sorts of interaction that revision control enables.