Описание пулл реквестов

Номер

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

        
          Jira references: 
             • Ticket (issue) — https://catsfactory.atlassian.net/browse/ticket-295
        
      

Название

Название должно тезисно описывать изменения — быть кратким и лаконичным. Следуйте правилам оформления заголовков:

• начинать с заглавной буквы,
• без точки вконце,
• иметь повелительное наклонение.

        
            Ticket-295: Add base cat interface and british cat realization
        
      

Разметка и примеры

Акцентируйте внимание на важные части изменений. Используйте логическую и визуальную разметку, например, markup или html.

• Подчеркивайте важные слова и фразы, имена собственные.
• Используйте списки, чтобы выделить последовательность или маркировать предложения.
• Заботьтесь о читабельности, используйте троеточие, чтобы скрыть лишнее.
• Приводите части кода или моделей данных.
• Прикрепляйте скриншоты результатов работы, если вы работаете с пользовательскими интерфейсами.

        
          class BritishCat implements Cat:
              
             public name
             public age
              
             ...
        
      

Описание

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

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

        
          The base cats interface was created to provide the common cats functionality 
          and attributes. Also the realization of the British cats was created as the individual one.

          Our business-analytics have provided for product owner that they want to interect with cats on out platform too, not only with docs. So developers got the tasks to 
          design and implement basic implementation of the cats interface to describe the common patterns of the interaction with it by user. Also the goal was to create 
          one demo cat called British cats (British Shorthair) with its great noses.
        
      

Советы из раздела Письменная коммуникация применима и к описанию пулл реквеста.

Ссылки

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

Что сделано

Выделите блок текста с описанием, что конкретно вы сделали:

• не скупитесь на детали,
• пишите на полутехническом и полубизнес языке,
• уделяйте внимание деталям и полностью описывайте изменения,
• приводите примеры использования вашего кода.

        
          Implemented:
             — create cats interface with the following structure:
          
                
                  interface Cat:

                     public name
                     public age

                     func run(destination: Destination)
                     func eat(food: Food)
                
              
   — create British cat implemented cats interface with unique type of nose;    — migrate database settings from SQLite to CatSQL.

Справка

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

• кратко описывайте куда направляет справка,
• если возможно — кидайте полные ссылки,
• если нет — сокращайте с помощью git.io, goo.gl, bit.ly,
• оформляйте списком.

        
          References:
             • British cats — https://en.wikipedia.org/wiki/British_Shorthair
             • Cats anatomy — https://en.wikipedia.org/wiki/Cat_anatomy
        
      

Пример

Таким может быть описание пулл реквеста на Github:

Communication