= __Эффективная работа с TRAC__ = На этой странице приведены рекомендации по организации эффективной работы c системой отслеживания багов Trac и репозиториями исходных текстов. Эта страница не призвана заменить собой [wiki:TracTickets руководство] по работе с Trac, она лишь служит для напоминания о ряде моментов, на которые следует обращать внимание в процессе работы с системой, а также краткое обоснование, для чего это нужно. == Рекомендации по работе с тикетами == === Открывая тикет, присваивайте ему соответствующий тип === Существует несоклько типов тикетов: "баг", "улучшение" и "задача". Создавая тикет, выберить подходящий тип: * '''баг''' - если Вы считаете, что нашли ошибку в работе программы; * '''улучшение''' - если Вы придумали что-то улучшающее и/или расширяющее функционал программы (при том что отсутствие такого улучшения ошибкой не является); * '''задача''' - все, что не подходит под первые два типа. Обычно это какие-то вспомогательные работы, не связанные напрямую с разработкой кода - например, создание руководства по эксплуатации. === Создавая тикет с типом "баг", опишите подробности === Опишите суть бага: что программа сделала (не сделала), и что, по вашему мнению, она должна была сделать (или не должна была сделать). Также опишите, при каких обстоятельствах это произошло. Это позволит разработчику быстрее найти и устранить причину. Также см. [[wiki:WikiStart#ЕслиВынашлибаг|как сделать хороший баг рипорт]] === Добавляйте ключевые слова === Создавая тикет, по возможности добавьте ключевые слова, по которым впоследствии можно будет находить этот тикет. Указание ключевых слов помогут в поиске информации о проблеме через много лет. === Закрывая тикет, указывайте подходящую резолюцию === В системе есть ряд возможных резолюций (решений), одна из которых должна быть указана при закрытии тикета. Выбирайте резолюцию, подходящую для закрытия тикета, это позволит быстрее ориентироваться в списке тикетов при последующем анализе. Далее приводится перечень возможных резолюций и рекомендации по использованию каждой из них. || '''Резолюция''' || '''в каких случаях применяется''' || || fixed || Проблема успешно решена: баг выявлен и исправлен, улучшение реализовано. || || wontfix || Заявленный баг имеет место, но по каким-то причинам мы не хотим или не имеем возможности его устранить, поэтому принято решение оставить все как есть. То же касается предложенного улучшения. || || duplicate || Открытый тикет дублирует уже существующий. || || worksforme || Были приложены все возможные усилия и предприняты все мыслимые меры для воспроизведения бага и поиска возможной причины, но они не дали никакого результата - баг воспроизвести так и не удалось. || || invalid || Тикет был открыт по ошибке - например, автор тикета ошибочно посчитал багом штатное поведение программы, или неверное поведение программы явилось следствием неправильных действий пользователя. || === Не закрывайте тикет с резолюцией fixed, если исправление еще не внесено в репозиторий === Лучше исправить баг и забыть закрыть тикет, чем закрыти тикет "авансом" и потом забыть исправить баг. === Закрывая тикет, напишите в комментарии, по какой причине тикет закрыт === Это позволит впоследствии понять, чем закончилась работа по тикету - была ли решена проблема, если да, то как, если нет, что помешало ее решить и т.п. === Закрывая тикет с резолюцией fixed, указывайте номер ревизии, в которой сделано исправление === Это позволит сэкономить время на поиске соответствующего исправление в рапозитории. Пример комментария: {{{ Исправлено в r123: при нажатии "play", если диспетчер/техник не в конференции, автоматически создается новая конференция с ним и запись проигрывается туда. }}} Удобно делать ссылки на тикеты прямо в процессе коммита, как это описано [#ticket-refs ниже]. === Закрывая тикет с резолюцией duplicate, указывайте номер тикета, который был дублирован === Это позволит сразу перейти к описанию первоначально открытого тикета. === Если не удалось воспроизвести описанный в тикете баг, не закрывате тикет сразу === Если не удается воспроизвести баг, полезно провести анализ кода, определив хотя бы приблизительно возможные причины возникновения бага. Во-первых, есть ненулевая вероятность обнаружить ошибку прямо в процессе этого анализа. Во-вторых, определив вероятные места возникновения проблемы, можно придумать что-то чтобы минимизировать возможные последствия проблемы и подготовиться к новому появлению бага - например добавить какой-то отладочный вывод в каких-то ключевых местах, чтобы не просто ждать подтверждения самого факта, что баг по-прежнему присутствует, а чтобы очередное проявления бага дало какую-то полезную дополнительную информацию для нахождения и исправления бага. Вот когда эта работа (анализ и подготовка) проведена - тогда можно сказать: "я сделал все что мог", и ждать результата... === Делайте правильные ссылки на тикеты и ченжсеты === При написании комментариев делайте ссылки на тикеты или ревизии кода так, чтобы trac мог опознать их в коде и сделать ссылками, например {{{Исправлено в r123}}} или {{{описано в #24}}}. Это позволит открыть ссылку одним кликом, экономя время на поиски. Подробнее об оформлении ссылок смотрите [wiki:TracLinks здесь]. == Рекомендации по работе с репозиториями == === Не объединяйте в одном коммите несколько не связанных между собой исправлений === Внесение в репозиторий сразу нескольких логически между собой не связанных исправлений одним коммитом во-первых, затрудняет анализ сделанных изменений, во-вторых, если впоследствии выяснится, что в процессе работы была "сломана" какая-то функция, такие "групповые" коммиты затрудняют изоляцию проблемы и последующий откат "проблемного" исправления. Даже если Вы хотите просто подравнять отступы в исходном коде, делайте это отдельным коммитом. Но не стоит также увлекаться излишним разбиением модификации на несколько коммитов. Старайтесь чтобы проект после любого из ваших коммитов, по крайней мере, собирался. Например, добавив в одном программном модуле вызов новой функции, тем же коммитом добавляйте определение этой функции в другом модуле. === Делая коммит, описывайте в комментарии суть сделанных изменений === Это поможет, просматривая впоследствии журнал, находить нужное исправление. Не ограничивайтесь фразами типа "теперь работает" или "исправление 168". Когда через год вы (или другой разработчик) будете читать журнал в поисках какого-то исправления, вы не сможете понять, что этот комментарий означает. Не ограничивайтесь ссылкой на тикет - у читающего журнал может не быть доступа к trac, а даже если и есть, дублирование текста в журнале репозитория сэкономит время, затраченное на поиски тикета. === Если коммит связан с тикетом, дайте на него ссылку в комментарии === #ticket-refs Если коммит полностью исправляет заявленную в тикете проблему, укажите в комментарии номер(а) тикета(ов) с одним из слов "close", "closed", "closes", "fix", "fixed" или "fixes": {{{Closes #123}}} или {{{Fixes #23,#45}}}. В этом случае упомянутые тикеты будут автоматически закрыты с резолюцией fixed и со ссылкой на данный коммит в комментарии. Если коммит связан с тикетов (тикетами), но не завершает работу над ними, дайте ссылку на тикеты с одним из слов "addresses", "re", "references", "refs" или "see": {{{"See #27"}}} или {{{Refs #125,#52}}}. В перечисленные тикеты будет добавлен комментарий со ссылкой на данный коммит, но состояние тикетов не будет изменено (они не будут закрыты). Подробнее о !CommitTicketUpdater смотрите [https://trac.edgewall.org/wiki/CommitTicketUpdater#Usage здесь].