Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Ben's AD review comments #52

Merged
merged 18 commits into from Mar 16, 2020
Merged

Ben's AD review comments #52

Changes from 15 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
8d35a5e
Reword RG text a little
martinthomson Mar 13, 2020
32cd3c3
Now we're into merge conflict territory, oh well
martinthomson Mar 13, 2020
496356e
Remove maintain membership oddnes
martinthomson Mar 13, 2020
71add31
Correct owner arrangement
martinthomson Mar 13, 2020
8eeb3c9
Correct text about teams and privileges
martinthomson Mar 13, 2020
709589f
Links to other resources too
martinthomson Mar 13, 2020
a8c7f96
copy of
martinthomson Mar 13, 2020
6cc2168
Remove normative language about labels
martinthomson Mar 13, 2020
6c81cd9
Issue tracking doesn't need to record the discussion, just that an is…
martinthomson Mar 13, 2020
8af36d0
Use language closer to what a design team might use
martinthomson Mar 13, 2020
578612e
redundant word, ugh
martinthomson Mar 13, 2020
664fe5e
review within the WG
martinthomson Mar 13, 2020
093c1cc
Recommend backups rather than defer
martinthomson Mar 13, 2020
0e0e9dc
Deal with a compromise
martinthomson Mar 13, 2020
153183a
Ben proofread this and I need to be more careful
martinthomson Mar 13, 2020
02ddc2c
Chris Wood makes this better
martinthomson Mar 16, 2020
302feb5
Adding a comment about credentials
martinthomson Mar 16, 2020
06bf70a
Merge branch 'master' into ben
martinthomson Mar 16, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
83 changes: 46 additions & 37 deletions draft-ietf-git-using-github.md
View file
Open in desktop
Expand Up @@ -72,8 +72,10 @@ A companion document, {{?GH-CONFIG=I-D.ietf-git-github-wg-configuration}},
describes administrative processes that support the practices described in this
document.

Although similar, guidance for IRTF Research Groups is out of scope for this document.
However, such groups may draw inspiration for GitHub use from the contents herein.
Although the operation of IRTF Research Groups can be similar in function to
Working Groups, this document only directly addresses the needs of Working Groups.
However, other groups may draw inspiration for GitHub use from the contents
herein.

## Distributed Version Control Systems

Expand All @@ -98,10 +100,11 @@ provides basic user management, an issue tracker, associated wikis, project
hosting, and other features.

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.
contributors. One way in which some IETF Working Groups have benefited from use
of the service 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.


## Other Services

Expand Down Expand Up @@ -168,17 +171,16 @@ found. For instance, the name could be ietf-wg-\<wgname>, as recommended in

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 membership.
management tasks.

Each organization requires owners. The owner team for a Working Group
repository MUST include responsible Area Directors. Area Directors MAY also
designate a delegate that becomes an owner and Working Group chairs MAY also be
owners.
GitHub requires that each organization have at least one owner. The owners for
a Working Group repository MUST include responsible Area Directors. Area
Directors MAY also designate a delegate that becomes an owner and Working Group
martinthomson marked this conversation as resolved.
Show resolved Hide resolved
chairs MAY also be owners.

A team with administrator access SHOULD be created for the Working Group Chairs
and any Working Group 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I can understand that there's not a huge need to mention the details of Administrator privilege in these guidelines.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, the point was that this was flat wrong, based on an outdated authorization model.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we mention that the model (as is now documented) is also subject to change?

Within an organization, members can be grouped into teams. A team with "Admin"
access to repositories SHOULD be created for the Working Group Chairs and any
Working Group Secretary.

Details about creating organizations adhering to these guidelines can be found
in {{!GH-CONFIG=I-D.ietf-git-github-wg-configuration}}.
Expand All @@ -193,9 +195,10 @@ organization.

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. Similarly, if there are
multiple mailing list options, links to those mailing lists should be given.
additional resources, such as additional mailing lists, links to those resources
martinthomson marked this conversation as resolved.
Show resolved Hide resolved
could also be added.

Repositories MUST include a copy or reference to the policy that applies to
Repositories MUST include a copy of 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
Expand Down Expand Up @@ -246,11 +249,10 @@ to track items that require further discussion in order to reach consensus,
keeping the issue tracker available to editors can be valuable.

Working Group policies need to be set with the goal of improving transparency,
participation, and ultimately the quality of the consensus behind documents. At
times, it might be appropriate to impose some limitations on what document
editors are able to do in order to serve these goals. Chairs SHOULD
periodically consult with document editors to ensure that policies are
effective.
participation, and ultimately the quality of documents. At times, it might be
appropriate to impose some limitations on what document editors are able to do
in order to serve these goals. Chairs SHOULD periodically consult with document
editors to ensure that policies are effective.

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
Expand Down Expand Up @@ -369,10 +371,10 @@ into a document.
Labels can be used to identify particular categories of issues or to mark
specific issues for discussion at an upcoming session.

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.
Chairs communicate any process that specifically relates to the use of labels 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.


### Closing Issues
Expand Down Expand Up @@ -512,14 +514,15 @@ formal standing in the Working Group process.
## Issue Tracking Mode

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.
for tracking outstanding issues. In this mode of interaction, a record of the
existence of substantive technical discussions is tracked using issues in the
issue tracker. However, discussion of any substantial matters is always
conducted on mailing lists.

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.
GitHub is limited to recording the state of issues. Only editorial matters can
be resolved using the issue tracker.

Chairs and editors are given discretion in determining what issues are
substantive. As documents mature, it is generally prudent to prefer consulting
Expand Down Expand Up @@ -561,7 +564,8 @@ issues always benefit from list discussion.
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.
confirmation for an initial set of resolutions arising from discussions on
the issue tracker.

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
Expand Down Expand Up @@ -777,8 +781,8 @@ the widest possible audience ensures a higher quality document.

If permitted, GitHub will be used for technical discussion and decisions,
especially during early stages of development of a document. Any decisions are
ultimately confirmed through review, and ultimately, through Working Group Last
Call (see Section 7.4 of {{!RFC2418}}).
confirmed through review within the Working Group, and ultimately, through
Working Group Last Call; see Section 7.4 of {{!RFC2418}}.

The use of issues and labels has been effective in managing contentious issues.
Explicitly labeling closed issues to identify those with formal
Expand Down Expand Up @@ -848,20 +852,25 @@ its services would be seriously affected.
Widespread use of git reduces the exposure to a system failure because the
primary repository is replicated in multiple locations. This includes hosted
web pages; the content of web pages is maintained as a branch in the main
repository. As specified in {{?GH-CONFIG=I-D.ietf-git-github-wg-configuration}},
maintaining a mirror of a repository hosted on GitHub provides IETF-hosted backups
for WG repositories.
repository.

However, other information maintained on GitHub is more vulnerable to loss.
This includes issues and discussion on those issues, discussion and reviews of
commits and pull requests, and any content hosted on the wiki. Tools exist for
extracting this information for backup.

As specified in {{?GH-CONFIG=I-D.ietf-git-github-wg-configuration}}, backup
copies of repositories and other important data SHOULD be maintained.

The potential for malicious actions by compromised or malcontent editors,
chairs and area directors is relevant in maintaining the integrity of the
content that GitHub hosts. Backups allow for recovery of content, and regular
submissions as Internet-Drafts ensure that work is not lost completely.

A compromise of GitHub does not pose a significant threat to Working Group
operations as it is expected that most data, aside from individual credentials,
is made public.


# IANA Considerations

Expand Down