the-beginners-guide-to-contributing-to-a-github-project (RU)

guide-to-contributing-to-github-project-RU.md

Руководство для начинающих по участию в проектах на GitHub

Адаптированный перевод статьи The beginner's guide to contributing to a GitHub project

Автор оригинала Rob Allen

Это руководство по внесению вклада в проект с открытым исходным кодом, использующий GitHub. Здесь приведено только общие рекомендации, поэтому ознакомьтесь с README вашего проекта для уточнения деталей.

В ДВУХ СЛОВАХ

Читайте краткое описание.

Шаг 1: Создайте рабочую копию на своем компьютере

Прежде всего, вам нужен локальный форк проекта, поэтому нажмите кнопку " fork" в GitHub. Это создаст копию репозитория в вашем собственном аккаунте GitHub, а под названием проекта вы увидите отметку о том, что он был форкнут:

Теперь вам нужна локальная копия, найдите "SSH clone URL" в правой колонке и используйте его для клонирования локально с помощью терминала:

$ git clone git@github.com:akrabat/zend-validator.git

Результат будет выглядеть примерно так:

Перейдите в директорию нового проекта:

$ cd zend-validator

Теперь необходимо установить связь с оригинальным проектом, чтобы вы могли получать любые изменения и вносить их в свою локальную копию. Сначала перейдите по ссылке в оригинальный репозиторий - она помечена как "Forked from" в верхней части страницы GitHub. Это вернет вас на главную страницу проекта на GitHub, где вы сможете найти "SSH clone URL" и использовать его для создания новой связи, которую мы назовем upstream.

$ git remote add upstream git@github.com:zendframework/zend-validator.git

Теперь ваша локальная копия проекта связана с двумя репозиториями на GitHub:

1. origin, который указывает на ваш форк проекта на GitHub. Вы можете читать и писать в этот репозиторий.
2. upstream, который указывает на репозиторий GitHub основного проекта. Вы можете только читать из этого репозитория.

Шаг 2: Заставьте его работать на вашей машине

Теперь, когда у вас есть исходный код, запустите его на своем компьютере. Надеюсь, в файле README или INSTALL будет документация о том, как это сделать.

Если у вас все работает, но документация неясна, то улучшение этого раздела должно стать вашим первым PR в проекте. Это одновременно и самый простой и полезный способ войти в проект!

Шаг 3: Сделайте что-нибудь полезное

Это самый приятный этап - внести свой вклад в проект. Начинать лучше исправления ошибки, которая либо раздражает вас, либо вы нашли ее в трекере проблем проекта. Если вы ищете, с чего начать, многие проекты используют ярлык "good first issue" (или его разновидность), чтобы указать, что эту проблему может решить новичок в проекте.

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

Ветвление

Правило номер один - размещать каждую часть разработки в отдельной ветке. Если проект использует git-flow, то у него будет ветка master и ветка develop. Общее правило таково: если вы исправляете ошибку, то ветвь от master, а если добавляете новую функцию, то ветвь от develop. Если у проекта есть только ветка master, то ветка от нее. Некоторые проекты, используют ветви, названные по номеру версии (2.x и 3.x и т.п.). В этом случае выберите соответствующую ветку.

В нашем примере мы предположим, что исправляем ошибку в zend-validator, поэтому мы создадим ветку от master:

$ git checkout master
$ git pull upstream master && git push origin master
$ git checkout -b hotfix/readme-update

В первую очередь мы убеждаемся, что находимся на master-ветке. Затем команда git pull синхронизирует нашу локальную копию с основной веткой проекта, а команда git push синхронизирует ее с нашим форкнутым проектом на GitHub. Наконец, мы создаем нашу новую ветку. Вы можете назвать свою ветку как угодно, но важно, чтобы она была осмысленной. Обычно полезно включить номер проблемы. Если проект использует git-flow, как это делает zend-validator, то существуют специальные соглашения об именовании, в которых ветка имеет префикс "hotfix/" или "feature/".

Теперь вы можете заняться устранением проблемы.

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

Убедитесь, что вы исправляете только то, над чем работаете. Не поддавайтесь искушению исправить другие вещи, которые вы видите по пути, включая проблемы форматирования, так как ваш PR, скорее всего, будет отклонен.

Убедитесь, что вы коммитите логичными блоками. Каждый коммит должен быть обоснованным. Прочитайте статью Как правильно составлять описания коммитов и почему это важно.

Шаг 4: Создайте Pull Request

Чтобы создать PR, вам нужно отправить вашу ветку в Ваш форк на GitHub, а затем нажать несколько кнопок на GitHub.

Чтобы отправить новую ветку:

$ git push -u origin hotfix/readme-update

В результате будет создана ветка в вашем проекте на GitHub. Флаг -u связывает эту ветку с удаленной, так что в будущем вы сможете просто набрать git push origin.

Вернитесь в браузер и перейдите к вашему форку проекта (https://github.com/akrabat/zend-validator в нашем примере), и вы увидите, что ваша новая ветка появилась в верхней части с удобной кнопкой "Compare & pull request":

Нажмите эту кнопку!

Если вы видите выделенную надпись, как показано ниже:

Нажмите на ссылку, которая приведет вас к файлу CONTRIBUTING проекта, и прочитайте его! Он содержит ценную информацию о том, как работать с кодовой базой проекта, и поможет вам добиться одобрения вашего вклада.

На этой странице убедитесь, что "base fork" указывает на правильный репозиторий и ветку. Затем дайте хорошее, краткое название вашему запросу и объясните, почему вы его создали в поле описания. Добавьте соответствующие номера проблем, если они у вас есть.

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

Как только вы будете уверены, нажмите кнопку "Create pull request" и все готово.

Шаг 5: Проверка разработчиками проекта

Чтобы ваши изменения были приняты в проект, разработчики проанализируют вашу работу и либо запросят изменения, либо объединят ее с основной веткой.

Зачем и как нужно ревьюить код вы можете посомтреть Вебинар о код-ревью: зачем он нужен, как оптимизировать код и как делают в Skyeng .

В ДВУХ СЛОВАХ

Вот и все. Главные принципы таковы:

1. Форкни проект и склонируй его на свой компьютер.
2. Установи связь с основным репозиторием проекта (upstream remote) и синхронизируй с ним локальную копию.
3. Создавай локальный бранчь для каждого логического блока работы.
4. Внеси изменения, создавай хорошие описания коммитов, и читай файл CONTRIBUTING, если он есть.
5. Синхронизируй изменения со своми форком (origin remote).
6. Создайте Pull Request на GitHub.
7. Отвечайте на все замечания полученные в код-ревью.

Если вы хотите внести свой вклад в проект с открытым исходным кодом, лучше всего выбрать тот, который вы используете сами. Разработчики будут вам благодарны!