RFC 8875 Working Group GitHub Administration

Опубликовано 28.08.2020 автором Nikolai Malykh 
Internet Engineering Task Force (IETF)                         A. Cooper
Request for Comments: 8875                                         Cisco
Category: Informational                                       P. Hoffman
ISSN: 2070-1721                                                    ICANN
                                                             August 2020

Working Group GitHub Administration

Администрирование рабочих групп GitHub

PDF

Аннотация

Использование GitHub в рабочих группах (WG) IETF возрастает. Этот документ описывает использование и соглашения для рабочих групп, начинающих пользоваться GitHub. Документ не задает обязательных процессов и не требует изменения работы существующих и будущих групп, которые не пользуются GitHub.

Статус документа

Документ не содержит какой-либо спецификации (Internet Standards Track) и публикуется с информационными целями.

Документ является результатом работы IETF1 и представляет согласованный взгляд сообщества IETF. Документ прошел открытое обсуждение и был одобрен для публикации IESG2. Дополнительную информацию о стандартах Internet можно найти в разделе 2 в RFC 7841.

Информация о текущем статусе документа, найденных ошибках и способах обратной связи доступна по ссылке https://www.rfc-editor.org/info/rfc8875.

Авторские права

Copyright (c) 2020. Авторские права принадлежат IETF Trust и лицам, указанным в качестве авторов документа. Все права защищены.

К этому документу применимы права и ограничения, перечисленные в BCP 78 и IETF Trust Legal Provisions и относящиеся к документам IETF (http://trustee.ietf.org/license-info), на момент публикации данного документа. Прочтите упомянутые документы внимательно. Фрагменты программного кода, включённые в этот документ, распространяются в соответствии с упрощённой лицензией BSD, как указано в параграфе 4.e документа IETF Trust Legal Provisions, без каких-либо гарантий (как указано в Simplified BSD License).

1. Введение

Многие рабочие группы и участники процессов IETF используют GitHub разными способами в своей работе над документами IETF. Некоторые люди заинтересованы в использовании GitHub их рабочими группами, но не знают, с чего начать или каким соглашениям следовать. Некоторые рабочие группы используют или планируют применять другие репозитории кода, такие как GitLab и Bitbucket, свойства которых отличаются от GitHub.

В этом документе задан набор административных процессов и соглашений для рабочих групп IETF, которые следует применять при выборе GitHub для упрощения своей работы. Эти спецификации не предназначены для рабочих групп и отдельных лиц, которые уже применяют GitHub для работы IETF. Практика таких групп различается и некоторые из них не соответствуют предлагаемым здесь соглашениям (это нормально). Цель спецификации не состоит в формировании единообразной практики и основной задачей является помощь рабочим группам, начинающим использовать GitHub, описав проверенные подходы способы, которые можно перенять при желании.

2. Административный процесс и соглашения

В этом разделе описан административный процесс и соглашения для поддержки создания и управления организацией в GitHub для рабочих групп и хранилищ отдельных документов единообразным способом. Эти действия можно выполнить вручную через секретариат IETF или автоматизированным путем. Примеры автоматизированных решений доступны по ссылкам https://github.com/richsalz/ietf-gh-scripts и https://github.com/martinthomson/i-d-template.

В этом документе вопрос выбора ручного или автоматизированного процесса намеренно не рассматривается, поскольку эти детали будут рассмотрены в IETF Secretariat и Tools Team.

Большинство приведенных ниже соглашений взяты из [RFC8874].

2.1. Создание организации в GitHub

Этот документ указывает, что интерфейс IETF Datatracker позволяет руководителям направлений (area director – AD) или рабочих групп запрашивать создание в GitHub организации для конкретной рабочей группы. В идеале эта возможность должна присутствовать как часть пользовательского интерфейса (UI) создания рабочей группы и ее страницы.

При запросе руководителем направления или рабочей группы создания организации в GitHub инициируется описанный ниже процесс.

  1. Для рабочей группы создается организация GitHub.

  2. Имя организации имеет формат ietf-wg-<wgname>…

  3. Организация инициализируется путем указания IETF Secretariat и руководителей направления в качестве владельцев области данной группы. Если ответственный AD для рабочей группы работает в другом направлении (area), этот AD также будет владельцем.

  4. Организация инициализируется с указанием администраторов, в число которых входят руководитель и секретарь рабочей группы, если они есть.

После создания организации ее URL добавляется на страницу рабочей группы в Datatracker.

Этапы 3 и 4 подразумевают, что идентификаторы владельцев и администраторов известны GitHub. Запись идентификаторов GitHub в Datatracker (см. https://trac.tools.ietf.org/tools/ietfdb/ticket/2548) будет облегчать это. Лицо, запрашивающее создание организации о недоступности идентификаторов GitHub для любого из указанных в качестве владельцев и администраторов.

2.2. Перенос существующих организаций

Если рабочая группа уже имеет организацию, для нее будет полезно указание такого же персонала управления, как описано в параграфе 2.1. Т. е. будет полезно иметь возможность выполнить этапы 3 и 4 из параграфа 2.1, чтобы описанные ниже действия, такие как смена персонала, выполнялись так же, как для созданной заново организации.

2.3. Изменение персонала

При смене персонала для направления или рабочей группы эти изменения будут отражаться в организации GitHub. В Datatracker следует обеспечить возможность отслеживания смены персонала.

2.4. Закрытие рабочей группы

При закрытии рабочей группы команда с административным доступом удаляется, а список владельцев возвращается в секретариат и текущим AD (на момент закрытия). Сводные данные об организации и репозитории внутри организации обновляются для указания того, что работа завершена. Позже список владельцев может быть ограничен секретариатом или включать других лиц по выбору секретариата или IESG.

2.5. Создание репозитория документов

Имеется много вариантов и конфигураций, в которых может быть полезно использование автоматизации или административных соглашения для репозиториев в рамках организации WG:

  • создание нового репозитория для отдельного чернового документа (по решению руководителя WG);

  • создание нового репозитория для уже принятого рабочей группой проекта (draft);

  • перенос имеющегося репозиория документов в организацию WG;

  • создание нового репозитория с множеством черновых документов.

В качестве этапа процесса этот документ указывает наличие в интерфейсе Datatracker инструмента, позволяющего администратору организации ietf-wg-<wgname> запросить создание нового репозитория для одного документа внутри этой организации. Авторы этого документа будут указаны как участники работы, а репозиторий получит имя чернового документа. В идеале репозиторий должен быть настроен с шаблоном чернового документа, файлами CONTRIBUTING, LICENSE и README, а также с поддержкой непрерывной интеграции в стиле https://github.com/martinthomson/i-d-template. Выполнение этого этапа будет автоматически информировать IETF Secretariat о необходимости создать резерную копию репозитория в соответствии с параграфом 3.2.

2.6. Список связанных репозиториев

В IETF Datatracker следует позволять пользователя добавлять ссылки на репозитории (GitHub и др.) для рабочих групп, документов и страниц пользователей. В данный момент эта функция находится стадии разработки.

3. Рабочий процесс

В [RFC8874] рассмотрены разные варианты использования GitHub рабочими группами и множество решений для реализации этого. В этом разделе указаны базовые административные правила для рабочих групп и описана административная поддержка этих правил.

3.1. Участники работы

Каждый репозиторий, созданный в организации WG, должен как минимум включать в свой файл CONTRIBUTING шаблонный текст https://trustee.ietf.org/license-for-open-source-repositories.html из файла лицензии IETF для репозиториев с открытым кодом. Этот файл может включать и другую информацию (см., например, https://github.com/ietf/repo-files/tree/master/contributing-samples).

Будет полезно указывать в пользовательских данных Datatracker как минимум список учетные данные пользователей GitHub, чтобы упростить отслеживание их вклада в работу.

Некоторые рабочие группы предпочитают иметь в репозитории несколько черновых вариантов, особенно для документов, связанных перекрестными ссылками. В таких случаях в файле README этого репозитория следует четко указывать это, чтобы читатель знал о возможности одновременного изменения нескольких черновых документов.

3.2. Резервные копии и архивы содержимого GitHub

Списки рассылок рабочих групп IETF автоматически копируются секретариатом IETF и архивы доступны для всех. Все официальные взаимодействия в WG должны архивироваться.

Информация рабочей группы в GitHub также должна архивироваться с обеспечением публичного доступа к архивам. Этот документ задает использование для решения этих задач протокола Git [git-protocol].

Репозиторий каждой рабочей группы IETF в GitHub будет иметь одноименный репозиторий (зеркало) на сервере, поддерживаемом секретариатом IETF. Каждый час служба будет использовать команду git fetch для всех отслеживаемых репозиториев GitHub. Зеркало репозитория будет обеспечивать доступ для всех.

Отметим, что эта система не делает резервных копий и запросов на вытягивание (pull). Резервные копии следует делать и GitHub API позволяет это. Секретариату IETF следует делать резервные копии зеркала одновременно с созданием резерных копий репозиториев GitHub.

Шаги, описанные в параграфе 2.5, информируют IETF Secretariat о репозиториях, для которых следует создать резервные копии. Руководителям рабочих групп и направлений следует также иметь возможность запрашивать у секретариата IETF резервное копирование других репозиториев и связанных рабочих IETF.

4. Вопросы безопасности

Злоумышленник может изменить содержимое Internet-Drafts, особенно на финальных этапах работы и внести незаметные изменения в протоколы, которые могут быть в конечном итоге приняты.

Существует риск потери данных из-за их размещения в одном сервисе. Это учитывается и может быть смягчено мерами, описанными в параграфе 3.2.

5. Взаимодействие с IANA

Этот документ не требует действий IANA.

6. Литература

[git-protocol] Chacon, S. and B. Straub, “Git on the Server – The Protocols”, in Pro Git, 2014, <https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols#The-Git-Protocol>.

[RFC8874] Thomson, M. and B. Stark, “Working Group GitHub Usage Guidance”, RFC 8874, DOI 10.17487/RFC8874, August 2020, <https://www.rfc-editor.org/info/rfc8874>.

Адреса авторов

Alissa Cooper

Cisco

Email: alcoop@cisco.com

Paul Hoffman

ICANN

Email: paul.hoffman@icann.org

Перевод на русский язык

Николай Малых

nmalykh@protokols.ru

1Internet Engineering Task Force.

2Internet Engineering Steering Group.

Запись опубликована в рубрике RFC. Добавьте в закладки постоянную ссылку.