Обзоры кода

В этом документе объясняется философия проверки кода команды XLA — философия, которую мы разработали за годы коллективного опыта работы над проектами с открытым исходным кодом в целом и XLA в частности.

Различные проекты с открытым исходным кодом имеют разные культурные ожидания относительно того, сколько рецензенты могут требовать от авторов кода. В некоторых проектах рецензенты берут «в основном правильный» запрос на включение (PR), самостоятельно изменяют его и отправляют. XLA использует другой подход: мы ожидаем, что авторы будут повторять PR до тех пор, пока они не станут достаточно хороши, чтобы их можно было отправлять без дополнительных изменений.

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

Чтобы стать «полноценным участником XLA», нужно не просто писать код, в котором нет ошибок. О вкладе в XLA можно узнать гораздо больше. Это включает в себя:

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

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

Как и во многих проектах с открытым исходным кодом, в XLA работают несколько опытных людей и много относительно новых людей. У тех из нас, кто имеет большой опыт, много требований к нашему времени. Вы можете обеспечить своевременное продвижение PR и сократить количество итераций, следуя этим советам:

  • Внимательно просмотрите свой PR и/или попросите коллегу просмотреть его перед отправкой: постарайтесь удалить незначительные ошибки (стиль кода, орфографические и грамматические ошибки и т. д.), прежде чем отправлять PR на проверку. Убедитесь, что все тесты пройдены.
  • Внимательно прочитайте комментарии рецензента: постарайтесь понять, о чем просит рецензент, и постарайтесь учесть все комментарии, прежде чем выпустить новую версию.
  • Избегайте второстепенных дискуссий (навес для велосипедов): Технические дискуссии и разногласия очень ценны, и никто не идеален. Однако избегайте дискуссий, которые не имеют никакого значения или носят чисто стилистический характер. Если вы не согласны с комментарием рецензента, постарайтесь подробно и подробно изложить свои причины, чтобы избежать долгих дискуссий.
  • Избегайте задавать «часто задаваемые вопросы для обзора», перечисленные ниже: ниже мы перечислили некоторые ответы на распространенные вопросы и наше обоснование.

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

Спасибо за вклад в XLA и удачного взлома!

Часто задаваемые вопросы по отзывам

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

Рецензенты XLA могут попросить вас создать некоторую инфраструктуру (или иным образом внести значительные изменения в PR) вместе с написанным вами PR. Этот запрос может показаться ненужным или противоречащим изменению, которое вы пытаетесь внести. Вероятно, это связано с несоответствием между вашими ожиданиями относительно того, сколько информации вам нужно создать, и ожиданиями вашего рецензента на этот счет.

Несовпадение ожиданий – это нормально! Это ожидаемо, когда вы новичок в проекте (и иногда это случается даже с нами, старыми шляпами). Вполне вероятно, что проекты, над которыми вы работали в прошлом, имеют другие ожидания. Это тоже нормально и ожидаемо! Это не означает, что ни один из этих проектов имеет неправильный подход; они просто другие. Мы приглашаем вас принять инфраструктурные запросы вместе со всеми другими отзывами, чтобы узнать, чего мы ожидаем от этого проекта.

«Могу ли я рассмотреть ваш комментарий в будущем пиаре?»

В отношении запросов на инфраструктуру (или других крупных запросов) в ОР часто возникает вопрос: необходимо ли вносить изменения в первоначальный ОР или можно ли это сделать в качестве дополнения к будущему ОР?

Как правило, XLA не позволяет авторам PR отвечать на комментарии к отзывам с помощью последующих PR. Когда рецензент решает, что что-то необходимо исправить в данном PR, мы обычно ожидаем, что авторы учтут это в этом PR, даже если то, что запрошено, является большим изменением. Этот стандарт применяется как снаружи, так и внутри Google.

Есть несколько причин, по которым XLA использует такой подход.

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

  • Влияние на других разработчиков: если вы отправили PR, касающееся определенной части XLA, есть большая вероятность, что другие люди просматривают ту же часть. Если мы признаем технический долг в вашем PR, то этот долг будет затрагивать всех, кто просматривает этот файл, до тех пор, пока не будут отправлены последующие действия.

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