| | 1 | = __Эффективная работа с TRAC__ = |
| | 2 | |
| | 3 | На этой странице приведены рекомендации по организации эффективной работы c системой отслеживания багов Trac и репозиториями исходных текстов. Эта страница не призвана заменить собой [wiki:TracTickets руководство] по работе с Trac, она лишь служит для напоминания о ряде моментов, на которые следует обращать внимание в процессе работы с системой, а также краткое обоснование, для чего это нужно. |
| | 4 | |
| | 5 | == Рекомендации по работе с тикетами == |
| | 6 | |
| | 7 | === Открывая тикет, присваивайте ему соответствующий тип === |
| | 8 | |
| | 9 | Существует несоклько типов тикетов: "баг", "улучшение" и "задача". Создавая тикет, выберить подходящий тип: |
| | 10 | |
| | 11 | * '''баг''' - если Вы считаете, что нашли ошибку в работе программы; |
| | 12 | * '''улучшение''' - если Вы придумали что-то улучшающее и/или расширяющее функционал программы (при том что отсутствие такого улучшения ошибкой не является); |
| | 13 | * '''задача''' - все, что не подходит под первые два типа. Обычно это какие-то вспомогательные работы, не связанные напрямую с разработкой кода - например, создание руководства по эксплуатации. |
| | 14 | |
| | 15 | === Создавая тикет с типом "баг", опишите подробности === |
| | 16 | |
| | 17 | Опишите суть бага: что программа сделала (не сделала), и что, по вашему мнению, она должна была сделать (или не должна была сделать). Также опишите, при каких обстоятельствах это произошло. Это позволит разработчику быстрее найти и устранить причину. |
| | 18 | |
| | 19 | Также см. [[wiki:WikiStart#ЕслиВынашлибаг|как сделать хороший баг рипорт]] |
| | 20 | |
| | 21 | === Добавляйте ключевые слова === |
| | 22 | |
| | 23 | Создавая тикет, по возможности добавьте ключевые слова, по которым впоследствии можно будет находить этот тикет. Указание ключевых слов помогут в поиске информации о проблеме через много лет. |
| | 24 | |
| | 25 | === Закрывая тикет, указывайте подходящую резолюцию === |
| | 26 | |
| | 27 | В системе есть ряд возможных резолюций (решений), одна из которых должна быть указана при закрытии тикета. Выбирайте резолюцию, подходящую для закрытия тикета, это позволит быстрее ориентироваться в списке тикетов при последующем анализе. Далее приводится перечень возможных резолюций и рекомендации по использованию каждой из них. |
| | 28 | |
| | 29 | || '''Резолюция''' || '''в каких случаях применяется''' || |
| | 30 | || fixed || Проблема успешно решена: баг выявлен и исправлен, улучшение реализовано. || |
| | 31 | || wontfix || Заявленный баг имеет место, но по каким-то причинам мы не хотим или не имеем возможности его устранить, поэтому принято решение оставить все как есть. То же касается предложенного улучшения. || |
| | 32 | || duplicate || Открытый тикет дублирует уже существующий. || |
| | 33 | || worksforme || Были приложены все возможные усилия и предприняты все мыслимые меры для воспроизведения бага и поиска возможной причины, но они не дали никакого результата - баг воспроизвести так и не удалось. || |
| | 34 | || invalid || Тикет был открыт по ошибке - например, автор тикета ошибочно посчитал багом штатное поведение программы, или неверное поведение программы явилось следствием неправильных действий пользователя. || |
| | 35 | |
| | 36 | === Не закрывайте тикет с резолюцией fixed, если исправление еще не внесено в репозиторий === |
| | 37 | |
| | 38 | Лучше исправить баг и забыть закрыть тикет, чем закрыти тикет "авансом" и потом забыть исправить баг. |
| | 39 | |
| | 40 | === Закрывая тикет, напишите в комментарии, по какой причине тикет закрыт === |
| | 41 | |
| | 42 | Это позволит впоследствии понять, чем закончилась работа по тикету - была ли решена проблема, если да, то как, если нет, что помешало ее решить и т.п. |
| | 43 | |
| | 44 | === Закрывая тикет с резолюцией fixed, указывайте номер ревизии, в которой сделано исправление === |
| | 45 | |
| | 46 | Это позволит сэкономить время на поиске соответствующего исправление в рапозитории. Пример комментария: |
| | 47 | {{{ |
| | 48 | Исправлено в r123: при нажатии "play", если диспетчер/техник не в конференции, |
| | 49 | автоматически создается новая конференция с ним и запись проигрывается туда. |
| | 50 | }}} |
| | 51 | |
| | 52 | Удобно делать ссылки на тикеты прямо в процессе коммита, как это описано [#ticket-refs ниже]. |
| | 53 | |
| | 54 | === Закрывая тикет с резолюцией duplicate, указывайте номер тикета, который был дублирован === |
| | 55 | |
| | 56 | Это позволит сразу перейти к описанию первоначально открытого тикета. |
| | 57 | |
| | 58 | === Делайте правильные ссылки на тикеты и ченжсеты === |
| | 59 | |
| | 60 | При написании комментариев делайте ссылки на тикеты или ревизии кода так, чтобы trac мог опознать их в коде и сделать ссылками, например {{{Исправлено в r123}}} или {{{описано в #24}}}. Это позволит открыть ссылку одним кликом, экономя время на поиски. Подробнее об оформлении ссылок смотрите [wiki:TracLinks здесь]. |
| | 61 | |
| | 62 | == Рекомендации по работе с репозиториями == |
| | 63 | |
| | 64 | === Не объединяйте в одном коммите несколько не связанных между собой исправлений === |
| | 65 | |
| | 66 | Внесение в репозиторий сразу нескольких логически между собой не связанных исправлений одним коммитом во-первых, затрудняет анализ сделанных изменений, во-вторых, если впоследствии выяснится, что в процессе работы была "сломана" какая-то функция, такие "групповые" коммиты затрудняют изоляцию проблемы и последующий откат "проблемного" исправления. Даже если Вы хотите просто подравнять отступы в исходном коде, делайте это отдельным коммитом. |
| | 67 | |
| | 68 | Но не стоит также увлекаться излишним разбиением модификации на несколько коммитов. Старайтесь чтобы проект после любого из ваших коммитов, по крайней мере, собирался. Например, добавив в одном программном модуле вызов новой функции, тем же коммитом добавляйте определение этой функции в другом модуле. |
| | 69 | |
| | 70 | === Делая коммит, описывайте в комментарии суть сделанных изменений === |
| | 71 | |
| | 72 | Это поможет, просматривая впоследствии журнал, находить нужное исправление. Не ограничивайтесь фразами типа "теперь работает" или "исправление 168". Когда через год вы (или другой разработчик) будете читать журнал в поисках какого-то исправления, вы не сможете понять, что этот комментарий означает. Не ограничивайтесь ссылкой на тикет - у читающего журнал может не быть доступа к trac, а даже если и есть, дублирование текста в журнале репозитория сэкономит время, затраченное на поиски тикета. |
| | 73 | |
| | 74 | === Если коммит связан с тикетом, дайте на него ссылку в комментарии === #ticket-refs |
| | 75 | |
| | 76 | Если коммит полностью исправляет заявленную в тикете проблему, укажите в комментарии номер(а) тикета(ов) с одним из слов "close", "closed", "closes", "fix", "fixed" или "fixes": {{{Closes #123}}} или {{{Fixes #23,#45}}}. В этом случае упомянутые тикеты будут автоматически закрыты с резолюцией fixed и со ссылкой на данный коммит в комментарии. |
| | 77 | |
| | 78 | Если коммит связан с тикетов (тикетами), но не завершает работу над ними, дайте ссылку на тикеты с одним из слов "addresses", "re", "references", "refs" или "see": {{{"See #27"}}} или {{{Refs #125,#52}}}. В перечисленные тикеты будет добавлен комментарий со ссылкой на данный коммит, но состояние тикетов не будет изменено (они не будут закрыты). |
| | 79 | |
| | 80 | Подробнее о !CommitTicketUpdater смотрите [https://trac.edgewall.org/wiki/CommitTicketUpdater#Usage здесь]. |
