Англійська для розробників Automerge

Automerge обробляє дані програми як документ JSON з повними гарантіями об’єднання на основі CRDT і відстеження історії, тому розмови про це змішують словник моделювання даних з тими ж безконфліктними концепціями реплікації, що поширені в екосистемі local-first.

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

** Документ ** — структура даних Automerge, яка представляє весь стан програми (або його частину) як об’ єкт типу JSON, з можливістю відстеження і об’ єднання кожної зміни, замість перезапису однієї змінної точки при кожному збереженні. “Ми не просто перезаписуємо JSON blob при збереженні — документ відстежує кожну окрему зміну, що саме дозволяє об’єднати дві автономні редагування автоматично пізніше.”

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

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

** Історія / подорож у часі ** — можливість перевірити або відтворити будь- який попередній стан документа за допомогою відтворення записаних змін, оскільки нічого не буде перезаписано.

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

** Об’ єднання ** — детермінований процес об’ єднання двох відмінних копій документа (кожна зі змінами, які не було побачено іншою) у єдиний послідовний результат, у більшості випадків без вручну розв’ язання конфлікту.

• “Обидві гілки розходились, коли не було зв’ язку з мережею, але об’ єднання відбувається автоматично, оскільки CRDT Automerge гарантує нам послідовний результат без вручну викликаного кроку конфлікту.” *

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

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

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

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

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

Пояснення моделі новому інженеру:

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

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

Перегляд моделі даних:

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

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

• Підкресліть, що ** документ ** у Automerge — це не просто сховище JSON — це JSON зі стеженням за змінами, і ця відмінність є центральною для пояснення, чому автономне об’ єднання взагалі працює.
• Використовувати гранулярність ** змін ** для зневадження несподіваних об’ єднань — перевірка фактичних записаних змін є набагато продуктивнішою, ніж вгадування того, що « повинно » статися.
• Підсвічування ** історії ** як вбудованого шляху скасування та аудиту, оскільки команди часто не усвідомлюють, що вони отримують цю можливість безкоштовно з моделлю документа, заснованою на CRDT.
• Позначте форми даних на початку перегляду дизайну, які можуть ** погано об’ єднуватися ** під час одночасного редагування — деякі структури (наприклад, неоднозначні переупорядкування масиву) потребують навмисного дизайну, щоб об’ єднання було чистим.

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

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

Переклади: «Переклади» — переклади з англійської мови

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

Однією з поширених областей, де виникають нерозуміння, є обговорення змін, зроблених поза мережею. Уявіть, що ви отримали коментар щодо запиту на збирання, у якому описується зміна у об’ єднанні історії документа: « Це об’ єднання призвело до невідповідностей. Структура даних попередньої версії зараз пошкоджена. “Це твердження, хоча і технічно вірне, може здатися неймовірно тривожним для когось, хто не знайомий з механікою CRDT. Більш доступною формулюванням може бути: “Я помітив деякі відмінності в тому, як цей розділ був редагований офлайн. Ми реалізували механізм, який автоматично обробляє ці типи розбіжних змін - він розроблений для мінімізації перешкод і забезпечення цілісності даних. “Ключ змінюється від опису * проблеми * (пошкодження) до пояснення * рішення * (автоматичне оброблення). Аналогічно, коли ви просите переглянути, сказати «Будь ласка, перевірте цей PR» відчувається неймовірно нечітким. Замість цього, розгляньте « Чи не могли б ви, будь ласка, переглянути цей PR, зосередившись на потенційних конфліктах, що виникають від автономних редагувань і переконатися, що історія документа залишається послідовною? »

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

Нарешті, пам’ ятайте, що розмови Slack часто вимагають коротких, але чітких пояснень. Швидкого повідомлення на зразок « Виправити конфлікт » недостатньо; воно викликає питання: * який * конфлікт? Більш продуктивною відповіддю може бути: «Розв’язано конфлікт, пов’язаний з редагуваннями в автономному режимі — реалізовано стратегію дельта-злиття згідно з узгодженим протоколом команди»

Ось приклад того, як ви можете скористатися git mergetool для ініціалізації вручну об’ єднання з певними параметрами, коли ви маєте справу зі складним конфліктом:

git mergetool --strategy=recursive --no-prompt /path/to/merge_tool

За допомогою цієї команди можна викликати інструмент об’ єднання, вказати стратегію recursive (яка часто підходить для CRDT) і вимкнути автоматичне запитування, що надає вам змогу вручну розв’ язувати конфлікти, якщо вони виникли. Прапорець --no-prompt забезпечує, що інструмент об’ єднання не перерве ваш робочий процес надмірними запитаннями.