Найкращі практики

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

Вступ

Для більшої кількості інформації про Git, або GitHub перегляньте Документацію GitHub

Git — це система контролю версій, яка допомагає керувати змінами файлів. Дані та історія змін osu! wiki зберігаються в Git репозиторії. GitHub — це платформа для розробників, яка надає веб інтерфейс для Git репозиторіїв, а також має в собі набір інструментів для керування проектом.

Синхронізація форку

Щоб внести зміни до репозиторію, який знаходиться на GitHub, потенційний учасник повинен отримати його контрольовану копію, яка називається форк. Коли ви створюєте форк репозиторію osu-wiki, в цей момент ви робите копію його вмісту. Перед внесенням змін завжди синхронізуйте ваш форк, щоб вони мали сенс. Це може бути зроблено напряму через GitHub:

1. Перейдіть у ваш форк репозиторію osu-wiki.

2. Оберіть гілку master з випадаючого меню.

3. Натисніть Fetch upstream, а потім оберіть Fetch and merge.

   Оновлення застарілої гілки

Тепер ваша гілка актуальна по відношенню до оригінального репозиторію.

Це рішення працює добре у більшості випадків, але цей інструмент сам по собі має обмежені можливості. Наприклад, він не дозволяє вам перезаписувати будь-які небажані зміни на гілці, оскільки він об'єднує лише основну гілку master.

Якщо ви зіткнулися з будь-якими проблемами при використанні інструментів GitHub, або ви хочете перезаписати вміст вашої гілки, ви можете використати workflow написаний учасниками osu! wiki.

1. Відкрийте ваш форк і перейдіть до вкладки Actions.

2. У Workflows, знайдіть Sync from osu! upstream.

3. Натисніть Run workflow і заповніть опції:

   GitHub Actions Workflow - Запуск Workflow

   • Use workflow from: назва гілки, яку ви бажаєте синхронізувати. За замовчуванням вона виставлена як master.
   • Overwrite any changes in the target repository:

     • true: замінити вміст вашої гілки чистою копією гілки master з ppy/osu-wiki.
     • false (за замовчуванням): об'єднати ваші зміни зі змінами на ppy/osu-wiki.
   • Create a backup of your target branch:

     • true: створити гілку з назвою backup-{назва вашої гілки} перед її зміною.
     • false (за замовчуванням): не робити ніяких резервних копій.

4. Натисніть кнопку Run Workflow і зачекайте поки workflow зробить все необхідне. Якщо вам цікаво як це працює, натисніть на завдання workflow — Sync from osu! upstream.

   GitHub Actions Workflow - Огляд Workflow

Внесення змін

Перегляньте також: Форк Workflow | Git Туторіал від Atlassian

В середині вашого форку osu! wiki, ви можете робити будь-які зміни і зебрігати їх. Коміти — це індивідуальні "точки збереження" репозиторію. Гілки — робочі середовища, які дозволяють вам переходити між багатьма версіями репозиторію. Щоб спростити ваш процес роботи і підтримувати історію wiki чистою і без зайвих речей, дотримуйтеся наступних рекомендацій:

• Синхронізуйте гілку master.
• Завжди починайте роботу створивши нову гілку від master і тримайте ваші зміни там. Дайте цій гілці змістовне ім'я, наприклад update-stuff-log.
• Робіть коміт коли ви внесли зміни розміру який має сенс. Краще додати в коміт статтю повністю, ніж 10 маленьких окремих правок.
• Використовуйте короткі і змістовні повідомлення комітів, оскільки вони говорять іншим про те що було зроблено. Щось накштал Rewrite the section about jump patterns говорить набагто більше ніж Update en.md.

Відкриття пул реквесту

Пул реквест показує іншим людям як ваші зміни вплинуть на файли. Напишіть додаткову інформацію до вашого пул реквесту, щоб пояснити ваші наміри:

• Заголовок: дуже короткий заголовок, який описує ваші зміни англійською, разом з назвою статті. У випадку перекладу, починайте заголовок з двох літер, які вказують назву мови вашого перекладу в квадратних дужках. Наприклад:

  • [UK] Add `BBCode`
  • Update `Beatmapping` and `Beatmap/Difficulty`
• Опис: що завгодно, що би ви хотіли сказати мейнтейнерам, або іншим потенційним рев'юверам. Наприклад:

  • Короткий підсумок змін, особливо якщо вони стосуються кількох статтей
  • Наскільки пул реквест завершенний, або ідеї пов'язані з ним
  • Автоматичне вирішення актуальних проблем
• Переконайтеся, що ви відмітили чекбокс Allow edits from maintainers, оскільки це дозволяє мейнтейнерам покращити ваш пул реквест коли це необхідно.

Застосування оглядів

Огляди найкраще застосовувати напряму через веб інтерфейс GitHub. Натисніть кнопку Add suggestion to batch, коли знаходитеся у вкладці Files changed, щоб застосувати декілька оглядів одночасно.

Ви також можете використовувати кнопку Commit suggestion для застосування однієї поради окремо, за умови що ви робите коміти економно і з інформативними повідомленнями.

Використовуючи це, система буде автоматично відмічати поради як вирішенні. У разі застосування порад вручну (наприклад, коли оглядач не дав прямої поради), помічайте їх як "вирішені" після внесення змін, щоб нічого не забути. Дозволити GitHub застосовувати огляди автоматично є найкращим варіантом, оскільки можна бути впевненим, що поради були застосовані коректно, а також уникнути будь-яких помилок через ручне копіювання.

Вирішення конфліктів

Існує дві причини чому може виникнути конфлікт:

• Ви відредагували файл, тоді коли гілка була застаріла.
• Була відсутність комунікації між вами та іншою людиною, тому ви обоє редагували ту саму статтю. Зміни іншої людини були об'єднанні перед вашими, через що ваші відредаговані файли стали застарілими.

В залежності від серйозності конфліктів, у вас є два варіанти як це виправити:

1. Якщо ваш пул реквест має кнопку Resolve conflicts, натисніть її. Ця дія відкриє злегка іншу версію веб редактора.

   1. GitHub буде виділяти конфліктні області. Знайдіть одну з них.
   2. Все починаючи від <<<<<<< і до ======= це ваші зміни, в той час як, все від ======= до >>>>>>> masterце те, що знаходться на гілці ppy/master.
   3. Починаючи звідси, вам потрібно буде власноруч вирішити конфлікт та видалити рядки з помітками <<<<<<<, =======, і >>>>>>> master.
   4. Повторіть цей процес для всіх конфліктів.
   5. Як закінчите, натисніть Mark as resolved (ця опція доступна лише тоді, коли всі конфліктні частини файлу вирішені).
2. Якщо кнопка Resolve conflicts заблокована через те, що конфлікти надто складні для GitHub — вам не повезло, і вам потрібно оновити вашу гілку та зробити ваші зміни знову.

   • Зауважте: Це правда лише якщо ви обмежені використанням веб інтерфейсу GitHub. Існують певні шляхи вирішення такої проблеми, але вони не підлягають під ціль цієї статті. Крім того, це ймовірно не вартує таких зусиль, оскільки ви перезапишите та повернете конфліктні зміни.