Политика публичных Issue
GitHub Issues — это отобранный публичный backlog ThreadCells, а не расшифровка предупреждений, аудитов или отладки релиза.
Приемлемость
Публичный Issue обычно должен удовлетворять всем этим условиям:
- проблема или возможность остаётся нерешённой;
- её можно воспроизвести или она подтверждена устойчивыми свидетельствами;
- она имеет значимое влияние на пользователя, проект, надёжность, документацию или сопровождаемость;
- публичное отслеживание полезно и применимо для проекта или сообщества;
- публичное раскрытие безопасно;
- ожидаемое поведение или результат ясны; и
- можно сформулировать конкретные критерии приемки.
Устойчивые технические свидетельства могут заменять шаги воспроизведения, когда детерминированное воспроизведение непрактично.
Вопросы, устранение неполадок и открытое обсуждение относятся в Discussions Q&A. Изучайте ранние предложения, начинающиеся с проблемы или сценария использования, в Discussions Ideas. Переносите находку или предложение в Issues только после того, как оно стало подтверждённым, конкретным, безопасным для публикации и применимым в рамках этой политики.
Что не относится к публичным Issues
Не создавайте публичный Issue лишь для:
- администрирования, доступного только owner репозитория или учётной записи;
- администрирования учётных данных или работы с закрытой инфраструктурой;
- учётных данных, секретов или деталей безопасности, небезопасных для раскрытия;
- временного шума CI, окружения, сети или runner;
- уже разрешённых находок;
- изолированных runtime-идентификаторов без воспроизводимого класса основной проблемы;
- предупреждений, которые работают безопасно без продемонстрированного дефекта;
- спекулятивной полировки без определённой проблемы и результата;
- временных наблюдений о релизе или отладке; или
- неклассифицированных заметок из аудита или просмотра остаточного долга.
Действия, доступные только owner, относятся в операционный канал owner репозитория, а не в backlog участников. Находка становится публичным Issue, только пройдя порог приемлемости.
Содержание отчёта
Используйте соответствующую форму Issue и укажите полезные части этой структуры:
- Проблема / контекст
- Влияние
- Текущее поведение
- Ожидаемое поведение
- Воспроизведение или свидетельства
- Критерии приемки
- Не-цели, когда это полезно
Включайте сведения об окружении или версии, только когда они влияют на отчёт. Редактируйте журналы и снимки экрана. Никогда не включайте секреты, учётные данные, персональные данные, личные сообщения, ненужные закрытые пути, базы данных состояния или расшифровки терминала.
Уязвимости и находки, чувствительные к безопасности, должны использовать закрытый канал из SECURITY.md, а не публичный Issue.
Триаж и дубликаты
Перед созданием отчёта найдите открытые и закрытые Issues. Сопровождающие связывают дубликаты с каноническим Issue и закрывают их как дубликаты, а не разделяют обсуждение и свидетельства.
Используйте наименьший полезный набор меток. bug, enhancement, documentation, accessibility и technical-debt описывают работу; duplicate описывает триаж. Сопровождающие могут запросить недостающие свидетельства до решения о том, соответствует ли отчёт требованиям.
Закрывайте Issue, когда выполнены критерии приемки, когда он дублирует канонический Issue или как not planned с краткой причиной, если он вне области работ, не может стать применимым или больше не оправдывает отслеживание проектом. Уже разрешённые отчёты должны указывать на подтверждающие свидетельства.
Метки для участников
Используйте good first issue только для безопасной, ограниченной, однозначной работы с достаточными контекстом и критериями приемки для нового участника. Используйте help wanted только когда внешний вклад действительно приветствуется и задача достаточно определена.
Критические границы безопасности или аутентификации, поведение жизненного цикла и exactly-once, разрушительная безопасность, полномочия на релиз, границы доверия провайдера или удалённого выполнения кода, миграции и целостность данных никогда автоматически не являются работой для новичков.