Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/alei1180/open-source-contributor-guide

Open Source Contributor Guide. Руководство для контрибьюторов в проекты с открытым исходным кодом.
https://github.com/alei1180/open-source-contributor-guide

1c 1c-enterprise bsl contributor github guide hacktoberfest open-source opensource

Last synced: about 2 months ago
JSON representation

Open Source Contributor Guide. Руководство для контрибьюторов в проекты с открытым исходным кодом.

Awesome Lists containing this project

README 

          
![](img/oscg-logo-readme.png)



# Руководство для контрибьюторов в проекты с открытым исходным кодом



Пошаговое руководство для желающих внести свои изменения в открытый проект и правильно оформить запрос на слияние (`Pull Request`).



## Зависимости



* Скачать и установить [git](https://git-scm.com/downloads) под вашу ОС



## Минимальная настройка git для работы



* Установить Имя автора, от которого будут совершаться изменения



  ```shell

  git config --global user.name "Ivan Ivanov"

  ```



* Установить email, от которого будут совершаться изменения



  ```shell

  git config --global user.email ivan-ivanov@gmail.com

  ```



* Установить имя интеграционной ветки по умолчанию



  ```shell

  git config --global init.defaultBranch main

  ```



* Установить настройку корректного отображения кириллицы в путях



  ```shell

  git config --global core.quotePath false

  ```



* При необходимости изменить редактор по умолчанию вместо стандартного редактора `vim`, на тот который вам по душе (редактор используется для ввода сообщений коммитов)



  ```shell

  git config --global core.editor code

  ```



* Посмотреть текущие настройки `git`



  ```shell

  git config --list --show-origin

  ```



## Найдите проект на GitHub



* Найти интересущий вас проект на [GitHub](https://github.com/)

* Изучить документацию проекта и правила по его доработке (если таковые есть)



## Создайте issue под задачу



> Каждая новая функция или исправление бага должны быть привязаны к `issue` (задаче, тикету). Это помогает организовать работу в одном месте: там можно найти всю историю запросов на слияние (`Pull Request`), комментарии участников и принять участие в обсуждении задачи.



* В оригинальном проекте автора на `GitHub` зайти в раздел `issue`

* Убедиться, что под задачу, над которой вы собираетесь работать есть `issue`

* Если `issue` существует - убедиться, что никто не взял его в работу

* Если `issue` не существует - создать, перед этим ознакомится с кратким руководством [GitHub issues](https://docs.github.com/ru/issues/tracking-your-work-with-issues/configuring-issues/quickstart/)

* Оставить комментарий, чтобы другие участники знали, что вы работаете над этой задачей



## Сделайте Fork репозитория проекта



> `Fork` - это не команда `Git`, это функция хостингов репозитория (например `GitHub`). `Fork` делает копию проекта из профиля автора в ваш профиль. При этом адрес репозитория,  в который вы будете вносить доработки физически меняется - он теперь в вашем профиле. Эта технология позволяет легко производить доработки проекта, отправляя их затем в ваши форк-репозитория, так как вам не потребуется запрашивать права, чтобы внести изменения в оригинальный репозиторий автора.



* В оригинальном репозитории автора в правом верхнем углу страницы нажать на меню `Fork` и выбрать `Create a new fork`



Если форк репозитория уже был создан ранее перейдите к следующему шагу.



## Синхронизируйте Fork из веб интерфейса GitHub



> Синхронизировать ваш fork-репозиторий необходимо чтобы поддерживать его в актуальном состоянии относительно оригинального репозитория автора. Синхронизируя fork-репозиторий мы догоняем по изменениям оригинальный репозиторий проекта.



* Из своего профиля на `GitHub` перейдите к `fork-репозиторию`, который вы создали на прошлом шаге

* Над списком файлов нажмите на меню `Sync fork` затем `Update branch`

* Если синхронизация выполнена успешно или `fork-репозиторий` содержит последние изменения из оригинальногое репозитория, то при последующем нажатии на `Sync fork` вы увидите надпись `This branch is not behind the upstream`



## Склонируйте Fork на локальную машину



> Клонирование на локальную машину необходимо для непосредственного внесения доработок по вашей задаче (`issue`)



* В вашем `fork-репозитрии` на `GitHub` нажмите на кнопку `Code` (находится над кнопкой `Sync fork`) и скопируйте ссылку на закладке `HTTPS`, обычно она имеет вид `https://github.com/ваш-профиль/форк-репозиторий.git`

* Откройте консоль на вашей локальной машине

* Перейдите в папку где хранятся (или планируете хранить) `git` проекты

* Склонируйте `fork-репозиторий` с помощью команды



  ```shell

  git clone https://github.com/ваш-профиль/fork-репозиторий.git

  ```



* При успешном клонировании вы увидите созданную директорию с названием проекта



Если клон репозитория уже был создан ранее перейти к следующему шагу.



## Создайте функциональную ветку под задачу в локальном репозитории



> Ветки позволяют разработчику сохранять разные изменения полностью независимо друг от друга. Вы можете работать над разными вещами одновременно, не смешивая изменения между собой. Ветка отражает историю коммитов. Ветки - это разные истории коммитов. Ветка - это просто ссылка на коммит по его ID, эта ссылка каждый раз обновляется когда вы делаете новый коммит. В любой момент времени можно создать новую ветку, переключиться между ветками, отказаться от ветки (т.е. отказаться от всей работы, которую вы в неё вложили), объединить ветки.



* Перейти в рабочий каталог (локальный репозиторий)



  ```shell

  cd projects/название-склонированного-репозитрия

  ```



* Переключиться на ветку `main`



  ```shell

  git checkout main

  ```



* Догнать в локальном репозитории изменения `fork-репозитория`



  ```shell

  git pull

  ```



* Создать локальную ветку под задачу



  ```shell

  git checkout -b feat/37/issue-name

  ```



  * `feat` - тип коммита ([соглашение о коммитах](https://www.conventionalcommits.org/ru/v1.0.0/))

  * `37` - номер задачи `issue` в основном репозитории проекта на `GitHub`, позволяет при использовании команды `git status` сразу держать его перед глазами не тратя времени на поиски задачи

  * `issue-name` - наименование задачи, обычно просто берется название задачи (`issue`) на `GitHub` переводится в нижний регистр, пробелы заменяются на дефисы и осталвяют только значимые слова. Помните давая четкое, но краткое описание задачи, вы облегчаете себе понимание о чем это задача, или на каком моменте вы остановились, переключаясь между ветками



## Внесите изменения в локальный репозиторий по задаче



* Напишите код, который решает вашу задачу

* Проверьте, что ваш код работает и ничего не ломает (проведите unit-тестирование)

* При необходимости дополните документацию проекта описывающую ваши изменения



## Добавьте ваши изменения по задаче в локальном репозитории в индекс



> Команда `git add` создаёт копию файла, помещает его в индекс (специальную область для временного хранения данных) и начинает отслеживать все последующие изменения. Файлу присваивается статус "подготовленный" (`staged`), что означает его готовность к фиксации в коммите. Индекс можно сравнить с черновиком, где вы можете вносить правки до момента, пока не решите зафиксировать изменения. Каждый зафиксированный коммит сохраняет состояние файлов таким, каким оно было на момент добавления в индекс.



* После изменений проверьте состояние вашего репозитория, и убедитесь что изменения коснулись только файлов над которыми вы работали



  ```shell

  git status

  ```



* При необходимости посмотрите детали по вашим изменениям (разницу между текущим состоянием репозитория и последним коммитом)



  ```shell

  git diff

  ```



* Добавьте изменения в индекс



  ```shell

  git add file-1 file-2

  ```



  * Можно добавить все измененные файлы в индекс в текущей директории без ручного перечисления командой `git add .`



## Зафиксируйте ваши изменения по задаче в локальном репозитории



> Команда `git commit` фиксирует все изменения в файлах, предварительно добавленных в индекс (`git add`), сохраняя их в объектной базе `Git` и помечая как неизменяемые. Каждый коммит представляет собой фиксацию состояния файлов на определённый момент времени. По сути, коммит — это снимок всех изменений, которые были включены в индекс. Он сохраняет состояние индекса в тот момент, когда вы решили зафиксировать изменения. Важно сопровождать коммит пояснительным сообщением, описывающим внесённые изменения. В процессе создания коммита формируется объект, который содержит метаданные, такие как ссылка на зафиксированные файлы, имя и электронная почта автора, временная метка коммита и текстовое сообщение.



* Проверьте состояния репозитория после добавления измененных файлов в индекс, текст вывода должен содержать сообщение `Changes to be commited` под которым будет список файлов, которые были добавлены в индекс



  ```shell

  git status

  ```



* Зафиксируйте (`commit`) изменения



  ```shell

  git commit

  ```



* После ввода команды откроется встроенный редактор для редактирования сообщения коммита

* Введите сообщение коммита



  ```shell

  feat: добавить обработчик редактирования текста (#37)

  ```

  

  * `feat` - тип коммита ([соглашение о коммитах](https://www.conventionalcommits.org/ru/v1.0.0/))

  * `37` - номер задачи `issue` в основном репозитории, необходимо чтобы привязать коммит к `issue` на `GitHub`



> #### Правила написания хороших сообщений коммитов

>

> * Всегда пишите осмысленные сообщения коммитов, это позволит вам легко понять цель внесённых изменений, если в будущем потребуется вернуться к этому коммиту в истории проекта

> * Рекомендуется использовать повелительное наклонение в сообщениях коммитов. Вместо фраз вроде "обновлена документация проекта" или "исправлена ошибка авторизации", формулируйте сообщения так, будто вы даёте команду компьютеру. Например, напишите "обновить документацию проекта" или "исправить ошибку авторизации".

> * Используйте команду `git commit` без флага `-m` и каких либо флагов вообще - это вызовет открытие вашего редактора для сообщения коммита по умолчанию, где вы можете написать осмысленное хорошее сообщение коммита. Плюс данного подхода так же в том, что в редакторе можно вводить спец символы, которые достаточно сложно бывает экранировать при вводе сообщение коммита прямо в командной строке

> * Пишите сообщение коммита так же, как вы пишите электронное письмо - с заголовком и, необязательно, с телом

> * Заголовок коммита от тела отделяется пустой строкой

> * В заголовке коммита постарайтесь кратко описать, о чем этот коммит

> * Если вам нужно уточнить, почему было сделано это изменение опишите это в теле коммита

> * Сообщение коммита должно фокусироваться на "причинах" изменения, а не на том "как" или "что" сделано. Конечно, это не всегда возможно, но об этом стоит помнить

> * Тип коммита обычное следует из типа задачи, которую вам поставили, лучше заранее посоветоваться с командой и задокументировать список типов, чтобы использовать их единообразно

> * Помните что опечатку в тексте коммита, можно исправить применением флага `--amend`



## Отправьте свои изменения из локального репозитория в удаленный Fork репозиторий на GitHub



* Отправьте изменения в ваш удаленный `fork-репозиторий` на `GitHub`



  ```shell

  git push -u origin feat/37/issue-name

  ```



## Создайте запрос на слияние (Pull Request) из Fork репозитория в оригинальный репозиторий проекта



> `Pull Request` позволяет создать запрос на слияние одной ветки в другую (в обычном случае запрос на слияние рабочей ветки в интеграционную) в удаленном репозитории. Создавая `pull request` мы показываем коллегам свои намерения выгрузить свою работу в интеграционную ветку, и они видят какие изменения будут внесены.

Запрос на слияние также дает возможность вашим коллегам предложение о том, как бы вы могли улучшить или изменить вашу работу.

Можно назначать конкретных рецендентов, отвественных за просмотр запроса и принятия решения о том, что работа выполнена качественно и точно.

Вы можете рассматривать запрос на слияние, как публичное слияние с голосованием - ваши коллеги получат возможность просмотреть вашу работу, прежде чем она станет частью целого.



* Перейдите в свой `fork-репозиторий` на `GitHub` и нажмите `Pull Request`

* Выберите свою ветку

* В комментарии напишите `Close #37` - это позволит связать запрос на слияние (`Pull Request`) и задачу (`issue`) по ее номеру, и если ваши дороботки будут слиты с интеграционной веткой - задача будет автоматически закрыта благодаря такому связыванию



> Если после запроса на слияние вам делают замечание, которое надо исправить, вы можете открыть свою локальную ветку внести в нее требуемые изменения сделать коммит и повторно выгрузить ветку в удаленный репозиторий, и снова подать запрос на слияние, при этом старый запрос (`pull request`) будет автоматически обновлен, чтобы отразить все коммиты в вашей ветке, и ваши коллеги могут посмотреть его повторно, чтобы убедиться что замечание было устранено.



## Ожидайте реакции автора оригинального репозитория



* В идеальном случае ваши доработки будут одобрены и слиты в интеграционную ветку оригинального проекта

* Автор так же вправе сделать вам предложения доработать ваши изменения, если он посчитает, что изменения в них нуждаются



## Удалите функциональную ветку



> Удаление функциональных веток после слияния не приносит никакого вреда - история коммитов остаётся. Удаление функциональной ветки до слияния завершится ошибкой.



* После слияния вашей функциональной ветки с интеграционной веткой автора, [синхронизируйте](#синхронизируйте-fork-из-веб-интерфейса-github) (догоните) эти изменения в вашем `fork-репозитории`

* Удалите функциональную ветку в `fork-репозитории` в разделе `branches` (`https://github.com/имя-профиля/проект/branches`)

* Обновите ваш локальный репозиторий из `fork-репозитория`:

  * переключитесь на интеграционную ветку

    

  ```shell

    git checkout main

  ```



  * обновите локальный репозиторий



  ```shell

    git pull

  ```



* Так как теперь интеграционная ветка содержит все последние изменения, включая ваши доработки, удалите функциональную ветку



```shell

  git branch -d имя-функциональной-ветки

```



## Обновить ветки слежения



* Очистите все [ветки слежения](https://git-scm.com/book/ru/v2/Ветвление-в-Git-Удалённые-ветки) (`remote`), у которых больше нет объекта в удаленном репозитории и получите все новые ветки и коммиты, которые отображаются на удаленном сервере следующей командой:



```shell

  git fetch --prune

```



## Ссылки на полезные материалы



* [Pro Git](https://git-scm.com/book/ru/v2)

* [Head First Git](https://i-love-git.com/)

* [Conventional Commits](https://www.conventionalcommits.org/ru/v1.0.0/)

* [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/)

* [Oh Shit, Git!?!](https://ohshitgit.com/ru)

* [email + git = <3](https://git-send-email.io/)

* [Learn Git Branching](https://learngitbranching.js.org/)