# Шпаргалка для контриб'юторів Kubernetes

Список загальних джерел для контриб'юторів Kubernetes, корисні поради, прийоми та найкращі практики, що застосовуються у Kubernetes. Це "TL;DR", або стислий довідник корисної інформації, що має на меті покращити ваш досвід контриб'ютора на GitHub.

**Зміст**

- [Шпаргалка для контриб'юторів Kubernetes](#шпаргалка-для-контрибюторів-kubernetes)
  - [Корисні джерела](#корисні-джерела)
    - [Початок роботи](#початок-роботи)
    - [SIGs та інші групи](#sigs-та-інші-групи)
    - [Спільнота](#спільнота)
    - [Робочий процес](#робочий-процес)
    - [Тести](#тести)
    - [Важливі поштові адреси](#важливі-поштові-адреси)
    - [Інші корисні посилання](#інші-корисні-посилання)
  - [Ефективне спілкування в GitHub](#ефективне-спілкування-в-github)
    - [Як бути найкращими одне для одного](#як-бути-найкращими-одне-для-одного)
      - [Приклади хорошого/поганого спілкування](#приклади-хорошогопоганого-спілкування)
  - [Внесок до проекту](#внесок-до-проекту)
    - [Підписання CLA](#підписання-cla)
    - [Відкрити та відреагувати на Issue](#відкрити-та-відреагувати-на-issue)
      - [Створення Issue](#створення-issue)
      - [Реакція на Issue](#реакція-на-issue)
    - [Відкрити Pull Request](#відкрити-pull-request)
      - [Створення Pull Request](#створення-pull-request)
      - [Приклад опису PR](#приклад-опису-pr)
      - [Усунення помилок у Pull Request](#усунення-помилок-у-pull-request)
    - [Мітки](#мітки)
  - [Робота локально](#робота-локально)
    - [Стратегія галуження](#стратегія-галуження)
      - [Додання Upstream](#додання-upstream)
      - [Синхронізація вашого відгалуження (fork)](#синхронізація-вашого-відгалуження-fork)
      - [Об’єднання комітів (squashing commits)](#обєднання-комітів-squashing-commits)

---

## Корисні джерела

### Початок роботи

- [Керівництво для контриб'юторів] - З чого почати свій внесок до проекту Kubernetes.
- [Керівництво для розробників] - Як зробити свій внесок безпосередньо у код проекту Kubernetes.
- [Безпека і розкриття інформації] - Інструкція з питань виявлення вразливостей і безпеки релізу.

### SIGs та інші групи

- [Список основних груп][sigs]

### Спільнота

- [Календар] - Перегляд усіх подій спільноти Kubernetes (зустрічі SIG та робочих груп, події, тощо)
- [kubernetes-dev] - Поштова розсилка для розробників Kubernetes.
- [Kubernetes форум] - Офіційний форум Kubernetes.
- [Канали Slack] - Офіційний Slack Kubernetes.
- [Stack Overflow] - Платформа, де кінцеві користувачі Kubernetes можуть ставити свої запитання.
- [YouTube канал] - Офіційний канал спільноти Kubernetes.

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

- [Gubernator Dashboard] - Перегляд вхідних та вихідних Pull Request, що потребують вашої уваги.
- [Prow] - Kubernetes CI/CD система.
- [Tide] - Prow плаґін для управління процесом злиття змін до основної гілки репозиторія (merge) і тестами. [Tide Dashboard]
- [Команди бота] - Команди для взаємодії з ботами Kubernetes (наприклад:
  `/cc`, `/lgtm` і `/retest`)
- [GitHub мітки] - Список міток, які використовуються в проекті Kubernetes
- [Пошук у коді Kubernetes], за підтримки [@dims]

### Тести

- [Prow] - Kubernetes CI/CD система.
- [Test Grid] - Перегляд історії тестів та дотичної до них інформації.
- [Triage Dashboard] - Агрегування схожих помилок для їх кращого виправлення.

### Важливі поштові адреси

- community@kubernetes.io - Написати листа комусь із команди спільноти (SIG Contributor
  Experience) щодо непорозумінь у спільноті.
- conduct@kubernetes.io - Написати листа до Комітету з контролю поведінки в Kubernetes, приватна розсилка.
- github@kubernetes.io - Надіслати приватного листа до [Адміністративної команди GitHub] з приводу чутливих питань.
- steering@kubernetes.io - Надіслати листа до комітету управління. Загальнодоступна адреса із публічним архівом.
- steering-private@kubernetes.io - Надіслати листа до комітету управління у приватному порядку, з приводу чутливих питань.
- social@cncf.io - Зв’язатися із командою соціальних мереж CNCF; блог, Twitter акаунт, решта соціальних сервісів.

### Інші корисні посилання

- [Developer Statistics] - Переглянути статистику розробки за всіма проектами CNCF.
- [Kubernetes Patch Release] Розклад патч-релізів Kubernetes і контактна інформація команди.

---

## Ефективне спілкування в GitHub

### Як бути найкращими одне для одного

Насамперед, ознайомтеся із [Кодексом поведінки Спільноти].

#### Приклади хорошого/поганого спілкування

Коли ви про щось питаєте чи шукаєте допомоги, будь ласка, будьте ввічливі:

  🙂 “X не компілюється, коли я роблю Y. Є якісь припущення?”

  😞 “X не працює! Будь ласка, виправіть це!”

Якщо ви відхиляєте PR, будь ласка, надайте інформативне та доброзичливе пояснення, чому запропоновані зміни не можуть бути об'єднані з основною гілкою (merged).

🙂 “Я відхиляю цей PR тому, що ця функціональність не може підтримувати сценарій використання X. У запропонованій формі її краще реалізувати з інструментом Y. Дякую за вашу роботу.”

😞 “Чому це не узгоджується з домовленостями щодо API? Це має бути зроблене в іншому місці!”

---

## Внесок до проекту

### Підписання CLA

Перш ніж зробити свій внесок, ви повинні [підписати Ліцензійну угоду учасника (CLA)][cla]. Ваш внесок до проекту Kubernetes може бути прийнято _лише_ за умови, що ви чи ваша компанія підписали CLA.

Якщо у вас виникли труднощі із підписанням CLA, дотримуйтесь рекомендацій [інструкції з вирішення проблем CLA].

### Відкрити та відреагувати на Issue

GitHub Issue є основним джерелом для відстеження інформації з таких питань, як звіти про помилки, запити на вдосконалення, або для повідомлень, наприклад, про невдалі тести. Вони **не** призначені для [підтримки користувачів]. Для цього скористайтеся
[інструкцією із усунення несправностей], повідомте про проблему до [Stack Overflow] чи [Kubernetes форум].

**Посилання:**

- [Мітки]
- [Команди Prow][commands]

#### Створення Issue

- Скористайтеся шаблоном issue, якщо такий є. Використання відповідного шаблона допоможе іншим учасникам, які відповідатимуть на ваш запит.
  - Дотримуйтесь рекомендацій, наведених у самому шаблоні.
- Детально опишіть питання, з яким звертаєтесь.
- Проставте відповідні [мітки]. Якщо ви не впевнені, бот [k8s-ci-robot][prow]
  ([Kubernetes CI bot][prow]) відповість на ваш issue і запропонує мітки, необхідні для пріоритизації вашого питання.
- Дотримуйтесь вибірковості, коли за допомогою [`/assign @<username>`][assign] або
  [`/cc @<username>`][cc] залучаєте до роботи над вашим питанням інших осіб. Використання правильних міток є набагато ефективнішим для пріоритизації вашого запиту, аніж залучення більшої кількості учасників.

#### Реакція на Issue

- Якщо ви починаєте роботу над якимось запитом (issue), залиште про це коментар. Так інші учасники знатимуть, над чим ви працюєте, і не робитимуть подвійної роботи.
- Якщо ви самостійно розв’язали якесь питання, залиште коментар по цьому запиту, а вже потім закривайте його.
- Долучайте посилання на PR, інші запити (issues) чи будь-які інші наявні матеріали, наприклад: _"ref: #1234"_. Доцільно зазначити, що роботи з даного питання вже велися деінде.

### Відкрити Pull Request

Pull request (PR) є основним засобом, за допомогою якого відбувається додання коду, документації чи іншого доробку до Git-репозиторія.

**Посилання:**

- [Мітки]
- [Команди Prow][commands]
- [Процес pull request]
- [Робочий процес у GitHub]

#### Створення Pull Request

- Дотримуйтесь рекомендацій, наведених у шаблоні pull request, якщо такий є. Це допоможе іншим учасникам, які відповідатимуть на ваш PR.
- У випадку [незначних виправлень], як-от неробоче посилання, друкарська або граматична помилка, перегляньте весь документ на предмет інших потенційних помилок. Не відкривайте численних PR для невеликих виправлень у тому самому документі.
- Посилайтеся на будь-які запити (issue), що стосуються вашого PR, або такі, які цей PR може вирішити.
- Уникайте завеликої кількості змін в одному коміті. Натомість розбийте ваш PR на декілька невеликих, логічно зв’язаних комітів. Цим ви полегшите перевірку вашого PR.
- Лишайте коментарі до свого PR щоразу, як вважаєте за потрібне пояснити щось детальніше.
- Дотримуйтесь вибірковості, коли за допомогою [`/assign @<username>`][assign] залучаєте до роботи над вашим PR інших осіб. Надмірна кількість рецензентів не пришвидшить перевірки вашого PR.
- Якщо ваш PR _"у роботі"_ (_"Work in progress"_), додайте до його назви префікс `[WIP]`
  або використайте команду [`/hold`][hold]. Наявність`[WIP]` або hold дозволить уникнути автоматичного злиття змін (merge).
- Якщо ваш PR не перевірили, не потрібно закривати його і відкривати новий із тими самими змінами. Зверніться до своїх рецензентів у коментарі, скориставшись `@<github username>`.
- Якщо вашому PR не приділяється достатньої уваги, опублікуйте посилання на PR у Slack-каналі `#pr-reviews` для того, щоб знайти додаткових рецензентів.

#### Приклад опису PR

```
Ref. #3064 #3097
Всі файли, що належать SIG testing, були переміщені із `/devel` до нової директорії `/devel/sig-testing`.

/sig contributor-experience
/cc @stakeholder1 @stakeholder2
/kind cleanup
/area developer-guide
/assign @approver1 @approver2 @approver3
```

Що в цьому PR:

- **Рядок 1** - Посилання на інші issue або PR (#3064 #3097).
- **Рядок 2** - Стислий опис того, що було зроблено в PR.
- **Рядок 4** - [Команда][commands]
  `/sig contributor-experience` визначає дотичну до PR [SIG][sigs].
- **Рядок 5** - Команда [`/cc`][cc] визначає рецензентів, яких може зацікавити цей issue або PR.
- **Рядок 6** - Команда [`/kind cleanup`][kind] додає [мітку][мітки], що характеризує issue або PR як такий, що стосується чистки коду, процесу або технічного боргу.
- **Рядок 7** - Команда [`/area developer-guide`][kind] характеризує issue або PR як такий, що має відношення до керівництва для розробників.
- **Рядок 8** - Команда [`/assign`][assign] визначає погоджувача (approver) PR.
  Погоджувач обирається ботом [k8s-ci-robot][prow] зі списку відповідальних осіб, що міститься у файлі [OWNERS]. Після перевірки PR вони додадуть до нього мітку
  [`/approve`][approve].

#### Усунення помилок у Pull Request

Після того, як ви зробили запит на прийняття змін, Kubernetes CI-платформа [Prow] виконує ряд тестів. У разі, якщо хоча б один із тестів завершився невдало, бот [k8s-ci-robot][prow] опублікує посилання на невдалі тести і наявні логи у відповіді на PR.

Додання нових комітів у ваш PR автоматично перезапускає тести.

Інколи можуть виникнути складнощі у роботі Kubernetes CI-платформи. Це може статися з багатьох причин, навіть якщо ваш код успішно пройшов локальні тести. Ви можете перезапустити тести командою `/retest`.

Детальніше про вирішення проблем, пов’язаних із певними тестами, дивіться в [керівництві з тестування].

### Мітки

Kubernetes використовує [мітки] для розподілу Issues та Pull Requests за категоріями та для визначення пріоритетності їх виконання. Використання відповідних міток сприятиме ефективній пріоритизації вашого issue чи PR.

**Посилання:**

- [Мітки]
- [Команди Prow][commands]

Часто використовувані мітки:

- [`/sig <sig name>`][kind] Призначити [SIG][SIGs] відповідальною за issue чи PR.
- [`/area <area name>`][kind] Віднести issue чи PR до певної
  [зони][мітки].
- [`/kind <category>`][kind] Віднести issue чи PR до певної [категорії][мітки].

---

## Робота локально

Перш ніж зробити PR, вам необхідно виконати певний рівень роботи локально. Якщо ви раніше не працювали із git, [git-посібник Atlassian] стане хорошою точкою для старту. Гарною альтернативою йому буде стенфордський багатомовний посібник [Git magic].

**Посилання:**

- [Git-посібник Atlassian]
- [Git magic]
- [Робочий процес у GitHub]
- [Тестування локально]
- [Керівництво для розробників]

### Стратегія галуження

Проект Kubernetes використовує стандартний для GitHub робочий процес _"Fork and Pull"_ (створення відгалуження від проекту і отримання останніх змін із віддаленого репозиторія проекту). У термінології git ваше особисте відгалуження називатиметься _"`origin`"_, а фактичний git-репозиторій проекту - _"`upstream`"_. Для того, щоб підтримувати синхронізацію вашої особистої гілки (`origin`) із гілкою проекту (`upstream`), налаштуйте конфігурацію у вашій локальній копії.

#### Додання Upstream

Додайте `upstream` як віддалений репозиторій і налаштуйте таким чином, щоб ви не могли відправити до нього зміни.

```bash
# замініть <upstream git repo> на url upstream-репозиторія
# наприклад:
#  https://github.com/kubernetes/kubernetes.git
#  git@github.com/kubernetes/kubernetes.git

git remote add upstream <upstream git repo>
git remote set-url --push upstream no_push
```

Для перевірки запустіть команду `git remote -v` , яка видасть перелік віддалених репозиторіїв, які у вас налаштовані.

#### Синхронізація вашого відгалуження (fork)

Отримайте останні зміни з основного репозиторія `upstream` і _"перебазуйте"_ їх у вашу локальну гілку `master`. Це синхронізує ваш локальний репозиторій із основним репозиторієм проекту (`upstream`). Відправте локальні зміни до своєї віддаленої мастер-гілки (`remote master`).

```bash
git fetch upstream
git checkout master
git rebase upstream/master
git push
```

Це - необхідний мінімум для створення нової гілки, у якій ви працюватимете над розробкою функціональності чи виправленням помилок.

```bash
git checkout -b myfeature
```

#### Об’єднання комітів (Squashing Commits)

[Об’єднання комітів] використовується для створення чіткої та зрозумілої історії git-комітів або журналу внесених змін. Зазвичай це роблять на останньому етапі перевірки PR. Якщо ви не впевнені, чи потрібно вам об’єднувати коміти, краще помилитись і лишити їх як є. Це питання вирішуватимуть учасники, які перевірятимуть та погоджуватимуть ваш PR.


[Керівництво для контриб'юторів]: /contributors/guide/README.md
[Керівництво для розробників]: /contributors/devel/README.md
[gubernator dashboard]: https://gubernator.k8s.io/pr
[prow]: https://prow.k8s.io
[tide]: http://git.k8s.io/test-infra/prow/cmd/tide/pr-authors.md
[tide dashboard]: https://prow.k8s.io/tide
[Команди бота]: https://go.k8s.io/bot-commands
[GitHub мітки]: https://go.k8s.io/github-labels
[Пошук у коді Kubernetes]: https://cs.k8s.io/
[@dims]: https://github.com/dims
[Календар]: https://calendar.google.com/calendar/embed?src=calendar%40kubernetes.io
[kubernetes-dev]: https://groups.google.com/forum/#!forum/kubernetes-dev
[Канали Slack]: http://slack.k8s.io/
[Stack Overflow]: https://stackoverflow.com/questions/tagged/kubernetes
[youtube канал]: https://www.youtube.com/c/KubernetesCommunity/
[triage dashboard]: https://go.k8s.io/triage
[test grid]: https://testgrid.k8s.io
[developer statistics]: https://k8s.devstats.cncf.io
[Кодексом поведінки Спільноти]: /code-of-conduct.md
[підтримки користувачів]: /contributors/guide/issue-triage.md#determine-if-its-a-support-request
[інструкцією із усунення несправностей]: https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/
[Kubernetes форум]: https://discuss.kubernetes.io/
[Процес pull request]: /contributors/guide/pull-requests.md
[Робочий процес у github]: /contributors/guide/github-workflow.md
[prow]: https://git.k8s.io/test-infra/prow#prow
[cla]: /CLA.md#how-do-i-sign
[інструкції з вирішення проблем CLA]: /CLA.md#troubleshooting
[commands]: https://prow.k8s.io/command-help
[kind]: https://prow.k8s.io/command-help#kind
[cc]: https://prow.k8s.io/command-help#cc
[hold]: https://prow.k8s.io/command-help#hold
[assign]: https://prow.k8s.io/command-help#assign
[SIGs]: /sig-list.md
[керівництві з тестування]: /contributors/devel/sig-testing/testing.md
[Мітки]: https://git.k8s.io/test-infra/label_sync/labels.md
[незначних виправлень]: /contributors/guide/pull-requests.md#10-trivial-edits
[Робочий процес у GitHub]: /contributors/guide/github-workflow.md#3-branch
[Об’єднання комітів]: /contributors/guide/pull-requests.md#6-squashing-and-commit-titles
[owners]: /contributors/guide/owners.md
[Тестування локально]: /contributors/guide/README.md#testing
[git-посібник Atlassian]: https://www.atlassian.com/git/tutorials
[git magic]: http://www-cs-students.stanford.edu/~blynn/gitmagic/
[Безпека і розкриття інформації]: https://kubernetes.io/docs/reference/issues-security/security/
[approve]: https://prow.k8s.io/command-help#approve
[Адміністративної команди GitHub]: /github-management#github-administration-team
[Kubernetes Patch Release]: https://github.com/kubernetes/sig-release/blob/master/releases/patch-releases.md