Англійською мовою для розробників Bazel Build System

Пообіцянка Базеля щодо швидких, відтворюваних збірок базується на словнику герметичності, графіків залежностей і кешування, для яких команда потребує спільної мови, тому що «збірка повільна» або «збірка нерівна» майже завжди веде до однієї з декількох конкретних, іменованих причин. Цей підручник містить інформацію англійською мовою, яку використовують під час обговорення налаштування Bazel з командою.

Ключовий словник

Target — названий, збудований або тестований блок, оголошений у файлі BUILD (бібліотека, бінарний файл або тест), базовий блок Bazel розкладає і кешує незалежно.

• “Розділити це на дві цілі замість однієї монолітної бібліотеки — зараз зміна непов’ язаного файла змушує перебудувати всі залежні цілі.” *

** Герметичність ** — властивість збірки, яка залежить лише від її оголошених вхідних даних, без залежності від стану навколишньої системи, доступу до мережі або версій інструментів, які не було прив’ язано до цієї властивості, що робить збірки відтворюваними і кешованими. “Ця перевірка читає файл з /tmp поза його оголошеними вхідними даними — це порушує герметичність, тому вона проходить локально, але зазнає невдачі в віддаленому кеші.”

** Графік збирання ** — графік залежностей, який Bazel створює з оголошених цілей і їх залежностей, використовується для визначення того, що потрібно перезбирати і що можна запускати паралельно. “Додання цієї залежності створює цикл у графі збирання — нам потрібно витягнути спільну частину у власну ціль, від якої можуть залежати обидві сторони.”

** Віддалений кеш ** — спільний кеш виводів збирання і тестування, ключі якого визначаються за вхідними гешами, що дозволяє одній машині повторно використовувати результати збирання іншої машини замість перебудови з нуля. “Ця ціль не вдаряє по віддаленому кешу, оскільки її вхідні дані дії містять штамп часу — давайте зробимо вхідні дані детермінованими, щоб вдаряння по кешу дійсно працювали.”

** Пісочниця ** — запуск кожної дії збирання у ізольованому середовищі, де буде видно лише її оголошені вхідні дані, за допомогою чого Bazel буде перехоплювати приховані або неоголошені залежності. “Увімкніть пісочницю локально перед зневадженням — без неї збирання може бути тихо залежним від файла, який не оголошено, і ви не побачите проблему до CI.”

** Visibility ** — атрибут файла BUILD, який обмежує кількість інших цілей, які можуть залежати від заданої цілі, використовується для забезпечення кордонів модулів у великому моно- сховищі. “Встановити видимість цього призначення тільки для пакунка команди-власника — зараз будь-хто у монорепо може залежати від нього, що знищує сенс внутрішнього API.”

Звичайні фрази

• Чи це герметична конструкція, чи залежить вона від чогось поза її декларованими вхідними даними?»
• «Чому це не вдаряє в віддалений кеш — є вхід недетермінованим?»
• Чи є в цьому прикладі значення для графіка?
• Чи можемо ми запустити це з ввімкненим пісочницею, щоб вловити будь-які незадекларовані залежності?»
• Чи повинна бути видимість цієї цілі обмежена, або вона повинна залишатися публічною?»

Приклади висловлювань

Перегляд запиту на звантаження: “Ця нова ціль не має обмежень видимості, тому будь-який пакунок у монорепо може залежати від неї — давайте розширимо її до двох споживачів, які насправді її потребують.”

Пояснення рішення про проектування:

• “Ми розділили спільну бібліотеку інструментів на менші цілі відповідальності, тому зміна помічника журналювання не змушує перебудовувати кожного користувача більшої бібліотеки.” *

Опис події: “Збірка була негерметичної — тест читав системний годинник безпосередньо, що означало, що кешовані результати іноді були застарілими і давали хибно позитивні результати.”

Професійні поради

• Скажіть “герметично”, особливо, коли відтворюваність збирання під загрозою — це точний термін, який використовують інженери Bazel, більш специфічний, ніж “чистий” або “ізольований”
• Коли кеш зневадження не знаходиться, запитайте “чи є недетермінований вхід?” — часові штампи, абсолютні шляхи і змінні середовища є зазвичай підозрілими, і їх назва прискорює сортування.
• Використовуйте “build graph” замість “dependencies” при обговоренні структурних питань, таких як цикли — це сигналізує, що ви думаєте про всю DAG, а не лише про одну ребро.
• Розрізняти « пісочницю » (ізоляція доступу до файлової системи дії) від « герметичності » (властивість, яку має мати вся збірка) — пісочниця — це техніка, яка допомагає забезпечити герметичність.

Практичні вправи

1. Поясніть двома реченнями, чому негерметична збірка підриває віддалений кеш Bazel.
2. Написати коментар перегляду коду у одному реченні, у якому буде позначено надто широкий спектр видимості цілі.
3. Опишете вашими словами, чому розділення монолітної цілі на менші частини прискорює час збирання.

Науковий напрямок: «Системи управління комунікаціями»

Багато розробників, які вивчають професійну англійську, особливо ті, хто переходить на ролі, що включають складні інструменти, такі як Bazel, стикаються не тільки з окремими словами, але і зі * способом *, у який ці слова використовуються в спільному потоці роботи. Легко перекласти буквально з вашої рідної мови, але тонкі відмінності у фразуваннях - особливо навколо опису проблем, пропозицій покращень або прохання про пояснення - можуть призвести до непорозумінь і розчарування. Ключовим елементом є визнання того, що технічні дискусії не просто про передачу інформації; вони про будівництво консенсусу і забезпечення того, щоб всі були на одній сторінці.

Одна з найпоширеніших проблем виникає при отриманні коментаря перегляду коду. Припустимо, що рецензент позначає зміну в базельській цілі: «Ця ціль здається надто складною. Чи можете ви розглянути можливість розбити його на менші, більш керовані кроки?” Прямий переклад може зосередитись лише на * складності * цілі. Однак, краща відповідь визнає занепокоєння рецензента і запрошує до співпраці. Замість того, щоб оборонно сперечатися про оригінальний дизайн, розробник міг би відповісти щось на зразок: «Дякую за вказівку! Я дякую, що ви підкреслили потенційну складність. Я спочатку намагався знайти коротке рішення, але ясно, що розбиття цього на частини покращить підтримку і тестування. Чи можемо ми обговорити найкращий підхід до модулізації?» Це демонструє активне слухання і бажання пристосуватися.

Інша область труднощів часто лежить в описах PR. Написання ефективних повідомлень про затвердження, які по суті є міні-документацією, вимагає точності. Замість простого зауваження «Виявлена помилка», хороший опис би надав контекст: «Виявлено: вирішено проблему, коли збірка Bazel зазнала невдачі через неправильне розв’язання залежностей при збиранні цілі my_library проти певної версії some_other_lib. Оновлено файл BUILD, щоб явно оголосити необхідні залежності і додано тестовий випадок для перевірки виправлення. » Цей рівень деталізації є критичним для супроводжувачів, яким зрештою слід буде зрозуміти * чому * було внесено зміну.

Нарешті, будьте уважні до термінології, пов’язаної з побудовою графів - поняття, такі як “герметичність” і “ланцюги залежності” можуть здатися абстрактними. Під час обговорення проблем зі своєю командою, зосередьтеся на описі * впливу *, а не просто використовуйте жаргон. Наприклад, замість того, щоб сказати: «Граф збирання порушує герметичність», ви можете сказати: «Ми бачимо несподівану поведінку, тому що зміни в цьому призначення ненавмисно впливають на інші частини системи збирання»

Ось приклад того, як можна використовувати bazel query під час розслідування проблеми зі збиранням:

bazel query '(//my/project:default) ^( //my/project/some_target)'

Ця команда допомагає ідентифікувати всі цілі, що залежать від //my/project/some_target. Зрозуміти вивід - і бути в змозі сформулювати, що це означає з точки зору залежностей збирання - це ключова навичка.