Linear API: Інтеграція управління проектами англійською мовою для розробників

Linear — це інструмент керування проектами, популярний серед програмістів за швидкість і дизайн, що орієнтований на клавіатуру. Його API дозволяє вам створювати інтеграції, автоматизувати робочі потоки і вбудовувати відстеження проблем у ваші власні продукти. API заснований на GraphQL, що означає, що словник включає як концепції, специфічні для Linear, так і загальну термінологію GraphQL. Цей запис допоможе розробникам ESL прочитати документацію з Linear API, написати код інтеграції і обговорити інструменти керування проектом англійською мовою.

---

Основна модель даних

** Проблема ** — фундаментальна одиниця роботи у Linear; проблема має назву, опис, стан, відповідача, пріоритет і оцінку, вона належить до Команди і, за бажанням, до Проекту або Циклю.

“Наша дія GitHub створює лінійну проблему автоматично, коли помилка Sentry трапляється більше десяти разів за годину, посилаючись на ідентифікатор помилки в описі проблеми.”

** Команда ** — група людей у Linear, які спільно користуються списком нерозв’ язаних завдань, станами потоку робіт і визначеннями міток; кожне завдання належить лише одній команді.

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

** Проект ** — контейнер для збірки проблем, які мають спільну мету і часову шкалу; проекти розташовуються вище окремих проблем і можуть охоплювати декілька команд.

“Ми створили проект під назвою ‘Q3 API Refactor’, щоб згрупувати всі пов’язані проблеми, щоб зацікавлені сторони могли відстежувати загальний прогрес на одній сторінці.”

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

“Наш бот планування запитує поточний цикл і публікує резюме його питань в Slack кожного понеділка вранці, щоб команда почала тиждень з повним контекстом.”

** План** — перегляд вищого рівня, який групує проекти за часом; лінійний API показує дані плану, щоб ви могли показувати стратегічні плани на зовнішніх панелях інструментів або у виконавчих звітах.

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

---

Схема і запити GraphQL

** GraphQL schema ** — типове визначення кожного об’ єкта, поля, запиту і мутації, доступних у API Linear; Linear публікує схему, яку можна досліджувати за допомогою інструментів, на зразок GraphQL Playground.

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

** mutation ** — дія GraphQL, яка змінює дані; Linear показує мутації для створення проблем, оновлення станів, призначення користувачів тощо.

• “Інтеграція викликає issueCreate з назвою та ідентифікатором команди, отриманими з попередження Sentry, щоб відкрити нову проблему в Linear.” *

** connection ** — шаблон сторінкування GraphQL Linear використовується для полів списку; з’ єднання містить список ребер, кожен з яких містить вузол (справжній об’ єкт) і курсор для отримання наступної сторінки.

• “Ми ітеруємо через з’ єднання проблем за допомогою курсора після, щоб отримати всі 500 проблем у списку очікування, 50 за раз.” *

---

Потік і сортування

** триаже ** — процес перегляду новостворених проблем і присвоєння їм пріоритету, стану і власника; у Linear для цієї мети передбачено спеціальний стан триаже і скриньку вхідних повідомлень.

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

** estimate ** — числове значення (часто у пунктах історії або одиницях часу), яке прив’ язано до проблеми, щоб вказати очікувані витрати часу; доступ до нього можна отримати за допомогою API для обчислень часу виконання і швидкості.

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

---

Webhooks і OAuth

** webhook event ** — корисна інформація JSON, яку Linear надсилає на налаштовану адресу URL кожного разу, коли відбувається вказана дія, наприклад, створюється, оновлюється або вилучається випуск.

“Ми налаштували підписку на події webhook для issueUpdated, щоб наш конвеєр розгортання автоматично закривав пов’ язані проблеми, коли мітка випуску надсилається на GitHub.”

OAuth — поток авторизації, який використовує Linear для надання стороннім програмам доступу до даних користувача або організації від їх імені, без спільного використання унікальних даних.

“Ми реалізували поток OAuth, щоб користувачі могли з’ єднати свій робочий простір Linear з нашим інструментом за три клацання, і ми безпечно зберігаємо токени доступу для викликів API від їх імені.”

---

Practice

Написати запит GraphQL, який отримає назву, стан і ім’ я відповідача для всіх відкритих завдань у певній команді Linear. Потім напишіть мутацію, яка оновить одну з цих проблем на інший стан. Англійською мовою поясніть колегі, що означає ** триаже ** у контексті команди розробників програмного забезпечення і чому наявність спеціального стану триаже відрізняється від простого наявності неприсвоєного відставання.

Національні мови: мова, що використовується для спілкування між ненаціональними групами

Будьмо чесними. Коли ви створюєте інтеграції з API, такими як Linear, особливо коли ваша основна мова не є англійською, тонкі відмінності у фразуваннях можуть здатися неймовірно значущими. Це не просто про те, щоб знати визначення слів; це про розуміння того, як ці слова використовуються в професійному контексті - особливо в технічному спілкуванні. Здається простим запит на «створення проблеми» може перетворитися на дуже різні рівні ясності, залежно від того, чи використовуєте ви прямий імператив, чи більш нюансований опис. У цьому розділі описано деякі типові помилки і запропоновано стратегії для плавнішого і ефективнішого спілкування під час роботи з інтерфейсом Linear API і пов’ язаною з ним термінологією.

Однією з найчастіших проблем є розуміння рівня деталізації, який очікується в документації і повідомленнях про перенесення. Розробники часто за замовчуванням використовують короткі фрази, які відчувають себе цілком прийнятними в їх рідній мові, але можуть бути неправильно інтерпретовані командою, звичною до високоописової англійської мови. Наприклад, просто сказавши « Виправити проблему GraphQL », ви не отримаєте достатньо інформації про те, * чому * її було виправлено або про конкретні зміни, які було внесено. Більш надійним підходом є вписання зміни в ширший контекст проекту і вплив на зацікавлені сторони. Розгляньте використання фраз на кшталт «Основні проблеми з погіршенням продуктивності, що впливають на швидкість завершення циклу» замість цього - надання кількісних даних додає значної ясності. Аналогічно, коли ви пишете описи PR, будьте чіткими щодо * причини * зміни, а не лише * що * ви змінили. Це особливо важливо під час перегляду коду, коли переглядачі мають швидко зрозуміти намір, який стоїть за вашою роботою.

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

І, нарешті, не бійтеся просити про пояснення. Набагато краще визнати, що ви чогось не розумієте, ніж робити припущення, засновані на вашому власному лінгвістичному розумінні. Швидке повідомлення Slack з проханням про докладніше пояснення терміну або фрази може позбавити вас годин розчарування і неправильного спілкування пізніше.

Ось приклад, який показує, як задати запит до API GraphQL Linear для отримання відомостей щодо проблеми, і який показує, які структуровані дані ви можете обговорювати під час інтеграції з платформою:

query GetIssue($issueId: ID!) {
  issue(id: $issueId) {
    id
    title
    description
    status
    assignee {
      name
    }
    comments {
      body
      author {
        name
      }
    }
  }
}

За допомогою цього запиту буде повернуто об’ єкт JSON, у якому містяться всі потрібні відомості щодо проблеми, що надає вам змогу створювати багаті інтеграції і показувати дані у зручному для користувача вигляді. Пам’ ятайте, що чітке спілкування має вирішальне значення — інвестування часу у вдосконалення ваших навичок англійської мови, безсумнівно, принесе дивіденди при роботі з міжнародними командами розробників і складними API, такими як Linear.