7. Внесок у проєкт

Внесок у проєкт cloud-init¶

Вітаємо! Ви пройшли шлях від фундаментальних концепцій «хмарної ініціалізації» до розширених методів забезпечення та усунення несправностей. Тепер ви досвідчений користувач cloud-init. Цей заключний розділ відкриває двері до наступного кроку у вашій подорожі: переходу від споживача cloud-init до потенційного учасника.

cloud-init — це критично важливий проєкт з відкритим кодом, який процвітає завдяки внеску спільноти. Чи то виправлення друкарської помилки в документації, повідомлення про помилку чи написання абсолютно нового модуля, кожен внесок допомагає. У цьому розділі наведено загальну карту для розуміння вихідного коду, створення власного модуля та взаємодії зі спільнотою розробників. Це не вичерпний посібник для розробників, а радше зручний вступ до процесу.

1. Ландшафт вихідного коду `cloud-init`¶

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

Мова та репозиторій¶

Canonical, майже повністю написаний на Python, розміщує репозиторій вихідного коду cloud-init на Launchpad, але для легшої співпраці та більш звичного інтерфейсу більшість учасників взаємодіють з його офіційним дзеркалом на GitHub.

Канонічний репозиторій (Launchpad): https://git.launchpad.net/cloud-init
Дзеркало GitHub: https://github.com/canonical/cloud-init

Щоб отримати вихідний код, ви можете клонувати репозиторій GitHub:

# Clone the source code to your local machine
git clone https://github.com/canonical/cloud-init.git
cd cloud-init

Налаштування середовища розробки¶

Щоб працювати над кодом, не впливаючи на пакети Python вашої системи, завжди використовуйте віртуальне середовище.

# Create a Python virtual environment
python3 -m venv .venv

# Activate the virtual environment
source .venv/bin/activate

# Install the required development dependencies
pip install -r requirements-dev.txt

Огляд вихідного коду на високому рівні¶

Орієнтація в новій кодовій базі може бути складною. Ось найважливіші каталоги:

cloudinit/: Це провідний каталог вихідних кодів Python.
cloudinit/sources/: Цей каталог містить код для Джерел даних (наприклад, DataSourceNoCloud.py). Ось як cloud-init виявляє та зчитує конфігурацію з різних хмарних платформ.
cloudinit/config/: Тут знаходяться Модулі (наприклад, cc_packages.py, cc_users_groups.py). Префікс cc_ – це умовне позначення модулів, що вмикаються за допомогою #cloud-config. Це найпоширеніше місце для внесків у нові функції.
doc/: Офіційна документація проєкту. Покращення документації – один із найкращих способів зробити свій перший внесок.
tests/: Повний набір тестів для проєкту.

2. Написання базового користувацького модуля¶

Хоча runcmd корисний, написання належного модуля — це найкращий спосіб створити конфігурації, які можна використовувати повторно, портативні та ідемпотентні.

Давайте створимо найпростіший можливий модуль: такий, що зчитує ключ конфігурації з user-data та записує повідомлення в журнал cloud-init.

Створення файлу модуля: Створіть новий файл з назвою cloudinit/config/cc_hello_world.py.

# Filename: cloudinit/config/cc_hello_world.py

# A list of frequency and stage for this module to run
frequency = "once-per-instance"
distros = ["all"]

def handle(name, cfg, cloud, log, args):
    # Get a 'message' key from the user-data config.
    # If it doesn't exist, use a default value.
    message = cfg.get("message", "Hello from a custom module!")

    # Write the message to the main cloud-init log.
    log.info(f"Hello World Module says: {message}")

Увімкнути модуль: Створення файлу недостатньо. Ви повинні вказати cloud-init, щоб запустити його. Створіть файл за адресою /etc/cloud/cloud.cfg.d/99-my-modules.cfg та додайте свій модуль до одного зі списків модулів:
```
# Add our custom module to the list of modules that run during the config stage
cloud_config_modules:
  - hello_world
```
Використання модуля: Тепер ви можете використовувати модуль у ваших user-data. Ключ верхнього рівня (hello_world) має відповідати назві модуля без префікса cc_.
```
#cloud-config
hello_world:
  message: "My first custom module is working!"
```

Після завантаження віртуальної машини з цією конфігурацією перевірте /var/log/cloud-init.log, щоб знайти своє власне повідомлення, яке підтверджує роботу вашого модуля.

3. Процес внесення змін¶

Внесок у проект з відкритим кодом відбувається за стандартним робочим процесом. Ось спрощений огляд:

Знайдіть щось, над чим попрацювати: Найкраще почати з відстеження проблем проекту на Launchpad. Шукайте помилки або запити на нові функції. Новачкам рекомендується починати з виправлень документації або проблем, позначених як «легкодоступні» або «гарний перший випуск».
Форк та гілка: Створіть власну копію («форк») репозиторію cloud-init на GitHub. Потім створіть нову гілку для ваших змін.
```
git checkout -b my-documentation-fix
```
Внесіть зміни та зафіксуйте їх: Внесіть зміни до коду або документації. Коли ви берете на себе зобов'язання, напишіть чітке повідомлення з описом того, що ви зробили. Прапорець -s додає рядок Signed-off-by, який засвідчує, що ви написали патч або маєте право його створити.
```
git commit -s -m "Doc: Fix typo in the users module documentation"
```
Включити тести: Усі суттєві внески, особливо нові функції, повинні містити тести. Перегляньте каталог tests/, щоб побачити, як тестуються існуючі модулі.
Надіслати запит на злиття (PR): Надішліть свою гілку до вашого форку на GitHub та відкрийте запит на злиття до гілки main репозиторію canonical/cloud-init. Це ваш офіційний запит на включення вашої роботи до проєкту.
Беріть участь у перевірці коду: Розробники проекту переглянуть ваш запит на реалізацію проекту. Вони можуть ставити запитання або вимагати змін. Це спільний процес. Взаємодія з відгуками є ключовою частиною внеску у розробку відкритого коду.

Залучення спільноти¶

Щоб дізнатися більше, поставити запитання та взаємодіяти зі спільнотою, ви можете приєднатися до каналу #cloud-init в мережі IRC OFTC або до офіційного списку розсилки.

Заключне слово¶

Вітаємо із завершенням цього посібника. Ви пройшли шлях від новачка до досвідченого користувача «хмарної ініціалізації», і тепер у вас є карта, яка проведе вас у світ внеску у відкрите програмне забезпечення. Спільнота cloud-init гостинна та цінує ваш внесок, яким би незначним він не був. Успішної збірки!

Author: Wale Soyinka

Contributors: Steven Spencer, Ganna Zhyrnova