Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
284 lines (199 loc) · 10.4 KB

CONTRIBUTING.md

File metadata and controls

284 lines (199 loc) · 10.4 KB

Внесок до CiWiki

Дякуємо за ваш інтерес до внеску у проєкт CiWiki! 🎉

CiWiki є центральним репозиторієм документації та єдиним джерелом правил для всієї екосистеми Cimeika. Ваш внесок допомагає покращити документацію для всіх.

Зміст

Кодекс поведінки

Цей проєкт дотримується Кодексу поведінки учасників. Беручи участь, ви погоджуєтесь дотримуватися його умов.

З чого почати

Перші кроки

  1. Ознайомтесь з документацією

    • Прочитайте README.md
    • Вивчіть COPILOT_CANON.md — основні правила роботи
    • Перегляньте процеси для розуміння робочих процедур

  2. Налаштуйте локальне середовище

    # Клонуйте репозиторій
git clone https://github.com/Ihorog/ciwiki.git
cd ciwiki

# Встановіть залежності
pip install -r requirements.txt
npm install

# Запустіть локальний сервер документації
mkdocs serve

  3. Знайдіть задачу

    • Перегляньте Issues
    • Шукайте мітки good first issue або help wanted
    • Задайте питання в issue перед початком роботи

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

1. Створіть Issue (якщо ще немає)

Перед початком роботи створіть або знайдіть відповідний Issue, щоб:

  • Обговорити запропоновані зміни
  • Уникнути дублювання роботи
  • Отримати зворотний зв'язок від мейнтейнерів

2. Fork та створіть гілку

# Fork репозиторій через GitHub UI

# Клонуйте ваш fork
git clone https://github.com/YOUR-USERNAME/ciwiki.git
cd ciwiki

# Додайте upstream remote
git remote add upstream https://github.com/Ihorog/ciwiki.git

# Створіть гілку для вашої роботи
git checkout -b feature/your-feature-name

3. Внесіть зміни

Важливі принципи:

  • ✅ Мінімальні зміни: Змінюйте тільки те, що необхідно
  • ✅ Антиповторення: Автоматизуйте повторювані дії
  • ✅ Без секретів: Ніколи не комітьте credentials або ключі
  • ✅ Документація: Оновлюйте документацію разом з кодом

4. Тестування

# Перевірте документацію локально
mkdocs serve

# Запустіть тести (якщо є)
npm test
python -m pytest

# Перевірте лінтинг
npm run lint

5. Commit

Дотримуйтесь конвенцій комітів:

# Хороші приклади
git commit -m "docs: оновити інструкції встановлення"
git commit -m "fix: виправити broken link у README"
git commit -m "feat: додати шаблон для bug reports"

# Поганий приклад
git commit -m "updates"
git commit -m "WIP"

6. Push та створіть Pull Request

# Синхронізуйте з upstream
git fetch upstream
git rebase upstream/main

# Push до вашого fork
git push origin feature/your-feature-name

Створіть Pull Request через GitHub UI.

Стандарти коду

Документація (Markdown)

  • Використовуйте чіткі, зрозумілі заголовки
  • Додавайте приклади коду де можливо
  • Перевіряйте орфографію та граматику
  • Використовуйте консистентне форматування

Python

# Використовуйте type hints
def process_data(input: str) -> dict:
    """Обробляє вхідні дані та повертає результат."""
    return {"result": input}

# Дотримуйтесь PEP 8
# Додавайте docstrings

JavaScript

// Використовуйте const/let замість var
const config = {...};

// Додавайте JSDoc коментарі
/**
 * Обробляє конфігурацію
 * @param {Object} config - Об'єкт конфігурації
 * @returns {Object} Оброблена конфігурація
 */
function processConfig(config) {
  return config;
}

Процес Pull Request

Шаблон PR

Використовуйте шаблон PR. Кожен PR повинен містити:

  1. Summary: Що змінено та чому
  2. Scope: Які файли/компоненти змінено
  3. Checklist: Всі обов'язкові перевірки виконані
  4. Notes: Ризики та план відкату

Критерії прийняття

PR буде змерджено якщо:

  • ✅ Всі тести пройшли
  • ✅ CI/CD перевірки успішні
  • ✅ Код review пройдено
  • ✅ Документація оновлена
  • ✅ Немає конфліктів з main
  • ✅ Дотримується принцип мінімальних змін

Процес review

  1. Автоматичні перевірки (CI/CD)

    • Лінтинг
    • Тести
    • Security scanning (CodeQL, Secret Scanning)
    • Documentation build

  2. Code Review

    • Мінімум 1 затвердження від мейнтейнера
    • Всі коментарі розглянуті
    • Conversation resolved

  3. Merge

    • Merge до main після затвердження
    • Автоматичний deploy документації

Звітування про помилки

Перед створенням Bug Report

  • Переконайтесь що issue ще не створений
  • Перевірте чи це не питання документації
  • Спробуйте відтворити проблему

Створення Bug Report

Використовуйте Bug Report template та включіть:

  • Опис: Чіткий опис проблеми
  • Кроки відтворення: Як відтворити баг
  • Очікувана поведінка: Що має працювати
  • Фактична поведінка: Що відбувається насправді
  • Середовище: ОС, версія браузера, тощо
  • Скріншоти: Якщо застосовно

Пропозиції покращень

Feature Requests

Використовуйте Feature Request template:

  • Проблема: Яку проблему розв'язує feature
  • Рішення: Запропоноване рішення
  • Альтернативи: Інші розглянуті варіанти
  • Додатковий контекст: Приклади, use cases

Покращення документації

Документація завжди може бути кращою! Якщо ви знайшли:

  • Неточності або застарілу інформацію
  • Граматичні помилки
  • Відсутню документацію
  • Broken links

Створіть issue або відразу PR з виправленням.

Безпека

НЕ створюйте публічні issues для вразливостей безпеки.

Дотримуйтесь Security Policy:

  1. Використовуйте GitHub Security Advisory
  2. Або повідомте через email
  3. Включіть детальну інформацію про вразливість

Security Best Practices

Перед кожним commit:

  • ✅ Перевірте Security Checklist
  • ✅ Запустіть npm audit та pip-audit
  • ✅ Переконайтесь що немає секретів в коді
  • ✅ Дотримуйтесь Copilot Guard Policy

Security Resources

Питання?

Ліцензія

Роблячи внесок до цього репозиторію, ви погоджуєтесь що ваш внесок буде ліцензований згідно з MIT License проєкту.

Подяки

Дякуємо всім, хто вносить внесок до CiWiki! 💙💛

Ваші зусилля роблять цю документацію кращою для всієї спільноти Cimeika.

Пам'ятайте: Якщо у вас є питання, не соромтесь запитувати. Ми тут, щоб допомогти! 🚀