Учет билетов

Django использует Trac для управления работой над кодовой базой. Trac - это ухоженный сообществом сад ошибок, которые люди нашли, и функций, которые люди хотели бы видеть добавленными. Как и в любом саду, иногда там есть сорняки, которые нужно выдергивать, а иногда есть цветы и овощи, которые нужно собирать. Нам нужна ваша помощь, чтобы отделить одно от другого, и в конечном итоге мы все вместе выиграем.

Как и все сады, мы можем стремиться к совершенству, но в реальности такого не бывает. Даже в самом нетронутом саду все равно есть улитки и насекомые. В общественном саду также есть полезные люди, которые - из лучших побуждений - удобряют сорняки и отравляют розы. Работа всего сообщества заключается в самоуправлении, сведении проблем к минимуму и обучении тех, кто приходит в сообщество, чтобы они могли стать ценными членами.

Аналогично, хотя мы стремимся к тому, чтобы Trac был идеальным отображением состояния прогресса Django, мы признаем, что этого не произойдет. Распределяя нагрузку по обслуживанию Trac на сообщество, мы признаем, что будут ошибки. Trac «в основном точен», и мы допускаем, что иногда он будет ошибаться. Это нормально. Мы перфекционисты со сроками.

Мы рассчитываем на то, что сообщество будет продолжать участвовать, поддерживать билеты как можно точнее и поднимать вопросы для обсуждения в наших списках рассылки, когда возникает путаница или разногласия.

Django - это проект сообщества, и каждый вклад помогает. Мы не сможем сделать это без вас!

Рабочий процесс транспортировки

К сожалению, не все сообщения об ошибках и запросы функций в тикет-трекере обеспечивают все required details. В ряде тикетов есть исправления, но эти исправления не отвечают всем требованиям good patch.

Один из способов помочь - это разбирать билеты, созданные другими пользователями.

Большая часть рабочего процесса основана на концепции triage stages билета. Каждый этап описывает, на каком этапе своего жизненного цикла находится данный билет в любой момент времени. Вместе с несколькими флагами этот атрибут легко сообщает нам, чего и кого ожидает каждый билет.

Поскольку фотография стоит тысячи слов, давайте начнем с этого:

Django's ticket triage workflow

На этой диаграмме у нас две роли:

  • Коммиттеры: люди с доступом к коммитам, которые отвечают за принятие окончательного решения о слиянии патча.
  • Триггеры тикетов: все члены сообщества Django, которые хотят участвовать в процессе разработки Django. Наша установка Trac намеренно оставлена открытой для публики, и любой может заниматься сортировкой тикетов. Django - это проект сообщества, и мы поощряем triage by the community.

В качестве примера, здесь мы видим жизненный цикл среднего билета:

  • Алиса создает тикет и отправляет неполный запрос (нет тестов, неправильная реализация).
  • Боб просматривает запрос на притяжение, отмечает билет как «принят», «нужны тесты» и «патч нуждается в улучшении», а также оставляет комментарий, в котором сообщает Алисе, как можно улучшить патч.
  • Алиса обновляет запрос на притяжение, добавляя тесты (но не меняя реализацию). Она удаляет два флага.
  • Чарли просматривает заявку на исправление и сбрасывает флаг «патч нуждается в улучшении», добавляя еще один комментарий об улучшении реализации.
  • Алиса обновляет запрос на исправление, исправляя реализацию. Она снимает флаг «патч нуждается в доработке».
  • Дэйзи просматривает запрос и помечает билет как «Готов к проверке».
  • Джейкоб, коммиттер, рассматривает запрос на выгрузку и объединяет его.

Некоторые билеты требуют гораздо меньше отзывов, чем эти, но, опять же, некоторые билеты требуют гораздо больше.

Этапы подготовки

Ниже мы более подробно опишем различные этапы, через которые может пройти билет в течение своей жизни.

Не просмотрено

Этот билет не был рассмотрен кем-либо, кто считал бы себя компетентным для вынесения суждения о том, содержит ли билет действительную проблему, жизнеспособную функцию или должен быть закрыт по любой из различных причин.

Принято

Большая серая зона! Абсолютное значение слова «принято» заключается в том, что проблема, описанная в тикете, является действительной и находится на определенной стадии проработки. Помимо этого есть несколько соображений:

  • Принято + без флагов

    Билет действителен, но никто еще не представил исправление для него. Часто это означает, что вы можете смело приступать к написанию исправления для него. Обычно это больше относится к принятым ошибкам, чем к принятым функциям. Заявка на ошибку, которая была принята, означает, что проблема была проверена по крайней мере одним экспертом как легитимная - и, вероятно, должна быть исправлена, если это возможно. Принятая новая функция может означать только то, что один триггер решил, что функция была бы полезна, но это само по себе не представляет общего мнения и не означает, что патч для этой функции будет принят с какой-либо уверенностью. Если вы сомневаетесь, попросите больше отзывов, прежде чем писать обширный патч.

  • Принято + имеет патч

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

  • Принято + Есть патч + Требуется …

    Это означает, что билет был рассмотрен и признан нуждающимся в дальнейшей работе. «Нужны тесты» и «Нужна документация» не требуют пояснений. «Патч требует доработки» обычно сопровождается комментарием к билету, объясняющим, что нужно сделать для улучшения кода.

Готовность к регистрации

The ticket was reviewed by any member of the community other than the person who supplied the patch and found to meet all the requirements for a commit-ready patch. A committer now needs to give the patch a final review prior to being committed.

Существует множество запросов на исправление. Может пройти немало времени, прежде чем ваш патч будет рассмотрен. Некоторые идеи можно найти в contributing code FAQ здесь.

Когда-нибудь/может быть

Этот этап не показан на диаграмме. Он используется редко, чтобы отслеживать идеи высокого уровня или долгосрочные запросы на функции.

Эти тикеты встречаются редко и в целом менее полезны, поскольку не описывают конкретных проблем, которые можно решить. Это запросы на улучшения, которые мы можем рассмотреть возможность добавления в фреймворк, если будет представлен отличный патч. Они не являются высокоприоритетными.

Другие атрибуты сортировки

В билете можно установить несколько флагов, отображающихся в Trac в виде флажков:

Имеет заплату

Это означает, что билет имеет соответствующую оценку patch. Они будут рассмотрены, чтобы определить, является ли патч «хорошим».

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

N

N

N

N

Пластырь нуждается в улучшении

Этот флаг означает, что хотя билет имеет патч, он еще не готов к проверке. Это может означать, что патч больше не применяется в чистом виде, есть недостатки в реализации, или что код не соответствует нашим стандартам.

Легкая добыча

Билеты, которые потребуют небольших, простых исправлений.

Тип

Билеты должны быть разделены на категории по типу между:

  • Новая функция
    За добавление чего-то нового.
  • Ошибка
    Для случаев, когда существующая вещь сломана или ведет себя не так, как ожидалось.
  • Очистка/оптимизация
    Когда ничего не сломано, но что-то можно сделать чище, лучше, быстрее, сильнее.

Компонент

Тикеты должны быть классифицированы по компонентам, указывающим, к какой области кодовой базы Django они относятся. Это позволит лучше организовать билеты и облегчит их поиск.

Тяжесть

Атрибут severity используется для определения блокирующих факторов, то есть проблем, которые должны быть исправлены до выпуска следующей версии Django. Обычно это ошибки, вызывающие регрессию по сравнению с предыдущими версиями или потенциально приводящие к серьезным потерям данных. Этот атрибут используется довольно редко, и подавляющее большинство тикетов имеют серьезность «Normal».

Версия

Можно использовать атрибут version, чтобы указать, в какой версии была выявлена сообщенная ошибка.

UI/UX

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

Cc

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

Ключевые слова

С помощью этого поля вы можете обозначить билет несколькими ключевыми словами. Это может быть полезно, например, для группировки нескольких билетов одной тематики. Ключевые слова могут быть разделены запятыми или пробелами. Поиск по ключевым словам находит строку ключевого слова в любом месте ключевых слов. Например, при нажатии на билет с ключевым словом «форма» будут найдены похожие билеты, помеченные ключевыми словами, содержащими такие строки, как «formset», «modelformset» и «ManagementForm».

Билеты на закрытие

Когда билет завершает свой полезный жизненный цикл, его пора закрыть. Закрытие билета - это большая ответственность. Вы должны быть уверены, что проблема действительно решена, и помнить о том, что автор заявки может быть не в восторге от того, что его заявка закрыта (если она не исправлена!). Если вы не уверены в закрытии тикета, оставьте комментарий со своими мыслями.

Если вы все же закрыли билет, вам всегда следует убедиться в следующем:

  • Убедитесь, что вопрос решен.
  • Оставьте комментарий, объясняющий решение о закрытии билета.
  • Если есть способ улучшить билет, чтобы его снова открыть, сообщите им об этом.
  • Если билет является дубликатом, ссылайтесь на оригинальный билет. Также сделайте перекрестную ссылку на закрытый тикет, оставив комментарий в оригинальном тикете - это позволит получить доступ к дополнительной информации о заявленной ошибке или запрошенной функции.
  • Будьте вежливы. Никому не нравится, когда его билет закрывают. Это может расстроить или даже обескуражить. Лучший способ не оттолкнуть людей от участия в Django - быть вежливым и дружелюбным и предлагать предложения о том, как они могут улучшить этот билет и другие билеты в будущем.

Билет может быть разрешен несколькими способами:

  • исправлено
    Используется после того, как патч был внедрен в Django и проблема устранена.
  • недействительный
    Используется, если обнаружено, что билет некорректен. Это означает, что проблема в тикете на самом деле является результатом ошибки пользователя, или описывает проблему с чем-то другим, нежели Django, или вообще не является сообщением об ошибке или запросом функции (например, некоторые новые пользователи отправляют запросы в поддержку как тикеты).
  • wontfix
    Используется, когда кто-то решает, что запрос не подходит для рассмотрения в Django. Иногда тикет закрывается как «wontfix» с просьбой к автору начать обсуждение в списке рассылки django-developers, если его мнение отличается от обоснования, предоставленного человеком, закрывшим тикет. В других случаях обсуждение в списке рассылки предшествует решению о закрытии тикета. Всегда используйте список рассылки для достижения консенсуса перед повторным открытием тикетов, закрытых как «wontfix».
  • дубликат
    Используется, когда в другом тикете рассматривается тот же вопрос. Закрывая дублирующие тикеты, мы сохраняем все обсуждения в одном месте, что помогает всем.
  • worksforme
    Используется, когда билет не содержит достаточно деталей для воспроизведения исходной ошибки.
  • needsinfo
    Используется, когда билет не содержит достаточно информации для воспроизведения сообщенной проблемы, но потенциально все еще действителен. Билет следует открыть заново, когда будет предоставлена дополнительная информация.

Если вы считаете, что билет был закрыт по ошибке - потому что у вас все еще есть проблема, или она всплыла в другом месте, или триггеры допустили ошибку - пожалуйста, откройте билет заново и предоставьте дополнительную информацию. Опять же, пожалуйста, не открывайте повторно тикеты, которые были помечены как «wontfix», и вместо этого доведите проблему до django-developers.

Как я могу помочь с сортировкой?

Процесс сортировки в основном осуществляется членами сообщества. Действительно, ЛЮБОЙ может помочь.

Чтобы принять участие, начните с creating an account on Trac. Если у вас есть аккаунт, но вы забыли пароль, вы можете восстановить его с помощью password reset page.

Тогда вы можете оказать помощь:

  • Закрытие билетов «Unreviewed» как «invalid», «worksforme», или «duplicate», или «wontfix».
  • Закрытие тикетов «Unreviewed» как «needsinfo», когда описание слишком скудное, чтобы можно было принять меры, или когда это запросы функций, требующие обсуждения на django-developers.
  • Исправление флагов «Нужны тесты», «Нужна документация» или «Есть патч» для билетов, в которых они установлены неверно.
  • Установка флага «Easy pickings» для билетов, которые являются небольшими и относительно простыми.
  • Установите тип билетов, которые еще не классифицированы.
  • Проверка того, что старые билеты все еще действительны. Если в билете давно не было активности, возможно, проблема была устранена, но билет еще не закрыт.
  • Выявление тенденций и тем в тикетах. Если есть много сообщений об ошибках в конкретной части Django, это может указывать на то, что мы должны рассмотреть возможность рефакторинга этой части кода. Если наметилась тенденция, вам следует поднять ее для обсуждения (со ссылкой на соответствующие тикеты) на django-developers.
  • Проверьте правильность исправлений, представленных другими пользователями. Если они корректны, а также содержат соответствующую документацию и тесты, переведите их в стадию «Готов к проверке». Если они некорректны, оставьте комментарий с объяснением причин и установите соответствующие флаги («Патч требует доработки», «Требует проверки» и т.д.).

Примечание

В Reports page содержатся ссылки на множество полезных запросов Trac, включая несколько, полезных для сортировки тикетов и проверки патчей, как было предложено выше.

Вы также можете найти больше Советы начинающим вкладчикам.

Однако мы просим всех членов сообщества, работающих в базе данных билетов, соблюдать следующие требования:

  • Пожалуйста, не не продвигайте свои собственные билеты до «Готов к проверке». Вы можете пометить чужие билеты, которые вы просмотрели, как «Готов к проверке», но вы должны попросить как минимум еще одного члена сообщества просмотреть патч, который вы отправляете.
  • Пожалуйста, не отменяйте решение, не опубликовав сообщение django-developers для поиска консенсуса.
  • Если вы не уверены, стоит ли вносить изменение, не вносите его, а оставьте комментарий со своими опасениями в тикете или напишите сообщение на django-developers. Это нормально - быть неуверенным, но ваш вклад все равно ценен.

Биссектриса регрессии

Регрессия - это ошибка, которая присутствует в более новой версии 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 до появления регрессии (т.е. точку, в которой тест проходит). Используйте что-то вроде git checkout HEAD~100 для проверки более ранней ревизии (в данном случае на 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 и, пожалуйста, включите регрессионный тест в качестве приложения. Когда кто-нибудь напишет исправление ошибки, у него уже будет ваш тест в качестве отправной точки.

Вернуться на верх