Шпаргалка для чайников по GitHub

Одна из самых важных вещей, которые нужно уметь делать, – это находить дополнительную информацию на GitHub, когда она вам нужна. GitHub постоянно развивается и меняется, и к тому времени, когда вы будете читать эту статью, в Git могут появиться новые функции, новые приложения для интеграции или новые популярные проекты. Важно, чтобы вы помнили, как узнать больше о GitHub как об инструменте.

Документация GitHub

На GitHub есть обширный список документации. Вы можете воспользоваться строкой поиска в верхней части страницы, чтобы найти конкретную тему, или выбрать продукт GitHub, о котором у вас есть вопрос (сюда входит GitHub.com), а затем просмотреть темы, популярные среди пользователей GitHub.

Документы GitHub часто эффективны для тех, у кого есть конкретный вопрос. Если вы хотите в целом узнать, как пользоваться продуктами, вам может быть сложнее ориентироваться в документации GitHub. Однако внизу каждой страницы на сайте Docs есть ссылка на страницу контактов GitHub, а также рекомендации о том, когда, к кому и как обращаться по различным проблемам, с которыми вы можете столкнуться.

Руководства GitHub

GitHub также выпустил ряд руководств, помогающих в выполнении общих действий по началу работы. Если вы зайдете на сайт GitHub.com, вы найдете около десяти руководств, которые можно прочитать от 3 до 10 минут. Считайте эти руководства версией шпаргалки GitHub. Эти руководства могут быть действительно эффективными, если у вас есть определенная цель, так как темы варьируются от того, как форкнуть проект, до того, как быть социальным на платформе.

Одно из самых важных руководств на этой странице – руководство по потокам GitHub. Эта интерактивная диаграмма объясняет весь процесс работы GitHub, начиная с написания и фиксации кода и заканчивая созданием и объединением запросов на перенос.

Попробуйте GitHub

На сайте GitHub.com вы можете найти целый список интересных интерактивных инструментов. Этот сайт включает интерактивные визуализированные представления git-репозиториев, список удобных шпаргалок, которые можно распечатать, а также ссылки на учебные лаборатории GitHub и профессиональное обучение, которое предлагает GitHub.

Учебные лаборатории GitHub

Вероятно, это один из самых эффективных инструментов обучения на GitHub. Учебные лаборатории – это интерактивные занятия на реальной платформе GitHub.com, которые позволяют вам попробовать сложные рабочие процессы, такие как создание и рассмотрение запросов на исправление, создание сообщества на GitHub или даже настройка непрерывной интеграции в вашем проекте.

Быть эффективным коммуникатором в репозиториях GitHub

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

Комментарии к коду: Комментарии в вашем коде предлагают английское описание того, что должен делать ваш код. Комментарии могут помочь вам (или другим людям) определить, когда написанный код не достигает того, что ожидалось. Поддерживая комментарии в актуальном состоянии по мере изменения кода, вы облегчаете другим (или себе в будущем) понимание того, что должен делать код, и облегчаете выявление несоответствия цели реальности.

• README: README – это главная страница всего вашего проекта. Каждый раз, когда что-то меняется в том, как работает код или как внести свой вклад в код, вы всегда должны обновлять README. README – это первое место, куда приходят люди, впервые познакомившиеся с вашим проектом, поэтому вы хотите иметь описательное резюме программы как с точки зрения пользователя, так и с точки зрения разработчика.
• Документы: Написание документации по вашему программному обеспечению может быть очень эффективным способом избежать путаницы как для пользователей, так и для участников. Вы можете использовать генераторы документации, такие как Javadocs, или просто дисциплинированно писать документацию о любом новом или измененном коде в вашем проекте. Проект с впечатляющей документацией – это Atom.
• Описания проблем: Если вы нашли ошибку, созданный вами выпуск должен всегда включать подробное описание того, какую именно ошибку вы обнаружили. Вы должны указать версию программного обеспечения или ветку, на которой вы работали, версию операционной системы и другие важные версии программного обеспечения, например, браузера. Также может быть полезно приложить скриншоты. Если у вас есть идея для будущей функции или модификации программного обеспечения, убедитесь, что вы изложили ее как можно подробнее. Будьте уважительны в своих просьбах и признайте, что основные разработчики проекта могут не согласиться с вашим предложением, или оно может не быть для них приоритетным. Другими словами, не пытайтесь требовать, чтобы то, что вы хотите, было сделано немедленно, а сосредоточьтесь на цели быть сотрудничающим членом проекта.
• Описание Pull-запроса: В описаниях запросов на исправление должны быть ссылки на проблемы, которые они исправляют. Вы можете напрямую ссылаться на проблемы, специально помечая их. Если вы добавите “Closes” перед ссылкой на проблему, то когда запрос на исправление будет объединен, проблема будет закрыта вместе с ним. В дополнение к проблеме (проблемам), на которую направлен запрос на исправление, вы всегда должны иметь четкое, подробное описание внесенных вами изменений, как они могут повлиять на другие части программного обеспечения, выполненные вами модульные тесты и скриншоты, демонстрирующие внесенные изменения. Вы также можете открыть запрос на исправление, когда только начинаете решать проблему, и использовать описание в качестве наброска того, что вам нужно сделать для выполнения задачи. У вас может быть буквальный контрольный список, который поможет соавторам узнать, на каком этапе решения вы находитесь, и лучше понять, как быстро вы можете закончить работу.
• Навигация по проекту программного обеспечения с открытым исходным кодом на GitHub

Когда вы впервые сталкиваетесь с проектом открытого программного обеспечения (OSS) на GitHub, вам следует потратить достаточное количество времени на изучение проекта, документации и рекомендаций, прежде чем вы попытаетесь внести свой вклад в проект. OSS

Это также важная составляющая для того, чтобы стать членом сообщества. Приход постороннего человека, предлагающего изменения (либо через проблемы, либо через pull request), не имея опыта работы над проектом, создаст впечатление, что вы не заинтересованы в проекте. Подходите к проектам как к опыту обучения, а не как к возможности поучать. Со временем у вас, вероятно, появится шанс внести значительные изменения и, возможно, научить других.

Есть несколько мест, с которых следует начать, когда вы ориентируетесь в проекте на GitHub:

README: Убедитесь, что вы прочитали README, где вы можете найти много полезной информации о совместимости и о том, как начать работу в качестве пользователя или соавтора программы.

• Документы по началу работы: Часто в проектах есть руководство о том, как начать использовать или вносить вклад в проект. Если ваша цель – внести свой вклад в программное обеспечение, создайте форк проекта и запустите его на своей локальной машине. Если у вас возникли проблемы, просмотрите документацию или проблемы (даже те, которые могут быть закрыты), прежде чем открывать новую проблему со своим вопросом. Скорее всего, кто-то уже сталкивался с подобной проблемой, и ответ уже есть в репозитории. Если проблема кажется серьезной, вы можете даже внести предложение по изменению документации, чтобы включить в нее исправление.
• Руководство по внесению вклада: В большинстве проектов есть руководство по внесению вклада, которое часто включает в себя Кодекс поведения. Вы должны относиться к этому очень серьезно. Писать код недостаточно; вы должны быть готовы присоединиться к сообществу и быть его положительным членом. О плохом поведении будет (и должно) сообщено сопровождающим. Руководство по внесению вклада также часто включает соглашения об именовании, процесс принятия решений, рабочий процесс между сопровождающими и сопровождаемыми, а также общие руководства по стилю.
• Существующие проблемы и запросы на исправление: Наконец, прежде чем приступать к работе, ознакомьтесь с некоторыми существующими проблемами и запросами на исправление, чтобы понять, как общается сообщество. Это поможет вам лучше взаимодействовать с конкретным сообществом, а также принять решение о том, что это сообщество вам не подходит. Вы также можете увидеть, каков рабочий процесс основных участников этого проекта. Например, часто ли запросы на доработку бывают большими с большим количеством серьезных изменений или маленькими с очень сфокусированными целями?
• Об этой статье

Эта статья взята из книги:

Об авторах книги:

Сара Гуталс, доктор философии, инженер социального программного обеспечения, предприниматель и бывший инженерный менеджер в GitHub. Она является соавтором книги Helping Kids with Coding For Dummies. Фил Хаак – бывший инженерный директор GitHub и старший менеджер программ в Microsoft. Он является автором ряда книг по ASP.NET.

Изображение книги