Робочий процес

These instructions assume that you already have a github account and have installed Git as well. Make sure that git is in your PATH by executing the command git in any terminal or cmd and checking that it doesn’t output an error such as “command not found”. If you don’t have git installed, follow these instructions.

🔗Documenting undocumented features

We are particularly interested in documenting closed pull requests that require additions or changes to this manual. Pull requests that require documentation are cataloged with a GitHub label documentation: pending.

Ось основні кроки для цього:

View the list of Pull Requests that need documentation.
Select a Pull Request where you understand what has changed.
Author the change as detailed in the workflow below.
When you make the Pull Request, include a link to the pull request from Step 1.

🔗Робочий процес документації

🔗Одноразове налаштування

Якщо ви ще не налаштували git локально, скористайтеся цими двома командами, щоб налаштувати свою ідентифікацію перед створенням комітів:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

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

Потім ви можете клонувати копію dtdocs на свій комп’ютер.

Перейдіть до https://github.com/darktable-org/dtdocs.
Натисніть кнопку Fork, а потім кнопку Create fork.
Вас буде перенаправлено на сторінку з вашим форком документації Darktable. Натисніть кнопку Code та скопіюйте посилання з HTTPS.
Відкрийте термінал або cmd у потрібному каталозі, де буде знаходитися репозиторій документації Darktable. Щось на кшталт ‘C:\Users\YourUser\Documents' або ‘/home/youruser/Documents/builds’. Як у Windows, так і в macOS/Linux ви можете скористатися командою cd для переходу до потрібного каталогу, замінивши приклад каталогу на ваш.
Клонуйте репозиторій dtdocs, виконавши команду виду: git clone https://github.com/<ваше ім'я користувача на github>/dtdocs.git. URL-адреса тут має бути та, яку ви скопіювали на кроці 3.
Тепер у вас є копія репозиторію dtdocs на вашому ПК. Перш ніж ви зможете розпочати редагування файлів, потрібно буде виконати деякі додаткові налаштування.

🔗Синхронізація змін

Перейдіть до своїх репозиторіїв на github та виберіть ваш форк dtdocs.
Натисніть Sync fork.
Відкрийте термінал або cmd у каталозі вашого репозиторію dtdocs.
Переконайтеся, що у вас немає локальних змін, виконавши git status, а потім виконайте git checkout master (якщо ви вперше виконали цю інструкцію, ви вже будете на master).
Виконайте git pull (це гарантує, що ваша локальна копія оновлена до поточного стану вашого форку на github).

Або ж ви можете синхронізувати свій fork та локальну копію через термінал:

Переконайтеся, що у вас немає локальних змін, виконавши git status, а потім виконайте git checkout master.
Перевірте ваші віддалені репозиторії: git remote -v. Ви повинні побачити принаймні origin (ваш fork). Якщо upstream відсутній, додайте його на наступному кроці.
Додайте репозиторій dtdocs як основний репозиторій (лише один раз): git remote add upstream https://github.com/darktable-org/dtdocs.git.
Витягніть поточний стан з основного репозиторію до вашої локальної копії: git pull upstream master.
Надішліть вашу синхронізовану локальну копію до вашого fork: git push origin master.

🔗Створення гілки, редагування та створення запиту на внесення змін (pull request)

Відкрийте термінал або cmd у каталозі вашого репозиторію dtdocs.
Виконайте git pull origin master, щоб отримати останні зміни з GitHub.
Виконайте git checkout -b branch-name, змінивши branch-name на бажане ім’я гілки. Можна пов’язати це з описом змін, які містить ця гілка. Наприклад, для цього PR https://github.com/darktable-org/darktable/pull/17589 ви можете назвати гілку dt-synch-edit-docs.
Зробіть свій внесок в документацію.
Перевірте змінені файли за допомогою git status. Якщо у вас змінено більше файлів, ніж ви маєте намір надіслати, ви можете виконати git restore path/to/file/, щоб скасувати небажані зміни.
Виконайте git add -A. Це підготує всі змінені файли.
Виконайте git commit -m “Додано документацію для бла-бла-бла”`. Всередині "" ви розмістите невелике повідомлення про суть виконаної роботи.
Виконайте git push --set-upstream origin branch-name. Замініть branch-name на те ім’я гілки, що ви вибрали раніше.
Створіть свій пул-реквест, дотримуючись інструкцій нижче.
Якщо вам потрібно внести подальші виправлення, використовуючи поточну гілку, просто повторіть кроки 3-8. Для команди на кроці 3 ви можете пропустити -b, а на кроці 8 ви можете просто виконати git push.
Після того, як ви закінчите і ваш пул-реквест буде прийнято, або ви завершите роботу над цим конкретним пул-реквестом, виконайте git checkout master, щоб повернутися до гілки master. Краще працювати лише з однією гілкою/пул-реквестом за раз, якщо ви ще не дуже впевнені при роботі з git.

🔗Локальний запуск `hugo` для перегляду змін

Також можна запустити веб-сервер hugo локально для створення локального попереднього перегляду документації. Це корисно для перевірки форматування, посилань тощо.

Виконайте команду hugo server -D --disableFastRender з базового каталогу вашого локального репозиторію. Якщо помилок не виявлено, термінал повідомить: Веб-сервер доступний за адресою http://localhost:1313/usermanual/development/ (адреса прив'язки 127.0.0.1), і сайт має бути доступний за вказаною URL-адресою. Hugo відстежуватиме зміни в каталозі та автоматично повторно розгортатиме файли після їх зміни. Коли у вас відкрито певну сторінку та внесено зміни до відповідного файлу .md, браузер також повинен перезавантажити сторінку.

🔗Пул-реквест (запит на прийняття змін)

Перейдіть на https://github.com/darktable-org/dtdocs/compare
Натисніть compare across forks. Виберіть свій форк репозиторію, а потім гілку, над якою ви щойно працювали.
Натисніть Create pull pequest