Сортировка билетов ¶
Django использует Trac для управления работой над кодовой базой. Trac - это сад сообщества ошибок, которые люди нашли, и функций, которые люди хотели бы видеть добавленными. Как и в любом саду, иногда нужно вырывать сорняки, а иногда есть цветы и овощи, которые нужно собирать. Нам нужна ваша помощь, чтобы отделить одно от другого, и, в конце концов, мы все выиграем вместе.
Как и все сады, мы можем стремиться к совершенству, но на самом деле такого нет. Даже в самом чистом саду все еще есть улитки и насекомые. В общественном саду также есть полезные люди, которые из самых лучших побуждений удобряют сорняки и травят розы. Задача сообщества в целом - управлять собой, сводить проблемы к минимуму и обучать тех, кто приходит в сообщество, чтобы они могли стать ценными участниками.
Точно так же, хотя мы стремимся к тому, чтобы Trac был идеальным представителем состояния прогресса Django, мы признаем, что этого не произойдет. Распределяя нагрузку по обслуживанию Trac на сообщество, мы признаем, что будут ошибки. Trac «в основном точен», и мы даем скидку на то, что иногда он будет ошибаться. Это нормально. Мы перфекционисты с дедлайнами.
Мы рассчитываем на то, что сообщество будет продолжать участвовать, сохранять тикеты как можно более точными и поднимать вопросы для обсуждения в наших списках рассылки при возникновении путаницы или разногласий.
Django - это проект сообщества, и каждый вклад помогает. Без тебя мы не справимся !
Рабочий процесс сортировки ¶
К сожалению, не все отчеты об ошибках и запросы функций в системе отслеживания заявок содержат все необходимые сведения . Некоторые билеты содержат исправления, но эти исправления не соответствуют всем требованиям, предъявляемым к хорошему исправлению .
Один из способов помочь - отсортировать заявки , созданные другими пользователями.
Большая часть рабочего процесса основана на концепции этапов сортировки заявки . Каждый этап описывает, где в любой момент времени находится данный билет. Наряду с горсткой флагов, этот атрибут легко сообщает нам, что и кого ждет каждый билет.
Поскольку картинка стоит тысячи слов, начнем с нее:
На этой диаграмме у нас две роли:
- Коммиттеры: люди с доступом к коммитам, которые несут ответственность за принятие окончательного решения о слиянии патча.
- Сортировщики билетов: любой член сообщества Django, решивший участвовать в процессе разработки Django. Наша инсталляция Trac намеренно оставлена открытой для публики, и любой может отсортировать билеты. Django - это проект сообщества, и мы поощряем его сортировку .
В качестве примера мы видим жизненный цикл среднего билета:
- Алиса создает билет и отправляет неполный пул-реквест (без тестов, некорректная реализация).
- Боб просматривает запрос на вытягивание, помечает билет как «Принято», «требует тестирования» и «исправление требует улучшения» и оставляет комментарий, рассказывающий Алисе, как можно улучшить исправление.
- Алиса обновляет пул-реквест, добавляя тесты (но не изменяя реализацию). Она убирает два флажка.
- Чарли просматривает запрос на вытягивание и сбрасывает флаг «исправление требует улучшения» с другим комментарием об улучшении реализации.
- Алиса обновляет пулреквест, исправляя реализацию. Она убирает флаг «патч требует улучшения».
- Дейзи просматривает пул-реквест и помечает билет как «Готовый к регистрации».
- Джейкоб, коммиттер, просматривает пулреквест и объединяет его.
Некоторые билеты требуют гораздо меньше обратной связи, чем эта, но, опять же, некоторые билеты требуют гораздо большего.
Этапы сортировки ¶
Ниже мы более подробно описываем различные этапы, которые может пройти билет в течение его срока службы.
Непроверенные ¶
Билет не был рассмотрен кем-либо, кто считал, что имеет право выносить суждение о том, содержит ли билет действительную проблему, жизнеспособную функцию или его следует закрыть по любой из различных причин.
Принято ¶
Большая серая зона! Абсолютное значение слова «принято» заключается в том, что проблема, описанная в билете, действительна и находится на некоторой стадии работы. Помимо этого, есть несколько соображений:
Принято + без флагов
Билет действителен, но патч для него еще никто не прислал. Часто это означает, что вы можете спокойно начать писать патч для него. Как правило, это более верно в случае принятых ошибок, чем в случае принятых функций. Заявка на ошибку, которая была принята, означает, что проблема была подтверждена, по крайней мере, одним средством проверки как допустимая ошибка - и, вероятно, ее следует исправить, если это возможно. Принятая новая функция может означать только то, что один из проверяющих считает, что эта функция будет полезна, но это само по себе не представляет собой единого мнения и не подразумевает с какой-либо уверенностью, что исправление будет принято для этой функции. Если вы сомневаетесь, узнайте больше отзывов, прежде чем писать обширный патч.
Принято + имеет исправление
Билет ждет, когда люди ознакомятся с поставленным патчем. Это означает загрузку патча и его опробование, проверку наличия тестов и документов, запуск набора тестов с включенным патчем и оставление отзыва о заявке.
Принято + есть исправление + Требуется…
Это означает, что заявка проверена и требует доработки. «Необходимые тесты» и «Необходимая документация» не требуют пояснений. «Патч требует улучшения», как правило, сопровождается комментарием к заявке, объясняющим, что необходимо для улучшения кода.
Готов к заселению ¶
Билет был рассмотрен любым членом сообщества, кроме человека, который предоставил патч, и обнаружил, что он отвечает всем требованиям для патча, готового к фиксации. Коммиттеру теперь необходимо провести окончательную проверку патча перед его фиксацией. См. FAQ для новых участников: «Моя заявка была в RFC навсегда! Что я должен делать?"
Когда-нибудь / Может быть ¶
Этот этап на схеме не показан. Его редко используют для отслеживания идей высокого уровня или долгосрочных запросов функций.
Эти тикеты необычны и в целом менее полезны, поскольку не описывают конкретных проблем, которые можно предпринять. Это запросы на усовершенствования, которые мы могли бы когда-нибудь добавить к фреймворку, если будет представлен отличный патч. Они не являются приоритетными.
Другие атрибуты сортировки ¶
На тикете можно установить ряд флажков, которые отображаются в виде флажков в Trac:
Есть патч ¶
Это означает, что с билетом связан патч . Они будут проверены, чтобы убедиться, что исправление «хорошее».
Следующие три поля (Требуется документация, Требуются тесты, Патч требует улучшения) применяются только в том случае, если патч был поставлен.
Требуется документация ¶
Этот флаг используется для заявок с исправлениями, требующими соответствующей документации. Полная документация по функциям является предварительным условием, прежде чем мы сможем проверить их в кодовой базе.
Требуются тесты ¶
Это помечает патч как требующий связанных модульных тестов. Опять же, это обязательная часть действующего патча.
Патч требует доработки ¶
Этот флаг означает, что хотя в билете есть патч, он еще не совсем готов для регистрации. Это может означать, что исправление больше не применяется чисто, есть ошибка в реализации или что код не соответствует нашим стандартам.
Легкие сборы ¶
Билеты, которые потребуют небольших, простых заплат.
Тип ¶
Билеты следует классифицировать по типу :
- Новая функция
- Для добавления чего-то нового.
- ошибка
- Когда существующая вещь сломана или ведет себя не так, как ожидалось.
- Очистка / оптимизация
- Ведь когда ничего не сломано, но что-то можно сделать чище, лучше, быстрее, сильнее.
Компонент ¶
Билеты следует классифицировать по компонентам, указывая, к какой области кодовой базы Django они принадлежат. Это упрощает организацию билетов и упрощает поиск.
Серьезность ¶
Тяжесть атрибут используется для идентификации блокаторов, то есть вопросы , которые должны получить фиксированные перед выпуском следующей версии Django. Как правило, это ошибки, вызывающие регресс по сравнению с более ранними версиями или потенциально вызывающие серьезные потери данных. Этот атрибут используется довольно редко, и подавляющее большинство заявок имеют уровень серьезности «Нормальный».
Версия ¶
Можно использовать атрибут версии, чтобы указать, в какой версии была обнаружена обнаруженная ошибка.
UI / UX ¶
Этот флаг используется для заявок, связанных с вопросами пользовательского интерфейса и пользовательского опыта. Например, этот флаг подходит для пользовательских функций в формах или в интерфейсе администратора.
Cc ¶
Вы можете добавить свое имя пользователя или адрес электронной почты в это поле, чтобы получать уведомления о новых вкладах в заявку.
Ключевые слова ¶
В этом поле вы можете пометить билет несколькими ключевыми словами. Это может быть полезно, например, для группировки нескольких заявок на одну тему. Ключевые слова могут быть разделены запятыми или пробелами. Поиск по ключевым словам находит строку ключевого слова в любом месте ключевого слова. Например, щелчок по заявке с ключевым словом «форма» приведет к появлению аналогичных заявок, помеченных ключевыми словами, содержащими такие строки, как «набор форм», «набор моделей» и «Менеджмент форма».
Закрытие билетов ¶
Когда заявка завершает свой полезный жизненный цикл, ее пора закрывать. Однако закрыть заявку - это большая ответственность. Вы должны быть уверены, что проблема действительно решена, и вы должны иметь в виду, что составитель заявки может быть недоволен закрытием заявки (если она не исправлена!). Если вы не уверены, что закрываете заявку, оставьте комментарий со своими мыслями.
Если вы закрываете заявку, вы всегда должны убедиться в следующем:
- Убедитесь, что проблема решена.
- Оставьте комментарий с объяснением решения о закрытии заявки.
- Если есть способ улучшить билет, чтобы повторно открыть его, сообщите им.
- Если билет является дубликатом, укажите исходный билет. Также сделайте перекрестную ссылку на закрытый тикет, оставив комментарий в исходном - это позволяет получить доступ к дополнительной информации о сообщенной ошибке или запрошенной функции.
- Будьте вежливы. Никто не любит, когда их билеты закрыты. Это может расстраивать или даже обескураживать. Лучший способ не отвлекать людей от участия в Django - это быть вежливыми и дружелюбными и предлагать предложения о том, как они могут улучшить этот билет и другие билеты в будущем.
Тикет может быть разрешен несколькими способами:
- фиксированный
- Используется после того, как патч был добавлен в Django и проблема устранена.
- недействительным
- Используется, если билет оказывается неверным. Это означает, что проблема в билете на самом деле является результатом ошибки пользователя или описывает проблему с чем-то другим, кроме Django, или вообще не является отчетом об ошибке или запросом функции (например, некоторые новые пользователи отправляют запросы в службу поддержки как Билеты).
- wontfix
- Используется, когда кто-то решает, что запрос не подходит для рассмотрения в Django. Иногда заявка закрывается как «wontfix» с просьбой к репортеру начать обсуждение в списке рассылки django-developers, если он считает иначе, чем объяснение, предоставленное человеком, который закрыл заявку. В других случаях обсуждение в списке рассылки предшествует решению закрыть заявку. Всегда используйте список рассылки для достижения консенсуса перед повторным открытием билетов, закрытых как «wontfix».
- дубликат
- Используется, когда другой билет касается той же проблемы. Закрывая дублирующиеся заявки, мы сохраняем все обсуждения в одном месте, что помогает всем.
- работает для меня
- Используется, когда тикет не содержит достаточно деталей, чтобы воспроизвести исходную ошибку.
- needsinfo
- Используется, когда билет не содержит достаточно информации для репликации обнаруженной проблемы, но потенциально все еще действителен. Билет следует повторно открыть, когда будет предоставлена дополнительная информация.
Если вы считаете, что билет был закрыт по ошибке - из-за того, что проблема все еще возникла, или она появилась где-то еще, или сортировщики допустили ошибку - пожалуйста, откройте заявку и предоставьте дополнительную информацию. Опять же, пожалуйста, не открывайте повторно заявки, помеченные как «wontfix», и вместо этого сообщайте о проблеме разработчикам django .
Как я могу помочь с сортировкой? ¶
Процесс сортировки в первую очередь осуществляется членами сообщества. Действительно, ЛЮБОЙ может помочь.
Чтобы принять участие, начните с создания учетной записи на Trac . Если у вас есть учетная запись, но вы забыли пароль, вы можете сбросить ее на странице сброса пароля .
Тогда вы можете помочь:
- Закрытие «непроверенных» билетов как «недействительных», «рабочих форм», «дубликатов» или «без исправлений».
- Закрытие «непроверенных» заявок как «needsinfo», когда описание слишком скудно, чтобы его можно было применить, или когда это запросы функций, требующие обсуждения на django-developers .
- Исправление флажков «Требуются тесты», «Требуется документация» или «Имеет исправление» для заявок, для которых они установлены неправильно.
- Установка флажка « Легкий сбор » для небольших и относительно простых билетов.
- Установите тип билетов, которые еще не попали в категорию.
- Проверка того, что старые билеты еще действительны. Если заявка не проявляла активности в течение длительного времени, возможно, проблема была устранена, но заявка еще не закрыта.
- Выявление тенденций и тем в билетах. Если есть много сообщений об ошибках в определенной части Django, это может указывать на то, что нам следует рассмотреть возможность рефакторинга этой части кода. Если тенденция намечается, вы должны поднять ее для обсуждения (ссылки на соответствующие тикеты) на django-developers .
- Убедитесь, что исправления, отправленные другими пользователями, верны. Если они верны и также содержат соответствующую документацию и тесты, переместите их на этап «Готовы к проверке». Если они неверны, оставьте комментарий, чтобы объяснить, почему, и установите соответствующие флажки («Патч требует улучшения», «Требуются тесты» и т. Д.).
Заметка
Страница отчетов содержит ссылки на множество полезных запросов Trac, в том числе несколько полезных для сортировки заявок и просмотра исправлений, как предложено выше.
Вы также можете найти больше советов для новых участников .
Однако мы просим всех членов сообщества, работающих с базой данных заявок, сделать следующее:
- Пожалуйста , не рекламируйте свои билеты в «Готово к заселению». Вы можете пометить чужие билеты, которые вы просмотрели, как «Готовые к проверке», но вы должны попросить как минимум одного другого члена сообщества просмотреть патч, который вы отправляете.
- Пожалуйста , не отменяйте решение, не отправив сообщение разработчикам django для достижения консенсуса.
- Если вы не уверены, следует ли вам вносить изменения, не вносите изменения, а вместо этого оставьте комментарий со своими проблемами в заявке или отправьте сообщение разработчикам django . Неуверенность - это нормально, но ваш вклад по-прежнему ценится.
Деление регрессии пополам ¶
Регрессия - это ошибка, которая присутствует в некоторых более новых версиях Django, но отсутствует в более старых. Чрезвычайно полезная информация - это коммит, который привел к регрессии. Знание фиксации, вызвавшей изменение поведения, помогает определить, было ли изменение преднамеренным или это был непреднамеренный побочный эффект. Вот как это можно определить.
Начните с написания регрессионного теста для набора тестов Django для решения этой проблемы. Например, мы сделаем вид, что отлаживаем регресс в миграциях. После того, как вы написали тест и подтвердили, что он не работает на последнем мастере, поместите его в отдельный файл, который можно запустить автономно. В нашем примере мы представим, что создали tests/migrations/test_regression.py , что можно запустить с помощью:
$ ./runtests.py migrations.test_regression
Затем мы отмечаем текущую точку в истории как «плохую», поскольку тест не проходит:
$ git bisect bad
You need to start by "git bisect start"
Do you want me to do it for you [Y/n]? y
Теперь нам нужно найти точку в истории git до того, как была введена регрессия (то есть точка, где проходит тест). Используйте что-то вроде
проверки более ранней ревизии (в данном случае 100 коммитов раньше). Проверьте, не прошел ли тест. Если да, отметьте эту точку как «плохую» ( ), затем проверьте более раннюю версию и повторите проверку. Как только вы найдете ревизию, в которой ваш тест пройден, отметьте ее как «хорошую»:git checkout HEAD~100 git bisect bad
$ git bisect good
Bisecting: X revisions left to test after this (roughly Y steps)
...
Теперь мы готовы к самой интересной части: использование для автоматизации остальной части процесса:git bisect run
$ git bisect run tests/runtests.py migrations.test_regression
Вы должны увидеть использование двоичного поиска для автоматической проверки изменений между хорошими и плохими фиксациями, пока не будет обнаружена первая «плохая» фиксация, в которой тест не прошел.git bisect
Теперь опубликуйте свои результаты в запросе Trac и включите регрессионный тест в качестве приложения. Когда кто-то пишет исправление для ошибки, ваш тест уже будет для них отправной точкой.