[要約] RFC 8874は、IETFのワーキンググループがGitHubを使用する際のガイダンスを提供するものです。このRFCの目的は、ワーキンググループがGitHubを効果的に活用し、コラボレーションを促進するための指針を提供することです。
Internet Engineering Task Force (IETF) M. Thomson
Request for Comments: 8874 Mozilla
Category: Informational B. Stark
ISSN: 2070-1721 AT&T
August 2020
Working Group GitHub Usage Guidance
ワーキンググループGithubの使用ガイダンス
Abstract
概要
This document provides a set of guidelines for working groups that choose to use GitHub for their work.
このドキュメントでは、githubを自分の作業に使用することを選択するワーキンググループの一連のガイドラインを提供します。
Status of This Memo
本文書の状態
This document is not an Internet Standards Track specification; it is published for informational purposes.
この文書はインターネット標準のトラック仕様ではありません。情報提供のために公開されています。
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Not all documents approved by the IESG are candidates for any level of Internet Standard; see Section 2 of RFC 7841.
この文書は、インターネットエンジニアリングタスクフォース（IETF）の製品です。IETFコミュニティのコンセンサスを表します。それは公開レビューを受け、インターネットエンジニアリングステアリンググループ（IESG）による出版の承認を受けました。IESGによって承認されたすべての文書がすべてのレベルのインターネット規格の候補者ではありません。RFC 7841のセクション2を参照してください。
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc8874.
この文書の現在のステータス、エラータ、およびフィードバックを提供する方法については、https://www.rfc-editor.org/info/rfc8874で入手できます。
Copyright Notice
著作権表示
Copyright (c) 2020 IETF Trust and the persons identified as the document authors. All rights reserved.
Copyright（C）2020 IETFの信頼と文書著者として識別された人。全著作権所有。
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
この文書は、この文書の公開日に有効なIETF文書（https://truste.ietf.org/License-info）に関するBCP 78とIETF信頼の法的規定を受けています。この文書に関してあなたの権利と制限を説明するので、これらの文書を慎重に見直してください。この文書から抽出されたコードコンポーネントには、信頼法の法的規定のセクション4。
Table of Contents
目次
1. Introduction
1.1. Distributed Version Control Systems
1.2. GitHub
1.3. Other Services
1.4. Document Goals
1.5. Notational Conventions
2. Administrative Policies
2.1. Organizations
2.2. Communicating Policies
3. Deciding to Use GitHub
3.1. What to Use GitHub For
3.2. Repositories
3.3. Editors and Contributors
3.4. Document Formats
4. Contribution Methods
4.1. Issue Tracker
4.1.1. Issue Labels
4.1.2. Closing Issues
4.1.3. Reopening Issues
4.2. Pull Requests
4.2.1. Discussion on Pull Requests
4.2.2. Merging Pull Requests
4.3. Monitoring Activity
5. Typical Working Group Policies
5.1. Document Management Mode
5.2. Issue Tracking Mode
5.3. Issue Discussion Mode
5.3.1. Early Design Phases
5.3.2. Managing Mature Documents
5.4. Issue Labeling Schemes
5.4.1. Editorial/Design Labeling
5.4.2. Decision Labeling
5.4.3. Component Labeling
5.4.4. Other Labels
6. Internet-Draft Publication
7. Assessing Consensus
8. Continuous Integration
9. Advice to Editors
10. Security Considerations
11. IANA Considerations
12. References
12.1. Normative References
12.2. Informative References
Acknowledgments
Authors' Addresses
The IETF has an open and transparent process for developing standards. The use of GitHub (https://github.com/) or similar tools, when used as part of this process, can have several objectives. GitHub provides tools that can be helpful in editing documents. Use of this service has been found to reduce the time that a working group needs to produce documents and to improve the quality of the final result.
IETFは標準を開発するためのオープンで透明なプロセスを持っています。このプロセスの一部として使用されると、Github（https://github.com/）または同様のツールの使用はいくつかの目的を持つことができます。GitHubは文書の編集に役立つことができるツールを提供します。このサービスの使用は、ワーキンググループが文書を作成し、最終結果の品質を向上させる必要がある時間を短縮することがわかっています。
The use of version control improves the traceability and visibility of changes. Issue tracking can be used to manage open issues and provide a record of their resolution. Pull requests allow for better engagement on technical and editorial changes, and encourage contributions from a larger set of contributors. Using GitHub can also broaden the community of contributors for a specification.
バージョン管理の使用は、変化のトレーサビリティと可視性を向上させます。発行トラッキングを使用して、開かれた問題を管理し、それらの解決の記録を提供することができます。プルリクエストにより、技術的および編集の変化へのより良いエンゲージメントが可能になり、より大きな貢献者のセットからの貢献を促進します。Githubを使用すると、仕様のために貢献者のコミュニティも広げられます。
The main purpose of this document is to provide guidelines for how a working group might integrate the capabilities provided by GitHub into their processes for developing Internet-Drafts. Whether to use GitHub and whether to adopt these practices is left to the discretion of the working group.
この文書の主な目的は、WITHUBが提供する機能をインターネットドラフトの開発のためのプロセスにどのように統合することができるかについてのガイドラインを提供することです。GitHubを使用するかどうか、およびこれらの慣行を採用するかどうかは、ワーキンググループの裁量に残されています。
This document is meant as a 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 by RFC 2418 [RFC2418]. This document aims to establish norms that reduce the variation in usage patterns between different working groups and to help avoid issues that have been encountered in the past.
この文書は、既存のワーキンググループの慣行への補足としてのものです。それは、RFC 2418 [RFC2418]によって確立されたフレームワーク内でGitHubをどのように使用するかについてのワーキンググループの椅子と参加者へのガイダンスを提供します。この文書は、さまざまなワーキンググループ間の使用パターンの変動を軽減し、過去に遭遇した問題を回避するのを助けるための規範を確立することを目的としています。
A companion document, [RFC8875], describes administrative processes that support the practices described in this document.
コンパニオンドキュメント[RFC8875]は、この文書に記載されている慣行をサポートする管理プロセスを説明しています。
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.
IRTF研究グループの動作は、作業グループと機能が似ている可能性がありますが、この文書はワーキンググループのニーズに直接取り組んでいます。しかしながら、他のグループは、ここでの内容物からのGITHUB使用のためのインスピレーションを引き出すことができる。
Version control systems are a critical component of software engineering and are also quite useful for document editing.
バージョン管理システムはソフトウェアエンジニアリングの重要なコンポーネントであり、文書編集にも非常に役立ちます。
Git (https://git-scm.com/) is a distributed version control system that can operate without a central service. 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.
git（https://git-scm.com/）は、中央サービスなしで動作できる分散バージョン管理システムです。リポジトリの各インスタンスにはいくつかのリビジョンが含まれています。各リビジョンは、一連のファイルの完全な状態を格納します。ユーザーは、リポジトリのコピーで新しいリビジョンを作成し、リポジトリのコピー間のリビジョンを共有できます。
GitHub is a service operated at <https://github.com/>. GitHub provides centralized storage for Git repositories. GitHub is freely accessible on the open Internet.
Githubは<https://github.com/>で運営されているサービスです。GithubはGitリポジトリのための集中型ストレージを提供します。Githubはオープンインターネットで自由にアクセスできます。
GitHub provides a simplified and integrated interface to Git and also provides basic user management, an issue tracker, associated wikis, project hosting, and other features.
GitHubはgitに簡単で統合されたインターフェースを提供し、基本的なユーザー管理、問題トラッカー、関連するウィキ、プロジェクトホスティング、その他の機能も提供します。
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 from use of the service is through increased numbers of reviews of the document and associated issues, along with other improvements that come from facilitating participation by a broader community.
Githubには多数のプロジェクトと、貢献者の非常に大きなコミュニティがあります。一部のIETFワーキンググループがサービスの使用に恩恵を受けている1つの方法は、ドキュメントのレビュー数と関連する問題の数を増やすことで、より広範なコミュニティによる参加を促進することから来ています。
Git is not the only version control system available, nor is GitHub the only possible choice for hosting. There are other services that host revision control repositories and provide similar additional features as GitHub. For instance, BitBucket (https://bitbucket.org/) and GitLab (https://about.gitlab.com/) provide similar feature sets. In addition to a hosted service, software for custom installations exists.
GITは利用可能な唯一のバージョン管理システムではありません。リビジョン管理リポジトリをホストし、GitHubと同様の追加機能を提供する他のサービスがあります。たとえば、BitBucket（https://bitbucket.org/）とgitlab（https://about.gitlab.com/）は、同様の機能セットを提供します。ホストされたサービスに加えて、カスタムインストール用のソフトウェアが存在します。
This document concentrates primarily on GitHub as it has a large and active community of contributors. As a result, some content might not be applicable to other similar services. A working group that decides to adopt an alternative tool or service can still benefit from the general guidance in this document.
この文書は、主にGitHubに集中しているため、貢献者の大規模で活発なコミュニティがあります。その結果、いくつかのコンテンツが他の同様のサービスには適用できない可能性があります。代替ツールやサービスを採用することを決定するワーキンググループは、まだこの文書の一般的なガイダンスから利益を得ることができます。
This document aims to describe how a working group might best apply GitHub to their work. The intent is to allow each working group considerable flexibility in how they use GitHub.
この文書は、ワーキンググループが自分の仕事にGitHubを最もよく適用するのがどのように適用されるのかを説明することを目的としています。意図は、各作業部グループがGitHubを使用する方法においてかなりの柔軟性を可能にすることです。
This document requires that policies for use of GitHub are agreed upon and clearly communicated within the working group (see Section 2). The remainder of the document contains guidelines and advice on how to construct a workable policy.
この文書では、GitHubの使用ポリシーが作業部会に合意され、明確に伝達されることが必要です（セクション2を参照）。この文書の残りの部分には、作業可能なポリシーを構築する方法に関するガイドラインとアドバイスが含まれています。
The requirements here apply to the case where a working group decides to use GitHub as a primary means of interaction. Individuals can set their own policies when using GitHub for managing their own drafts or for managing drafts that they edit on behalf of a working group that has not explicitly adopted GitHub.
ここでの要件は、作業グループが相互作用の主な手段としてGitHubを使用することを決定する場合に適用されます。個人は、GitHubを自分のドラフトを管理するために、または明示的にgithubを採用していないワーキンググループを代表して編集しているドラフトを管理するために、自分のポリシーを設定できます。
For both sets of users, this document aims to provide some amount of advice on practices that have been effective.
どちらのユーザーのセットの場合、この文書は効果的であった慣行に関する何らかのアドバイスを提供することを目的としています。
This document only aims to address use of GitHub in developing documents. A working group could choose to use the tool to aid in managing their charter or session materials such as agendas, minutes, and presentations. Though the advice here might apply more broadly, using GitHub to manage other material is out of scope for this document.
この文書は、文書の開発におけるGitHubの使用に対処することを目的としています。ワーキンググループは、議論、分、およびプレゼンテーションなどの憲章またはセッション資料の管理を支援するためにツールを使用することを選択できます。ここでのアドバイスはより広く適用されるかもしれませんが、GitHubを使って他の資料を管理することはこの文書の範囲外です。
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
「必須」、「必須」、「必須」、「SHALL」、「必ず」、「推奨する」、「推奨する」、「推奨する」、「推奨する」、「推奨する」、「5月」「この文書では、BCP 14 [RFC2119] [RFC8174]に記載されている場合に解釈されるべきです。
This document uses a lot of terms related to Git and GitHub; see [GLOSSARY] for information on these terms.
この資料はGITとGithubに関連する多くの用語を使用しています。これらの用語については、[用語集]を参照してください。
The following administrative rules provide the necessary oversight and transparency.
次の管理規則は、必要な監視と透明性を提供します。
Organizations are a way of forming groups of contributors on GitHub. The working group SHOULD create a new organization for its work. A working group organization SHOULD be named consistently so that it can be found. For instance, the name could be ietf-wg-<wgname>, as recommended in [RFC8875].
組織はGitHubの貢献者のグループを形成する方法です。ワーキンググループはその作業のために新しい組織を作成するべきです。ワーキンググループの組織は、それが見つかる可能性があるように一貫して名前を付けます。たとえば、[RFC8875]で推奨されるように、名前はIETF-WG-<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.
単一の組織は、すべてのIETFアクティビティ、またはエリア内のすべてのアクティビティに使用しないでください。大規模な組織は、一般管理タスクにあまりにも多くのオーバーヘッドを作成します。
GitHub requires that each organization have at least one owner. The owners for a working group repository MUST include responsible area directors and the IETF Secretariat. Working group chairs SHOULD also be included as owners. Area directors MAY also designate a delegate that becomes an owner, such as another area director from the same area. An organization MUST have at least two owners.
GitHubでは、各組織に少なくとも1人の所有者がいることが必要です。ワーキンググループリポジトリの所有者には、責任ある地域取締役とIETF事務局が含まれていなければなりません。ワーキンググループの議長も所有者として含まれるべきです。エリアディレクターはまた、同じエリアからの別のエリアディレクターなど、所有者になる代理人を指定することもできます。組織には少なくとも2つの所有者が必要です。
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 [RFC8875].
これらのガイドラインに付随する組織の作成に関する詳細は[RFC8875]にあります。
Each working group MAY set its own policy as to whether and how it uses GitHub. It is important that occasional participants in the working group and others accustomed to IETF tools be able to determine this and easily find the policy and GitHub organization.
各ワーキンググループは、それがGitHubを使用するかどうかに関して独自のポリシーを設定することができます。ワーキンググループの時折参加者が、IETFツールに慣れている他の人たちがこれを決定し、政策とgithub組織を簡単に見つけることができます。
A simple example of how to do this is to include a link to the GitHub organization on the working group charter page in the datatracker. Similarly, if there are additional resources, such as mailing lists, links to those resources could also be added.
これを行う方法の簡単な例は、DataTrackerのワーキンググループの憲章ページ上のGitHub組織へのリンクを含めることです。同様に、メーリングリストなどの追加のリソースがある場合は、それらのリソースへのリンクも追加できます。
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 makes working group policies available to casual contributors who might only interact with the GitHub repository.
リポジトリには、含まれている文書の管理に適用されるポリシーのコピーまたは参照を含める必要があります。プロセスの詳細を使用してリポジトリ内のREADMEまたは貢献ファイルの更新は、メーリングリストアーカイブ以外の安定した場所にプロセスが記録されます。これにより、GitHubリポジトリとのみ対話する可能性があるカジュアルな貢献者が利用できるワーキンググループポリシーもあります。
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. The README SHOULD contain a link to the CONTRIBUTING file.
GitHubは特定のページ上の貢献ファイルにすぐにリンクします。このファイルは、新しい貢献者が必要とする情報については、ReadMeを好みに使用する必要があります。READMEには、貢献ファイルへのリンクを含める必要があります。
In addition to working group policies, notices on repositories MUST include citations for the IETF Note Well (https://www.ietf.org/about/ note-well/).
ワーキンググループのポリシーに加えて、リポジトリ上の通知には、IETFメモの入意（https://www.ietf.org/about/ NOLL /）の引用を含める必要があります。
Working group chairs are responsible for determining how to best accomplish the charter objectives in an open and transparent fashion. The working group chairs are responsible for determining if there is interest in using GitHub and for making a consensus call about whether the proposed policy and use is acceptable.
ワーキンググループの椅子は、憲章の目的を開放的で透明な方法で最もよく達成する方法を決定する責任があります。ワーキンググループの椅子は、GitHubを使用することに興味があるかどうか、および提案されたポリシーと使用が許容できるかどうかについての合意を呼び出すために決定する責任があります。
Chairs SHOULD involve area directors in any decision to use GitHub, especially where substantive discussion of issues is permitted as described in Section 5.3.
椅子は、特に議論を使用するためのあらゆる決定において、特に問題についての実質的な議論が可能である場合には、セクション5.3に記載されているように許可されるべきである。
Working group chairs decide what GitHub features the working group will rely upon. Section 4 contains a more thorough discussion on the different features that can be used.
ワーキンググループの椅子作業グループが依存するGitHubがどのようなgithubを決定します。セクション4には、使用できるさまざまな機能に関するより徹底的な議論が含まれています。
Working group chairs who decide to use GitHub MUST inform the working group of their decision on the working group mailing list. An email detailing how the working group intends to use GitHub is sufficient, though it might be helpful to occasionally remind new contributors of these guidelines.
Githubを使用することを決定したワーキンググループの議長は、ワーキンググループのメーリングリストに対する自分の決定のワーキンググループに知らなければなりません。ワーキンググループがGitHubを使用しようとしている方法を詳述するのは、これらのガイドラインの新しい貢献者を間違いなく思い出させるのに役立ちます。
Working group chairs are responsible for ensuring that any policy they adopt is enforced and maintained.
ワーキンググループの椅子は、採用されている方針が強制され維持されることを保証する責任があります。
The set of GitHub features (Section 4) that the working group relies upon need to be clearly documented in policies. This document provides some guidance on potential policies and how those might be applied.
作業グループが頼っているGithub機能のセット（セクション4）は、政策に明確に文書化される必要があることを示しています。この文書は、潜在的なポリシーに関するいくつかのガイダンスとそれらがどのように適用されるかを提供します。
Features that the working group does not rely upon can be made available to document editors. Editors are then able to use these features for their own purposes. For example, though the working group might not formally use issues 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 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 are encouraged to 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 such public repository MUST follow the IETF Note Well and bear notices; see Section 2.2. This recognizes that editors have traditionally chosen their own methods for managing the documents they edit but preserves the need for contributors to understand their obligations with respect to IETF processes.
作業グループがgithubを使用することを明示的に選択していなくても、ドキュメントエディタは編集した文書に対して独立してGitHUBを使用できます。そのような公開リポジトリは、IETFの注文をよく従わなければなりません。セクション2.2を参照してください。これは、編集者が伝統的に編集された文書を管理するための独自の方法を伝統的に選択していることを認識していますが、IETFプロセスに関して彼らの義務を理解するための貢献者の必要性を保持しています。
Work done in GitHub has no special status. The output of any activity using GitHub needs to be taken to the working group and is subject to approval, rejection, or modification by the working group as with any other input.
GitHubで行われた作業には特別なステータスはありません。GitHUBを使用した任意の活動の出力は、作業グループに連れて行かれ、他の入力と同様に、ワーキンググループによる承認、拒否、または変更の対象となります。
New repositories can be created within the working group organization at the discretion of the chairs. Chairs could decide to only create new repositories for adopted working group items, or they might create repositories for individual documents on request.
新規リポジトリは、椅子の裁量でワーキンググループ組織内で作成できます。椅子は、採用されたワーキンググループアイテムのための新しいリポジトリを作成すること、または要求に応じて個々の文書のためのリポジトリを作成することを決定することができます。
Maintaining private repositories for working group products is not recommended without specific cause. 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 for working group documents MUST be made public.
ワーキンググループ製品のプライベートリポジトリを維持することは、特定の原因なしではお勧めできません。たとえば、セキュリティの脆弱性を詳細に説明する文書は、初期パブリケーションの前にインターネットドラフトとして非公開に保つことができます。インターネットドラフトが公開されると、ワーキンググループの文書のリポジトリを公開する必要があります。
The adoption status of any document MUST be clear from the contents of the repository. This can be achieved by having the name of the document reflect status (that is, draft-ietf-<wgname>-... indicates that the document was adopted) or through a prominent notice (such as in the README).
任意の文書の採用状況は、リポジトリの内容から明確でなければなりません。これは、文書の名称を反映状態（つまり、ドラフトが採用されたことを示している）、または顕著な通知（READMEなど）を介して実現できます。
Experience has shown that maintaining separate repositories for independent documents is most manageable. This allows the work in that repository to be focused on a single item.
経験は、独立した文書のための別々のリポジトリを維持することが最も扱いやすいことを経験しました。これにより、そのリポジトリ内の作業を単一の項目に焦点を合わせることができます。
Closely related documents, such as those that together address a single milestone, might be placed in a single repository. This allows editors to more easily manage changes and issues that affect multiple documents.
単一のマイルストーンをまとめてアドレス指定するものなど、密接に関連した文書を単一のリポジトリに配置することができます。これにより、編集者は複数の文書に影響を与える変更や問題をより簡単に管理できます。
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 (Section 3.3).
同じリポジトリ内の複数の文書を維持することで、個々の文書に悪影響を及ぼすオーバーヘッドを追加できます。たとえば、問題に影響を与える文書を識別するための追加のマーキングが必要になる場合があります。また、編集者はすべてリポジトリへの書き込みアクセス権を持っているため、より大きなリポジトリへの書き込みアクセス権を持つ人々のセットを管理することはより困難です（セクション3.3）。
Working group chairs MUST give document editors write access to document repositories. This can be done by creating teams with write access and allocating editors to those teams or by making editors collaborators on the repository.
ワーキンググループの椅子は、ドキュメントエディタの書き込みアクセス権をドキュメントリポジトリへのアクセス権を与える必要があります。これは、書き込みアクセスを使用してチームを作成し、それらのチームにエディタを割り当てること、またはリポジトリ上の編集者のコラボレータを作成することによって行うことができます。
Working group chairs MAY also grant other individuals write access for other reasons such as maintaining supporting code or build configurations. Working group chairs, as administrators or owners of the organization, might also have write access to repositories. Users other than document editors, including chairs, SHOULD NOT make changes to working group documents without prior coordination with document editors.
作業グループの椅子はまた、サポートコードまたはビルド構成の維持など、他の理由で他の個人の書き込みアクセスを許可することができる。組織の管理者または所有者としてのワーキンググループの議長も、リポジトリへの書き込みアクセス権を持つ可能性があります。椅子を含む文書編集者以外のユーザーは、ドキュメントエディタとの事前に調整されずにワーキンググループの文書を変更しないでください。
A working group MAY create a team for regular contributors that is only given read access to a repository. This does not confer additional privileges on these contributors; it instead allows for issues and pull requests to be assigned to those people. This can be used to manage the assignment of editorial or review tasks to individuals outside of the editor team.
ワーキンググループは、リポジトリへの読み取りアクセスのみが与えられている通常の貢献者のためのチームを作成することができます。これはこれらの貢献者に追加の特権を与えません。それは代わりに問題と引っ張り要求をそれらの人々に割り当てることを可能にします。これは、エディタチームの外部での個人への編集の割り当てを管理するために使用することができます。
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 are more accessible for new contributors, though ultimately, decisions about format are left to document editors.
標準XML形式[RFC7991]に加えて、ドキュメントエディタは、マークダウンなどの文書を編集するための異なる入力フォームを使用することを選択することができます。マークダウンベースのフォーマットは新しい貢献者にとってアクセスが起こりやすいですが、最終的には、フォーマットに関する決定が編集者に残されています。
Formats that are not text-based SHOULD NOT be used, as these are ill-disposed to the sorts of interaction that revision control enables.
テキストベースではないフォーマットは、リビジョンコントロールが有効にする対話型の種類に違反しているため、使用しないでください。
Contributions to documents come in many forms. GitHub provides a range of options in addition to email. Input on GitHub can take the form of new issues and pull requests, comments on issues and pull requests, and comments on commits.
文書への貢献は多くの形で来ます。GitHubは、電子メールに加えて様々なオプションを提供します。GitHubの入力は、新しい問題の形をとり、リクエストを引いて、問題、およびリクエストの入力、およびコミットについてのコメントを取ります。
The GitHub issue tracker can be an effective way of managing the set of open issues on a document. Issues, both open and closed, can be a useful way of recording decisions made by a working group.
GitHub Issue Trackerは、文書上の開いた問題のセットを管理する効果的な方法です。Open and Closeの両方の問題は、ワーキンググループによって行われた決定を記録するための便利な方法です。
Issues can be given arbitrary labels, assigned to contributors, and assembled into milestones. The issue tracker is integrated into the repository; an issue can be closed using a special marker in a commit message.
問題に割り当てられ、マイルストーンに組み立てる任意のラベルを課すことができます。問題トラッカーはリポジトリに統合されています。問題は、コミットメッセージで特別なマーカーを使用して閉じることができます。
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.
GitHubを使用することを決定するとき、ワーキンググループの椅子は、GitHubの発行トラッカーがどのように使用されるかを決定しなければなりません。問題トラッカーの使用は問題の存在を記録することに限定される可能性があります。または、貢献者間の実質的な技術的協議のための会場として使用される可能性があります。
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 Section 5.
ワーキンググループポリシーは、問題を使用してすべての実質的な変更が追跡されることを要求する場合があります。GitHub Issue Trackerを使用するための推奨ポリシーはセクション5の主な主題です。
A system of labeling issues can be effective in managing issues. For instance, marking substantive issues separately from editorial can be helpful at guiding discussion. Using labels can also be helpful in identifying issues for which consensus has been achieved but that require editors to integrate the changes into a document.
ラベリングの問題のシステムは、問題を管理するのに効果的です。例えば、編集者とは別に実質的な問題をマーキングすることは議論を指すのに役立ちます。ラベルを使用すると、コンセンサスが達成された問題を特定するのに役立ちますが、エディタを文書に統合するために編集者が必要です。
Labels can be used to identify particular categories of issues or to mark specific issues for discussion at an upcoming session.
ラベルを使用して、特定のカテゴリの問題を特定したり、次のセッションで議論のための特定の問題をマークしたりできます。
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. Section 5.4 describes some basic strategies that might be adopted to manage decision-making processes.
椅子は、ワーキンググループへのラベルの使用に特別に関連するプロセスを伝達します。これにはラベルの意味、およびこれらのラベルを適用して削除することができます。セクション5.4は、意思決定プロセスを管理するために採用される可能性があるいくつかの基本的な戦略を説明しています。
Editors have write access to repositories, which also allows them to close issues. The user that opens an issue is also able to close the issue. Chairs MUST provide guidance on who is permitted to close an issue and under what conditions.
編集者はリポジトリへの書き込みアクセス権を持っています。問題を開くユーザーも問題を閉じることができます。椅子は、誰が問題を閉じてどのような条件下でも許されている人にガイダンスを提供しなければなりません。
Restrictions on who can close an issue and under what circumstances are generally not advisable until a document has reached a certain degree of maturity.
誰が問題を閉じるか、そして文書が特定の程度の成熟度に達するまで一般的にどのような状況では妥当ではないかを制限する。
Issues that have reached a resolution that has working group consensus MUST NOT be reopened unless new information is presented.
ワーキンググループのコンセンサスを持つ解決策に達した問題は、新しい情報が表示されない限り再度開かないようにしてください。
For long-running work items, new contributors often raise issues that have already been resolved. Moreover, there could be temptation to reopen contentious issues resolved with rough consensus. Determining whether arguments presented in favor of reopening an issue represents new information might require some discussion in the working group.
長期的な作業項目のために、新しい貢献者はしばしば解決されている問題を提起します。さらに、大まかなコンセンサスで解決された議論のある問題を再開するための誘惑があるかもしれません。問題の再開を支持している議論が提示されたかどうかを判断すると、新たな情報が作業グループでいくつかの議論が必要な場合があります。
Chairs are empowered to exercise discretion in determining whether or not to reopen issues. For more difficult matters, the chairs MAY insist that the working group reach consensus on whether an issue should be reopened. Note, however, that any product of this process still needs to have the support of rough consensus in the working group, which could justify reopening issues.
椅子は、問題を再開するかどうかを判断する際に裁量を行使することに力を与えられています。より困難な事項については、椅子は、問題が再開されるべきかどうかについて作業グループが合意に達すると主張することがあります。ただし、このプロセスの製品の任意の製品はまだ作業グループ内の大まかなコンセンサスをサポートする必要があります。これにより、問題の再開の問題を正当化できます。
A pull request is a GitHub feature that allows a user to request a change to a repository. A user does not need to have write access to a repository to create a pull request. A user can create a "fork", or copy, of any public repository. The user has write access to their own fork, allowing them to make local changes. A pull request asks the owner of a repository to merge a specific set of changes from a fork (or any branch) into their copy.
プル要求は、ユーザーがリポジトリへの変更を要求できるようにするGitHub機能です。ユーザは、プル要求を作成するためにリポジトリへの書き込みアクセス権を持つ必要はありません。ユーザーは、パブリックリポジトリの「フォーク」、またはコピーを作成できます。ユーザーは自分のフォークへの書き込みアクセスを持っており、地域の変更を加えることができます。プル要求は、リポジトリの所有者に、特定の変更セットをフォーク（または任意のブランチ）からコピーにマージするように求められます。
Editors are encouraged to make pull requests for all substantial changes rather than committing directly to the "primary" branch of the repository. See Section 5.3.2 for discussion on what constitutes a substantial change. A pull request creates an artifact that records the reasons for changes and provides other contributors with an opportunity to review the change. Ideally, pull requests that address substantive issues mention the issue they address in the opening comment. A working group policy could require that pull requests be used in this fashion.
編集者は、リポジトリの「プライマリ」ブランチに直接コミットするのではなく、すべての実質的な変更に対するプル要求を作成することをお勧めします。実質的な変更を構成するものについての議論については、5.3.2節を参照してください。PULLリクエストは、変更の理由を記録し、その変更を確認する機会を提供する他の貢献者を提供するアーティファクトを作成します。理想的には、実質的な問題に対処するリクエストをプルして、オープニングコメントでアドレスがあるという問題について説明しています。作業グループポリシーでは、この方法でプル要求を使用する必要があります。
| Note: This document assumes that there is a unified effort on a
| document, all concentrated on a single Git branch. More
| advanced usage of Git is not in the scope of this document.
Pull requests have many of the same properties as issues, including the ability to host discussion and bear labels. Critically, using pull requests creates a record of actions taken.
プルリクエストには、ディスカッションとクマのラベルを発信する能力を含む、問題と同じプロパティが多くあります。クリティカルには、プル要求を使用すると、取得されたアクションの記録が作成されます。
For significant changes, leaving a pull request open until discussion of the issue within the working group concludes allows the pull request to track the discussion and properly capture the outcome of discussions. Pull requests can be updated as discussions continue, or in response to feedback.
作業グループ内の問題についての議論が議論を追跡し、議論の結果を適切に捉えることを可能にするまで、プル要求を開くことが大幅に変更された。ディスカッションが続行されたとき、またはフィードバックに応答して、プル要求を更新することができます。
Groups of editors could adopt a practice of having one editor create a pull request and another merge it. This ensures that changes are reviewed by editors. Editors are given discretion in how they manage changes amongst themselves.
編集者のグループは、1つのエディタを持つことの慣習を採用することができ、もう1つは別のマージをマージします。これにより、変更がエディタによって検討されます。編集者は、自分の間の変更をどのように管理するかに裁量を与えられます。
In addition to the features that pull requests share with issues, users can also review the changes in a pull request. This is a valuable feature, but it presents some challenges.
要求を問題と共有する機能に加えて、ユーザーはプル要求の変更を確認することもできます。これは貴重な機能ですが、いくつかの課題があります。
Comments in a review other than a summary are attached to specific lines of the proposed change. Such comments can be hard or impossible to find if changes are subsequently made to the pull request. This is problematic for contributors who do not track discussions closely.
要約以外のレビューのコメントは、提案された変更の特定の行に添付されています。そのようなコメントは、変更が引き続きプル要求に行われるかどうかを見つけることが難しくても不可能です。これは、議論を綿密に追跡しない貢献者にとって問題があります。
For this reason, working group chairs SHOULD discourage the use of inline comments for substantial technical discussion of issues.
このため、ワーキンググループの議長は、問題の実質的な技術的な議論のためのインラインコメントの使用を妨げるべきです。
A working group MUST determine who is permitted to merge pull requests. Document editors SHOULD be permitted to merge pull requests at their discretion. This requires that editors exercise some judgment. Working group chairs MAY occasionally identify a pull request and request that editors withhold merging until working group consensus has been assessed.
ワーキンググループは、誰がプル要求をマージすることが許可されているかを決定しなければなりません。ドキュメントエディタは、その裁量でプル要求をマージすることを許可されるべきです。これには、編集者がいくつかの判断を行使することが必要です。ワーキンググループの椅子は時々引っ張り要求を特定し、編集者がワーキンググループのコンセンサスが評価されるまでマージを差し控えることを要求することができます。
Note that the copy of a document that is maintained on GitHub does not need to be a perfect reflection of working group consensus at every point in time. Document editors need some flexibility in how they manage a document.
GitHubで維持されている文書のコピーは、あらゆる時点でワーキンググループのコンセンサスを完全に反映する必要はありません。ドキュメントエディタには、文書を管理する方法に柔軟性が必要です。
GitHub produces individualized email notifications of activity that each user can adjust to their preferences. In addition to these, some working groups have created read-only mailing lists that receive notifications about activity on working group repositories. The volume of information on these lists can be too high to monitor actively, but access to an archive of actions can be useful.
GitHubは、各ユーザーが自分の好みに合わせて調整できる活動の個別の電子メール通知を生成します。これらに加えて、一部のワーキンググループは、ワーキンググループリポジトリのアクティビティに関する通知を受け取る読み取り専用メーリングリストを作成しました。これらのリストに関する情報の量は積極的に監視するには高すぎる可能性がありますが、アクションのアーカイブへのアクセスは役に立ちます。
An alternative is to rely on periodic email summaries of activity, such as those produced by a notification tool like github-notify-ml (https://github.com/dontcallmedom/github-notify-ml). This tool has been used effectively in several working groups, though it requires server infrastructure.
代替案は、github-notify-mlのような通知ツール（https://github.com/dontcallmedom/github-notify-ml）など、アクティビティの定期的な電子メール概要に頼ることです。このツールは、サーバーインフラストラクチャが必要ですが、このツールはいくつかのワーキンググループで効果的に使用されています。
Additionally, clear reporting about the changes that were included in each revision of an Internet-Draft helps ensure that contributors can follow activity. This might be achieved by requesting that editors provide a change log that captures substantive changes to the document in each revision.
さらに、インターネットドラフトの各リビジョンに含まれている変更についての明確な報告は、貢献者が活動に従うことができることを保証します。これは、エディタが各リビジョンで文書に実質的な変更を取得する変更ログを提供することを要求することによって達成されるかもしれません。
Current experience with use of GitHub suggests a few different approaches to greater use of the tool in working groups.
Githubを使用した現在の経験は、作業群の工具をより多く使用するためのいくつかの異なるアプローチを示唆しています。
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 is 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.
このセクションでは、GitHubと対話するためのいくつかの基本的なモードについて説明します。これは、文書管理が正式に使用されている唯一の機能である非常に軽量の相互作用から始まります。次に、GitHubの発行追跡機能を徐々により集中的に使用することについて説明します。これらのアプローチは主に実質的な問題の議論がどのように管理されるかに異なります。この文書のアドバイスのほとんどはすべてのモデルにも同様に当てはまります。
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. It is possible to use different processes for different documents in the working group.
作業グループは、これらの方針を彼らのニーズに合わせて調整することができますが、IETF全体の一貫性のために無償変更を回避することをお勧めします。ワーキンググループ内の異なる文書に対して異なるプロセスを使用することが可能です。
Working group chairs are responsible for confirming 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.
ワーキンググループの椅子は、作業部会がどのプロセスを採用するための合意があることを確認する責任があります。特に、より緊密に制御されたプロセスの導入は、すでに文書に撮影されている特権位置の影響を持つことができ、それは別の視点を欠く可能性があります。
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.
このインタラクションモードでは、GitHubリポジトリは文書への変更を管理するために使用されますが、その作業の大部分は電子メール、対面会議、およびその他の伝統的な相互作用を使用して行われます。このポリシーの意図は、プロセスの複雑さを最小限に抑えながら、GitHubを使用して文書化および発行管理を有効にすることです。
In the version of this mode with the least interaction with GitHub, a repository is created for the purposes of document management by editors. Editors might maintain issues and pull requests for their own benefit, but these have no formal standing in the working group process.
GitHUBとの対話が少なく、このモードのバージョンでは、編集者によるドキュメント管理の目的でリポジトリが作成されます。編集者は自分の利益のために問題を維持し、要求を引き立てるかもしれませんが、これらにはワーキンググループプロセスに正式なスタンディングがありません。
In addition to managing documents, the working group might choose to use GitHub 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.
ドキュメントの管理に加えて、作業グループは優れた問題を追跡するためにGitHubを使用することを選択するかもしれません。この対話モードでは、実質的な技術的議論の存在の記録は、問題トラッカーの問題を使用して追跡されます。ただし、常にメーリングリストでは常に行われています。
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 limited to recording the state of issues. Only editorial matters can be resolved using the issue tracker.
このモードの下では、問題とプル要求を誰でも開くことができますが、実質的なものとみなされるものは、メーリングリストで独占的に解決されなければなりません。GitHubに関する議論は問題の状態を記録するために限定されています。発行トラッカーを使用して解決できるのは編集上の問題だけです。
Chairs and editors are given discretion in determining what issues are substantive. As documents mature, it is generally prudent to prefer consulting the mailing list where there is doubt. As with other working group decisions, chairs are the arbiters in case of dispute.
椅子と編集者には、どの問題が実質的なものがあるかを判断する際に裁量が与えられています。文書が成熟するにつれて、疑問があるところにメーリングリストを相談することをお勧めします。他のワーキンググループの決定と同様に、議論の場合は椅子がアービターです。
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.
この対話モードの再発的な問題は、議論トラッカーで自発的に発展するための議論の傾向です。これには、椅子や編集者からの程度の規律が必要です。
Retaining mailing lists as the primary venue for discussion of substantive matters ensures that this mode, along with the document management mode, is 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 working group mailing list.
実質的な問題についての議論のための主な会場としてのメーリングリストを保持することで、このモードは文書管理モードとともに、作業グループの既存の作業慣行と最も互換性があります。どちらのモデルの下で動作するワーキンググループの参加者は、ワーキンググループのメーリングリストからグループの作品についての関連するすべての通信を受信することが合理的に期待できます。
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.
メーリングリストは決定を下すために使用されますが、問題トラッカーは依然として問題の状態の有用な記録です。椅子や編集者が解決されたときに問題を解決するときに、椅子や編集者が問題の問題の詳細を記録した場合に便利です。
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.
このGitHub相互作用モードは、GitHubの問題に実質的な技術的な問題に関する議論が発生することが許されているという点で、他のモードとは異なります。決定は常にメーリングリストの確認の対象となりますが、参加者は問題トラッカーで実質的な議論を行うことができます。場合によっては、ワーキンググループのメーリングリストを使用せずにいくつかの決定を下すことが含まれます。
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.
ワーキンググループのメーリングリストは、問題の議論が他の場所で発生した場合でも、意思決定のための重要な会場です。ワーキンググループメーリングリストには、一般的に問題の議論に従う人よりも幅広い聴衆が含まれているため、難しい問題は常にリストの議論から恩恵を受けます。
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 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 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]).
メーリングリストを使用して困難または物議を醸す問題を解決することは強く奨励されます。そのような場合、課題追跡者は、デザインチームプロセスと同様の行に沿って、メーリングリストの議論を開始する前に、問題の理解をより十分に開発するために使用される可能性があります（[RFC2418]のセクション6.5を参照）。
As a more involved process, adopting this mode can require changes in policies as documents become more mature.
より多くの関与するプロセスとして、このモードを採用することは、文書がより成熟するにつれてポリシーの変更を必要とする可能性があります。
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.
プロトコルの設計の初期段階の間に、椅子は編集者が問題のあらゆる面を管理することを可能にし得る。編集者は、編集者が必要とされる変更を加えるなど、技術的な問題を特定し解決する方法について決定を下すことができます。
The primary reason to grant editors more discretionary power is to improve the speed with which changes can be made. In many cases, documents that are adopted by a working group are already sufficiently mature, and a looser process is not beneficial. A looser process increases the risk of missing issues that need working group consensus and integrating substantive changes based on decisions that don't reflect the consensus of the working group.
エディタを付与する主な理由は、より慎重な電力を与えることで、変更が加えることができる速度を向上させることです。多くの場合、ワーキンググループによって採用されている文書はすでに十分に成熟しており、緩いプロセスは有益ではありません。Looserプロセスは、ワーキンググループのコンセンサスを必要とする不足している問題のリスクを高め、ワーキンググループのコンセンサスを反映していない決定に基づいて実質的な変更を統合します。
Changes made by editors under this process do not lack options for identifying and correcting problems. 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. Also, process checkpoints like Working Group Last Call (WGLC; Section 7.4 of [RFC2418]) provide additional safeguards against abuse.
このプロセスの下でエディタによって行われた変更は、問題を識別して修正するためのオプションを欠いていません。GitHubとGitは、変更が追跡され、監査できるようにするためのツールを提供します。通常のワーキンググループプロセス内では、インターネットドラフトが通常のレビューを受けると予想されます。また、ワーキンググループの最後の呼び出しのようなプロセスチェックポイント（WGLC; [RFC2418]のセクション7.4）は、虐待に対して追加の保護措置を提供します。
Working groups are advised against allowing editors this degree of flexibility for the entirety of a document life cycle. Once a document is more stable and mature, it could be useful to move to a more tightly controlled process.
ワーキンググループは、文書ライフサイクルの全体のこの程度の柔軟性を編集者に許可することを勧めます。文書がより安定して成熟すると、それはより厳密に制御されたプロセスに移動するのに役立ちます。
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.
文書が成熟するにつれて、文書全体がワーキンググループのサポートを保持しているだけでなく、その変更はより広い協議なしに行われないことを理解することがより重要になります。
Chairs MAY choose to manage the process of deciding which issues are substantive. For instance, chairs might reserve the ability to use the "design" label for new issues (see Section 5.4.1) and to close issues marked as "design". Chairs SHOULD always allow document editors to identify and address editorial issues as they see fit.
椅子はどの問題が実質的な問題を決定するプロセスを管理することを選択するかもしれません。たとえば、チェアは、新しい問題のために「デザイン」ラベルを使用する能力を留保する（セクション5.4.1を参照）、「設計」としてマークされている問題を閉じることがあります。チェアは常に文書編集者がフィットするにつれて編集上の問題を識別してアドレス指定できるようにする必要があります。
As documents mature further, explicit confirmation of technical decisions with the working group mailing list becomes more important.
文書がさらに成熟するにつれて、ワーキンググループのメーリングリストでの技術的決定の明示的な確認がより重要になる。
Chairs can declare working group consensus regarding the resolution of issues in the abstract, allowing editors discretion on how to capture the decisions in documents.
椅子は抽象の問題の解決に関してワーキンググループのコンセンサスを宣言することができ、編集者は文書内の決定を把握する方法に関する編集者の裁量を可能にします。
More mature documents require not only consensus, but consensus about specific text. Ideally, substantive changes to documents that have passed WGLC are proposed as pull requests and MUST be discussed on the mailing list. Having chairs explicitly confirm consensus on changes ensures that previous consensus decisions are not overturned without cause. Chairs MAY institute this stricter process prior to WGLC.
より成熟した文書には、コンセンサスだけでなく、特定のテキストについてのコンセンサスが必要です。理想的には、WGLCに合格した文書への実質的な変更は、プル要求として提案されており、メーリングリストで説明する必要があります。椅子を持つことは、変更に対する合意を明示的に確認することで、以前のコンセンサスの決定が原因なしで覆われていないことを確認します。椅子は、WGLCの前にこの厳格なプロセスを研究することができます。
| Note: 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.
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.
問題の管理に問題ラベルを使用するためのいくつかのスキームが正常に使用されています。このセクションでは、これらの戦略とそれらがどのように適用されるかについて概説します。
A design/editorial split (see Section 5.4.1) is useful in all cases in which the issue tracking capability is used. A working group that only uses GitHub for issue tracking might find that distinction sufficient for their needs.
デザイン/編集分割（セクション5.4.1を参照）は、問題追跡機能が使用されているすべての場合において役立ちます。問題追跡のためにGitHubのみを使用するワーキンググループは、そのニーズに十分な区別を見つけるかもしれません。
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.
ワーキンググループまたは編集者は、選択したときに追加のラベルを使用することがあります。プロセスの一部として使用されるラベルは、プロセスがワーキンググループの椅子によって文書化され発表される必要があります。編集者は、それらの問題に適切なプロセスの有意性があることなく問題を管理するためにラベルを使用することを許可されるべきです。
The most important distinction about an issue is whether it is substantive. The labels of "editorial" and "design" are used to represent this distinction.
問題について最も重要な区別はそれが実質的なものであるかどうかです。「編集」および「設計」のラベルは、この区別を表すために使用されます。
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.
「編集」と表示された問題は、問題に対処する範囲を除く文書に対して実質的な影響を与えません。「編集」の問題の解決は、編集者の裁量を残すことができます。
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.
「デザイン」として表示されている問題は、文書に実質的な影響を与える可能性があります。プロトコル仕様の場合、「設計」の問題は、実装または相互運用性の要件に影響を与える可能性があるものです。解像度が変更されない場合でも、「設計」の問題に対処することは、最終的にはワーキンググループのコンセンサスを必要とします。
This distinction can be applied to all types of documents. For instance, a "design" issue for an Informational document might be raised to discuss possible changes to important concepts in the document.
この区別はあらゆる種類の文書に適用できます。たとえば、情報文書の「デザイン」の問題が提起されて、文書内の重要な概念に可能な変更を議論することができます。
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, the labeling of issues can be used to help manage working group decisions.
ラベルを使用してプロセスを管理できます。文書が成熟して問題が多数になるにつれて、ラベルを使用して問題の状況を明確にマークすることができます。特に、問題の表示は、ワーキンググループの決定を管理するのに役立ちます。
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 on 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.
成熟した文書の場合、解決策の問題があるがテキストへの変更に対する特定の提案は、アプローチに合意があるが特定の提案なしに「エディタレディ」とマークされる可能性がある。椅子はこれを使うかもしれませんが、議論が完了し、その編集者がテキストの建設において裁量を与えられることになるかもしれません。
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.
対照的に、特定のテキストが問題を解決するための前提条件であれば、より成熟した文書の場合は「プロポーザルレディ」ラベルを使用して、許容できる解決策を持つと信じる問題を編集者によって使用することができます。
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]).
解決された問題については、正式なワーキンググループの決定が行われた問題をマークするために、「has-consensus」ラベルが椅子によって使用される可能性があります（[RFC2418のセクション6.1）。
A "future" 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.
「未来」または「次のバージョン」ラベルを使用して、特に解決方法を行っていない場合には、将来のバージョンの、または将来のバージョン、または拡張機能の問題を保存することができます。
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.
複数の相互に関連した文書または複雑な文書を持つリポジトリまたは複数の論理コンポーネントを含む複雑な文書は、作業のさまざまな側面を識別するラベルから利益を得ることがあります。コンポーネントの適切なラベルの選択は、特定の文書の構造によって異なります。
Other labels can be used depending on the needs of editors and working group processes. For example,
エディタのニーズやワーキンググループプロセスに応じて、他のラベルを使用できます。例えば、
* An "invalid" label might be used for issues that were raised in error.
* 「無効な」ラベルが、エラーで発生した問題に使用される可能性があります。
* A "blocked" label might indicate an issue is awaiting resolution of an external process or related issue.
* 「ブロックされた」ラベルが、問題が外部プロセスまたは関連する問題の解決を待っていることを示している可能性があります。
* A "parked" label might be used to indicate issues that do not require immediate working group attention.
* 即時の作業グループの注意を必要としない問題を示すために「駐車中」ラベルを使用することができます。
During the development of a document, individual revisions of the document can be built and formally submitted as an Internet-Draft. This creates a stable snapshot and makes the content of the in-progress document available to a wider audience. Documents submitted as Internet-Drafts are not expected to address all open issues or merge outstanding pull requests.
文書の開発中に、文書の個々の修正を構築し、正式にインターネットドラフトとして提出することができます。これにより、安定したスナップショットが作成され、進行中の文書の内容がより幅広い視聴者に利用可能になります。インターネットドラフトとして提出された文書は、開いているすべての問題に対処することも、優れたプル要求をマージすることは期待されていません。
Section 7.1 of [RFC2418] recommends that editors create a new Internet-Draft submission two weeks prior to every session, which includes IETF meetings, other in-person meetings, and telephone or video conferences. Though discussion could use the current version of a document from version control, participants in a session cannot be expected to monitor changes to documents in real time; a published Internet-Draft ensures that there is a common, stable state that is known to all participants.
[RFC2418]のセクション7.1編集者は、IETF会議、他の人物内会議、電話またはビデオ会議を含む、すべてのセッションの2週間前に新しいインターネットドラフト送信を作成することをお勧めします。ディスカッションはバージョン管理から現在のバージョンの文書を使用することができますが、セッション内の参加者はリアルタイムで文書への変更を監視することが期待できません。公開されたインターネットドラフトは、すべての参加者に知られている一般的で安定した状態があることを保証します。
Internet-Drafts that use a GitHub repository SHOULD include a notice that includes a reference to the repository. This notice might also include information about where to discuss the draft.
GitHubリポジトリを使用するインターネットドラフトには、リポジトリへの参照を含む通知を含める必要があります。この通知には、ドラフトについて議論する場所に関する情報も含まれる場合があります。
Revisions used to generate documents that are submitted as Internet-Drafts SHOULD be tagged in repositories to provide a record of submissions.
インターネットドラフトとして提出された文書を生成するために使用されるリビジョンは、提出物の記録を提供するためにリポジトリにタグ付けされるべきです。
Working group chairs MAY request a revision of an Internet-Draft being managed on GitHub at any time, in consultation with document editors.
ワーキンググループチェアは、ドキュメントエディタと協議して、いつでもGitHubで管理されているインターネットドラフトのリビジョンを要求することができます。
The work that occurs on GitHub could be part of the consensus process, but the ultimate decision on consensus regarding a document is made by the chairs [RFC2026].
GitHubで発生する作業は、コンセンサスプロセスの一部になる可能性がありますが、文書に関する合意に関する最終的な決定は、チェア[RFC2026]によって行われます。
GitHub facilitates more involved interactions, which can result in a much higher level of activity than a typical working group mailing list. Participants who wish to limit their time commitment might follow GitHub activity selectively, either by following only specific issues or by occasionally reviewing the state of the document. Other participants might not use GitHub at all. Chairs are reminded that assessing consensus based on GitHub content alone cannot be assumed to reach all interested participants.
GitHubは、より多くの関与した対話を容易にします。これにより、一般的なワーキンググループのメーリングリストよりもはるかに高いレベルのアクティビティが発生する可能性があります。彼らの時間コミットメントを制限したい参加者は、特定の問題だけを以下に、または文書の状態を確認することによって、Githubの活動を選択的に追跡するかもしれません。他の参加者はまったくgithubを使用しないかもしれません。椅子は、GitHubコンテンツだけに基づくコンセンサスの評価をすべての関心のある参加者に到達すると想定することはできません。
As described in [RFC2418], chairs consider input from all discussion venues when assessing consensus. These include mailing lists, IETF meetings, and interim meetings in addition to discussion on GitHub. Each venue has different selection biases that might need to be considered.
[RFC2418]で説明されているように、椅子は合意を評価するときにすべてのディスカッション会場からの入力を検討します。これらには、メーリングリスト、IETF会議、およびGitHubに関する議論に加えて、暫定会議が含まれます。各会場には、考慮する必要があるかもしれない異なる選択バイアスがあります。
A working group chair MUST 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.
作業グループの議長は、潜在的に潜在的に潜在的な問題について作業グループのメーリングリストを参照する必要があります。GitHubを通して提供される入力に頼ることは、より狭い参加者のセットからの入力を得ることをもたらすかもしれません。これには、Working Group Last Callのような重要なマイルストーンが含まれます。
If permitted, GitHub will be used for technical discussion and decisions, especially during early stages of development of a document. Any decisions are confirmed through review within the working group and, ultimately, through Working Group Last Call; see Section 7.4 of [RFC2418].
許可されている場合、GitHubは、特に文書の開発の初期段階の間に技術的な議論と決定に使用されます。ワーキンググループ内のレビュー、最終的にはワーキンググループの最後の呼び出しを通じて、決断が確認されます。[RFC2418]のセクション7.4を参照してください。
The use of issues and labels has been effective in managing contentious issues. Explicitly labeling closed issues to identify those with formal consensus means that there is no confusion about the status of issues.
問題とラベルの使用は、議論のある問題を管理するのに効果的でした。正式なコンセンサスを識別するために閉じた問題を明示的にラベル付けすることは、問題の状況に関する混乱がないことを意味します。
Various third-party services offer the ability to run tests and other work when changes are made to a repository.
リポジトリに変更が加えられたときに、さまざまなサードパーティサービスがテストやその他の作業を実行する機能を提供します。
One common practice is to use these continuous integration services to build a text or HTML version of a document. This is then published to GitHub Pages, which allows users to view a version of the most recent revision of a document. Including a prominent link to this version of the document (such as in the README) makes it easier for new contributors to find a readable copy of the most recent version of a draft. In addition, including links to differences between this generated version and any published document helps contributors identify recent changes.
1つの一般的な方法は、これらの継続的な統合サービスを使用して文書のテキストまたはHTMLバージョンを構築することです。これはGitHubページに公開されているため、ユーザーはドキュメントの最新のリビジョンのバージョンを表示できます。このバージョンの文書への著名なリンク（ReadMeなど）を含めて、最新のドラフトの最新バージョンの読みやすいコピーを見つけることができなくなります。さらに、この生成されたバージョンと公開された文書の違いへのリンクを含めて、貢献者が最近の変更を識別するのに役立ちます。
Continuous integration can also validate pull requests and other changes for errors. The most basic check is whether the source file can be transformed successfully into a valid Internet-Draft. For example, this might include checking that the XML source is syntactically correct.
継続的な統合では、プル要求やエラーの変更を検証することもできます。最も基本的なチェックは、ソースファイルを有効なインターネットドラフトに正常に変換できるかどうかです。たとえば、XMLソースが構文的に正しいことを確認することが含まれます。
For a document that uses formal languages as part of the specification, such as schema or source code, a continuous integration system might also be used to validate any formal language that the document contains. Tests for any source code that the document contains might be run, or examples might be checked for correctness.
スキーマやソースコードなどの仕様の一部として正式な言語を使用する文書の場合、継続的な統合システムを使用して、文書に含まれる正式な言語を検証することもできます。ドキュメントが含まれている可能性があるソースコードをテストするか、または例を正確さについてチェックすることができます。
Document editors are primarily responsible for maintaining documents. Taking on a few additional tasks can greatly improve the process for the working group.
文書編集者は主に文書の維持を担当しています。いくつかの追加のタスクを取り上げると、ワーキンググループのプロセスが大幅に向上します。
Using GitHub means that it is more likely that a contribution is made by users who are not very familiar with the work. Pull requests from new contributors can contain errors or omissions. Duplicate issues are commonplace. Proposed changes might have grammatical errors or they might diverge from existing style. If a change is generally sound, rather than rejecting the pull request or requesting changes, editors could instead accept the change and then make any necessary corrections.
Githubを使用すると、その作品にはまったく精通していないユーザーが貢献が行われる可能性が高いことを意味します。新しい貢献者からのプルリクエストには、エラーまたは脱落が含まれています。重複する問題は一般的です。提案された変更は文法的な誤りを持つかもしれませんし、それらは既存のスタイルから分岐するかもしれません。プル要求を拒否するか変更を要求するのではなく、変更が一般的な場合、エディタは代わりに変更を受け入れてから必要な修正を行うことができます。
Editors SHOULD NOT close a pull request or issue without first understanding why the item was created. Editors and chairs SHOULD try to explain every action clearly and concisely. Even if a contributor seems rude, being courteous in response is always best.
編集者は、アイテムが作成された理由を最初に理解せずにプル要求または問題を閉じてはいけません。編集者と椅子は、すべての行動を明確かつ簡潔に説明しようとするべきです。たとえ寄稿者が失礼であっても、それに応えて丁寧であることは常に最善です。
If a contributor makes a comment that raises a new issue, editors can create an issue or, if there is an obvious solution, a pull request. It does not matter what venue the issue was raised in (e.g., email, issue discussion, a pull request review); capturing issues quickly ensures that problems become visible and can be tracked.
寄稿者が新しい問題を発生させるコメントを作成した場合、エディタは問題を作成できます。問題がどのような会場で提起されていません（例えば、電子メール、議論、議論、プル要求レビュー）。問題を取り込むと、問題が見えるようになり、追跡できるようになります。
This takes a little more effort, but these simple steps can help encourage contributions, which will ultimately improve the quality of documents.
これはもう少し努力しますが、これらの簡単なステップは貢献を促進するのに役立ちます。これは最終的に文書の品質を向上させます。
Continuity of operations is always a consideration when taking a dependency on an external service. If GitHub were to fail in some way, anyone relying upon its services would be seriously affected.
外部サービスに依存している場合、業務の継続性は常に考慮です。Githubが何らかの形で失敗した場合、そのサービスに頼る人は真剣に影響を受けるでしょう。
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.
GITの広範な使用は、一次リポジトリが複数の場所で複製されているため、システム障害への露出を減らします。これにはホストされているWebページが含まれます。Webページの内容は、メインリポジトリのブランチとして維持されています。
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.
ただし、GitHubで維持されている他の情報は損失に対して脆弱です。これには、これらの問題、ディスカッション、コミットおよびプルリクエスト、およびWikiでホストされているコンテンツに関する問題と議論が含まれます。バックアップのためにこの情報を抽出するためのツールが存在します。
As specified in [RFC8875], backup copies of repositories and other important data SHOULD be maintained.
[RFC8875]で指定されているように、リポジトリとその他の重要なデータのバックアップコピーを維持する必要があります。
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.
妥協された編集者、椅子、およびエリアディレクターによる悪意のある行動の可能性は、Githubホストが照会するコンテンツの完全性を維持するのに関連しています。バックアップにより、コンテンツの回復を可能にし、インターネットドラフトとしての定期的な提出物は、作業が完全に失われないことを確認します。
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.
GitHubの妥協点は、個々の資格情報とは別に、ほとんどのデータが公開されていると予想されるため、ワーキンググループの業務に大きな脅威をもたらさない。
A compromise of credentials could mean loss of control for repositories an organizations. All contributors, especially those with commit or admin privileges SHOULD use current best practices for protection of credentials, such as multi-factor authentication.
認証情報の妥協点は、組織をリポジトリの制御の喪失を意味する可能性があります。すべての貢献者、特にコミットまたは管理者特権を持つ人々は、マルチファクタ認証などの資格情報の保護のための現在のベストプラクティスを使用する必要があります。
This document has no IANA actions.
この文書にはIANAの行動がありません。
[RFC2026] Bradner, S., "The Internet Standards Process -- Revision 3", BCP 9, RFC 2026, DOI 10.17487/RFC2026, October 1996, <https://www.rfc-editor.org/info/rfc2026>.
[RFC2026] Bradner、S。、「インターネット標準プロセス - リビジョン3」、BCP 9、RFC 2026、DOI 10.17487 / RFC2026、1996年10月、<https：//www.rfc-editor.org/info/rfc2026>。
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/info/rfc2119>.
[RFC2119] BRADNER、S、「RFCSで使用するためのキーワード」、BCP 14、RFC 2119、DOI 10.17487 / RFC2119、1997年3月、<https：//www.rfc-editor.org/info/RFC2119>。
[RFC2418] Bradner, S., "IETF Working Group Guidelines and Procedures", BCP 25, RFC 2418, DOI 10.17487/RFC2418, September 1998, <https://www.rfc-editor.org/info/rfc2418>.
[RFC2418] BRADNER、S、「IETFワーキンググループガイドラインと手順」、BCP 25、RFC 2418、DOI 10.17487 / RFC2418、1998年9月、<https://www.rfc-editor.org/info/rfc2418>。
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8174] Leiba、B、「RFC 2119キーワードの大文字の曖昧さ」、BCP 14、RFC 8174、DOI 10.17487 / RFC8174、2017年5月、<https：//www.rfc-editor.org/info/RFC8174>。
[GLOSSARY] GitHub, "GitHub glossary", March 2020, <https://help.github.com/en/github/getting-started-with-github/github-glossary>.
[用語集] Github、「Github Glossary」、2020年3月、<https：//help.github.com/en/github/getting-started-with-github/github-lossary>。
[RFC7991] Hoffman, P., "The "xml2rfc" Version 3 Vocabulary", RFC 7991, DOI 10.17487/RFC7991, December 2016, <https://www.rfc-editor.org/info/rfc7991>.
[RFC7991] HOFFMAN、P.、「XML2RFC「バージョン3語彙」、RFC 7991、DOI 10.17487 / RFC7991、2016年12月、<https://www.rfc-editor.org/info/rfc7991>。
[RFC8875] Cooper, A. and P. Hoffman, "Working Group GitHub Administration", RFC 8875, DOI 10.17487/RFC8875, August 2020, <https://www.rfc-editor.org/info/rfc8875>.
[RFC8875] Cooper、A.およびP. Hoffman、「ワーキンググループGitHub政権」、RFC 8875、DOI 10.17487 / RFC8875、2020年8月、<https://www.rfc-editor.org/info/rfc8875>。
Acknowledgments
謝辞
This work would not have been possible without the hard work of those people who have trialed the use of GitHub at the IETF. Alia Atlas contributed significant text to an earlier draft version of this document. Tommy Pauly, Rich Salz, and Christopher Wood all provided significant input.
この作品は、IETFでのGitHUBの使用を試行した人々の努力なしには不可能だったでしょう。Alia Atlasは、この文書の以前のドラフト版に重要なテキストを貢献しました。Tommy Pouly、Rich Salz、そしてChristopher Woodはすべて重要な入力を提供しました。
Authors' Addresses
著者の住所
Martin Thomson Mozilla
Martin Thomson Mozilla.
Email: mt@lowentropy.net
Barbara Stark AT&T
Barbara Stark At＆T.
Email: barbara.stark@att.com