Backstage Software Catalog: English Vocabulary for Platform Teams (англійською)

Backstage, портал розробників з відкритим кодом від Spotify, став стандартним інструментом для інженерних команд платформи в компаніях будь-якого розміру. Якщо ви працюєте у команді з розробки платформи або використовуєте внутрішні інструменти розробників, ви щодня стикаєтеся з словником Backstage під час зустрічей, у гілках Slack і під час перегляду запитів на витягування. У цьому довіднику пояснюється основні англійські терміни і фрази, щоб ви могли безпечно брати участь у таких розмовах.

---

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

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

“Перед тим, як почати збирання нової служби, перевірте каталог програмного забезпечення — можливо, вже існує бібліотека, яка виконує те, що вам потрібно.”

** Сутність ** — будь- який елемент, зареєстрований у каталозі Backstage. Сутність має kind (наприклад, Component, API, або Resource), namespace, і name. Кожна сутність описується в файлі catalog-info.yaml, який заноситься до її сховища.

“У каталозі наразі є 340 об’ єктів — 210 компонентів, 80 API і 50 ресурсів.”

** catalog-info.yaml ** — файл налаштувань, який ви додаєте до сховища, щоб зареєструвати його як об’ єкт у каталогу програмного забезпечення. Він декларує тип сутності, власника, стадію життєвого циклу і відносини з іншими сутностями.

• “Конвейер не пройшов перевірку власника, оскільки у файлі catalog-info.yaml відсутнє поле spec.owner.” *

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

“Наші Runbooks тепер знаходяться в TechDocs — інженерам більше не потрібно шукати в Confluence, щоб знайти завчасно створений Playbook.”

** Скафлдер (Шаблони програмного забезпечення) ** — функція Backstage, яка надає змогу командам розробників платформи створювати * шаблони * для нових проектів. Коли розробник хоче створити нову службу, він відкриває теку scafffolder, вибирає шаблон, заповнює форму, і Backstage автоматично створює сховище, додає catalog-info.yaml і реєструє нову сутність.

“Ми використовували scafffolder для запуску нової служби платежів — це зайняло три хвилини, а сховище вже було налаштовано з CI, linting і метаданими власника.”

** Додаток ** — самостійний додаток, який додає функціональність до Backstage. Додатки можуть бути інтерфейсними (додавання сторінок і карток до порталу), серверними (додавання API) або обома. Екосистема Backstage має сотні плагінів з відкритим кодом, що покривають Kubernetes, управління витратами, сканування безпеки і багато іншого.

• “Ми встановили додаток PagerDuty — тепер інженери можуть бачити розклад роботи під час чергування і активні випадки безпосередньо на порталі Backstage без перемикання вкладок.” *

Власник — команда або особа, відповідальна за суб’єкт, оголошений в catalog-info.yaml під spec.owner. Власність є критичним для реагування на інцидент і для маршрутизації питань до правильної команди.

“Каталог показує, що checkout-api належить команді платежів — я підніму цю проблему з ними безпосередньо.”

** Жіночий цикл ** — поле метаданих на компоненті, яке вказує на його стадію зрілості: зазвичай experimental, production або deprecated. Команди використовують стан життєвого циклу, щоб вирішити, чи можна безпечно встановити залежність від компонента.

“Ця бібліотека все ще позначена як experimental у каталогу — я не приймав би жорсткої залежності від неї для виробничої служби.”

---

Корисні фрази

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

• “Я підняв PR, щоб додати catalog-info.yaml — як тільки він з’ єднається, служба з’ явиться в каталогу автоматично.”
• • “Шаблон теки, який ми створили, скоротив час налаштування нової служби з двох днів до близько 20 хвилин.” *
• • “Чи можете ви перевірити, чи документовано цей API у TechDocs? Команда повинна була опублікувати там підручники.»*
• “Ми повинні впорядкувати метадані власника — близько 30% наших об’єктів каталогу не мають власника, що робить відповідь на інцидент болісною.”
• • “Я встановив додаток Lighthouse у попередньому спринті, щоб менеджери продуктів могли бачити показники продуктивності всіх наших компонентів інтерфейсу у одному місці.” *

---

Поширені помилки

** Плутанина між « об’ єктом » і « компонентом ». ** У повсякденній мові інженери іноді говорять * « компонент » *, коли мають на увазі будь- який об’ єкт. У Backstage, Component є специфічним kind — він представляє розгортання частини програмного забезпечення (сервіс, веб-сайт, бібліотека). Сутність API описує інтерфейс, а суть Resource описує інфраструктуру, наприклад базу даних або S3 bucket. Використання цих термінів точно уникає плутанини під час написання файлів catalog-info.yaml або обговорення структури каталогів.

** Використання слова « вивантажити » замість « зареєструвати ». ** Люди, які не є носієм мови, іноді кажуть * « Я вивантажив службу до каталогу ». * Правильним дієсловом є * register *: * « Я зареєстрував службу у каталогу » * або * « Я додав службу до каталогу ». * Каталог знаходить об’ єкти читанням файлів catalog-info.yaml з джерела контролю — нічого не вивантажено у традиційному сенсі.

** Неправильна вимова « scaffold » і « scaffolder ». ** Слово * scaffold * вимовляється ** SKAF-old ** (перший склад римується з *staff *, а c перед a не вимовляється). Інженери, які не знають англійської, іноді вимовляють c як твердий звук. Вправи на мовлення: * “Ми створили нову службу за допомогою Backstage scaffolder.” *

---

Засновники розуміють основні поняття — каталог є єдиним джерелом правди, сутності — це елементи, які містяться у ньому, TechDocs зберігає документацію поруч з кодом, а тека scaffolding перетворює ваші найкращі практики у шаблони, які можна використовувати знову і знову, і кожну команду можна використовувати з першого дня.

Розрізняють: практичні (прикладні) та загальні (об’єктивні) методи

Будьмо чесними - вивчення професійної англійської, особливо в технічній галузі, такій як інженерія платформ, може бути приголомшливим. Ви освоїли * концепції * Backstage і його компонентів — ви розумієте, що файл catalog-info.yaml описує вашу технічну документацію, тека scafffold генерує код для нових об’ єктів, а додатки розширюють функціональність Backstage. Але перетворити це розуміння на чітке, коротке спілкування англійською мовою може бути складно. Багато розробників, особливо ті, чия перша мова не є англійською, борються з нюансами фразування, які очікуються при обговоренні технічних проектів, надаючи зворотній зв’язок щодо коду або документуючи рішення.

Поширеною пасткою є надмірна залежність від буквальних перекладів з вашої рідної мови. Наприклад, розробник може інстинктивно сказати « нам потрібно * інтегрувати * цю функціональність », коли він має на увазі « нам потрібно побудувати цю функціональність у існуючу платформу ». Хоча « інтегрувати » не є * помилкою *, йому бракує точності, очікуваної у дискусіях Backstage щодо розширення каталогів і додавання об’ єктів — такі терміни як « розширити » або « збільшити » є більш поширеними. Аналогічно, формулювання зворотного зв’язку як «цей код поганий» може бути не корисним. Замість того, щоб робити критику беззастережно, конструктивний коментар буде таким: « Ця функція могла б отримати користь від більш чіткої обробки помилок; розгляньте можливість додавання блоків try...catch для граціозного управління потенційними винятками ». Сфокусування на * що * потребує поліпшення і * чому * надає більш дієві рекомендації.

Іншою частою проблемою є використання надто складного словника, коли простіших термінів достатньо. Сам термін «суб’єкт» може бути загрозливим, але він просто відноситься до окремого шматка даних або функціональності в межах вашої платформи - облікового запису користувача, таблиці бази даних або кінцевої точки API. Аналогічно, опис зміни як «зміна основної інфраструктури» звучить неймовірно пригнічуючим; такі фрази, як «зміна конфігурації для служби автентифікації» є набагато більш доступними і легко зрозумілими для більшої аудиторії. Пам’ятайте, ясність - це найважливіше.

І нарешті, зверніть увагу на формальність вашого спілкування. Повідомлення Slack повинні бути розмовними, але описи PR і коментарі перегляду коду вимагають рівня точності, який відповідає професійним стандартам. Добре написаний опис PR може починатися з: «Цей запит на витягування вводить нову сутність для керування профілями користувачів, покращуючи здатність нашої платформи до…».

Ось приклад, який показує, як можна використовувати команди backstage dev у практичному випадку:

backstage dev --entity-id my-team/user-profile --scaffold create-profile-form

За допомогою цієї команди можна продемонструвати функціональність scafffolder — створення базової форми для створення профілів користувачів за вказаним ідентифікатором об’ єкта. Для ефективного використання цієї команди і її виводу у обговоренні слід ясно вказати на мету створення форми, її взаємодію з існуючими об’ єктами і всі необхідні налаштування.