Как посмотреть проект на гитхабе

Метрики проектов с открытым исходным кодом

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

Зачем что-то измерять?

Данные, при разумном использовании, могут помочь вам принимать лучшие решения в качестве сопровождающего (maintainer) открытого исходного кода.

Имея больше информации, вы можете:

• Понять, как пользователи реагируют на новую функцию
• Выяснить, откуда приходят новые пользователи
• Определить и решить, стоит ли поддерживать новую функциональность
• Оценить популярность вашего проекта
• Понять, как используется ваш проект
• Привлечь инвестиции через спонсорство и гранты

Например, Homebrew обнаружил, что Google Analytics помогает ему определять приоритеты в работе:

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

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

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

Обнаруживаемость

Прежде чем кто-то сможет воспользоваться вашим проектом или внести в него свой вклад, он должен узнать о его существовании. Спросите себя: могут ли люди найти этот проект?

Если ваш проект размещён на GitHub, вы можете посмотреть, сколько людей попадают в ваш проект и откуда они приходят. На странице вашего проекта нажмите Insights, затем Traffic. На этой странице вы можете увидеть:

• Общее количество просмотров страниц: показывает, сколько раз был просмотрен ваш проект.
• Общее количество уникальных посетителей: показывает, сколько человек просмотрело ваш проект.
• Сайты-источники: рассказывает о том, откуда пришли посетители. Эта метрика может помочь вам определить, где можно привлечь аудиторию и работают ли ваши усилия по продвижению.
• Популярный контент: рассказывает о том, куда заходят посетители вашего проекта, в разбивке по просмотрам страниц и уникальным посетителям.

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

Вы также можете захотеть отслеживать открываемость в определенных местах: например, Google PageRank, реферальный трафик с сайта вашего проекта или рефералы с других проектов с открытым исходным кодом или сайтов.

Использование

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

Если вы используете менеджер пакетов, такой как npm или RubyGems.org, для распространения вашего проекта, вы можете отслеживать скачивания пакета.

Каждый пакетный менеджер может использовать несколько иное определение “скачивания”, и скачивания не обязательно коррелируют с установками или использованием, но это даёт некоторую базу для сравнения. Попробуйте использовать Libraries.io для отслеживания статистики использования многих популярных менеджеров пакетов.

Если ваш проект находится на GitHub, снова перейдите на страницу Traffic. Вы можете использовать clone graph, чтобы увидеть, сколько раз ваш проект был клонирован в определенный день, с разбивкой по общему количеству клонирований и уникальным клонирователям.

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

• Ваш проект плохо конвертирует вашу аудиторию, либо
• Вы привлекаете не ту аудиторию

Например, если ваш проект попадет на первую страницу Hacker News, вы, вероятно, увидите всплеск посещений (трафика), но более низкий коэффициент конверсии, поскольку вы охватите всех пользователей Hacker News. Однако если ваш Ruby-проект будет представлен на конференции Ruby, вы, скорее всего, получите высокий коэффициент конверсии от целевой аудитории.

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

Как только вы узнаете, что люди используют ваш проект, вы можете попытаться выяснить, что они с ним делают. Создают ответвления (fork) вашего кода и добавляют функции? Используют для науки или бизнеса?

Удержание

Люди находят ваш проект и используют его. Следующий вопрос, который вы захотите задать себе: участвуют (contribute) ли люди в этом проекте?

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

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

Вот ещё показатели для отслеживания:

• Общее количество участников и количество правок (commit) на одного участника: позволяет узнать, сколько у вас участников и кто из них более или менее активен. На GitHub это можно посмотреть в разделе Insights ->Contributors. В настоящее время этот график учитывает только тех участников, которые сделали правку (commit) в ветку репозитория по умолчанию.

• Первоначальные, случайные и повторные участники: помогает вам отслеживать, привлекаете ли вы новых участников и возвращаются ли они. (Случайные участники — те, у кого мало правок (commit). Будет ли это одна правка, менее пяти или что-то другое — решать вам). Без новых участников сообщество вашего проекта может стать застойным.
• Количество текущих открытых проблем (issue) и запросов на перенос (pull request): если эти показатели слишком высоки, вам может понадобиться помощь в устранении проблем и проверке кода.
• Общее количество проблем (issues) и запросов на перенос (pull request) (включая закрытые): открытые когда-то проблемы (issues) означают, что ваш проект кому-то достаточно интересен, чтобы он открыл проблему (issue). Если это число увеличивается со временем, это говорит о том, что люди заинтересованы в вашем проекте.
• Типы вклада (contribution): например, правки (commit), исправление опечаток или ошибок, или комментирование проблемы (issue).

Открытый исходный код — это больше, чем просто код. Успешные проекты с открытым исходным кодом включают написание кода и документации вместе с обсуждением этих изменений.

Активность сопровождающих

Наконец, вы захотите замкнуть цикл, убедившись, что участники вашего проекта в состоянии справиться с объёмом получаемых вкладов (contributions). Последний вопрос, который вы хотите задать себе, это: отвечаю ли я (или мы) на запросы нашего сообщества?

Неотзывчивые сопровождающие становятся узким местом для проектов с открытм кодом. Если кто-то вносит свой вклад, но так и не получает ответа от сопровождающего, он может разочароваться и уйти.

Исследование компании Mozilla предполагает, что отзывчивость сопровождающих является критическим фактором поощрения повторного участия.

Отслеживайте, сколько времени требуется вам (или другому сопровождающему), чтобы ответить на вклад, будь то проблема (issue) или запрос на перенос (pull request). Для ответа не обязательно предпринимать какие-либо действия. Можно просто сказать: “Спасибо за ваш вклад! Я рассмотрю его в течение следующей недели.”

Можно также измерять время, необходимое для перехода от одного этапа процесса внесения вклада к другому, например:

• Среднее время, в течение которого проблема (issue) остаётся открытой
• Закрываются ли проблемы (issue) в запросе на перенос (pull request)
• Закрываются ли неактуальные проблемы (issue)
• Среднее время для слияния запроса на перенос (pull request)

Используйте ��, чтобы узнать о людях

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

CHAOSS — это гостеприимное сообщество с открытым исходным кодом, ориентированное на аналитику, показатели и программное обеспечение для здоровья сообщества.

6.3 GitHub — Сопровождение проекта

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

Создание нового репозитория

Давайте создадим новый репозиторий для распространения кода нашего проекта. В панели управления справа нажмите кнопку «New repository» или воспользуйтесь кнопкой + на панели инструментов, рядом с вашим именем пользователя как показано на рисунке Выпадающее меню «New repository».

Рисунок 109. Раздел «Your repositories»

Рисунок 110. Выпадающее меню «New repository»

Это приведёт к открытию формы «New repository»:

Рисунок 111. Форма «new repository»

Всё, что в действительности нужно сделать, так это указать название проекта, все остальные поля опциональны. Сейчас, просто нажмите кнопку «Create Repository» и ваш новый репозиторий с названием / готов.

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

Теперь ваш проект хостится на GitHub и вы можете предоставить ссылку на него любому желающему. Все проекты на GitHub доступны как по HTTP https://github.com// , так по SSH git@github.com:/ . Git может получать и отправлять изменения по обоим указанным ссылкам, при этом производится контроль доступа на основании учётных данных пользователя, осуществляющего подключение.

Примечание

Обычно, для общедоступного проекта предпочтительнее использовать HTTPS ссылки, так как это не требует наличия GitHub аккаунта для клонирования репозитория. При этом, для использования SSH ссылки у пользователя должен быть GitHub аккаунт и его SSH ключ должен быть добавлен в ваш проект. Так же HTTPS ссылка полностью совпадает с URL адресом, который пользователи могут вставить в браузер для просмотра вашего репозитория.

Добавление участников

Если вы работаете с другими людьми, которым вы хотите предоставить доступ для отправки коммитов, то вам следует добавить их как «участников». Если Бен, Джефф и Льюис зарегистрировались на GitHub и вы хотите разрешить им делать «push» в ваш репозиторий, то добавьте их в свой проект. Это предоставит им «push» доступ; это означает, что они будут иметь права доступа как на чтение, так и на запись в проект и Git репозиторий.

Перейдите по ссылке «Settings» в нижней части панели справа.

Рисунок 112. Ссылка на настройки репозитория

Затем выберите «Collaborators» в меню слева. Напишите имя пользователя в поле для ввода и нажмите кнопку «Add collaborator». Так вы можете добавить неограниченное количество пользователей. Чтобы отозвать доступ, просто нажмите «X» справа от имени пользователя.

Рисунок 113. Участники проекта

Управление запросами на слияние

Сейчас у вас есть проект с некоторым кодом и, возможно, несколько участников с «push» доступом, давайте рассмотрим ситуацию, когда вы получаете запрос на слияние.

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

Для последующих примеров предположим, что вы «tonychacon» и создали новый проект для Arduino с названием «fade».

Email уведомления

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

Рисунок 114. Email уведомление о новом запросе слияния

Следует сказать о некоторых особенностях этого уведомления. В нём содержится краткая статистика отличий — количество изменений и список файлов, которые были изменены в этом запросе слияния, ссылка на страницу запроса слияния на GitHub, а так же несколько ссылок, которые вы можете использовать в командной строке.

Если вы видите строку с текстом git pull patch-1 , то это самый простой способ слить удалённую ветку без добавления удалённого репозитория. Это кратко описывалось в Извлечение удалённых веток. Если хотите, то можно сначала переключиться в тематическую ветку и только потом выполнить эту команду для изменений запроса слияния.

Другие ссылки, которые представляют интерес, это .diff и .patch ссылки. Как вы догадались, они указывают на версии унифицированной разницы и патча запроса слияния. Технически, вы можете слить изменения из запроса слияния командой:

$ curl https://github.com/tonychacon/fade/pull/1.patch | git am

Взаимодействие по запросу слияния

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

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

Рисунок 115. Ответы на письма включены в диалог

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

Если слияние тривиально, то можно просто нажать кнопку «Merge» на сайте GitHub. Это всегда приводит с созданию коммита слияния, даже если доступно слияние перемоткой вперёд. Это значит, что в любом случае создаётся коммит слияния, как только вы нажимаете кнопку «Merge». Как можно увидеть на Кнопка Merge и инструкции по ручному слиянию запроса, GitHub отображает информацию об этом при вызове подсказки.

Рисунок 116. Кнопка Merge и инструкции по ручному слиянию запроса

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

Ссылки на запрос слияния

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

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

В качестве примера мы используем низкоуровневую команду ls-remote (часто упоминается как «plumbing» команда, более подробно о ней будет рассказано в Сантехника и Фарфор). Обычно, эта команда не используется в повседневных Git операциях, но сейчас поможет нам увидеть какие ссылки присутствуют на сервере.

Если выполнить её относительно использованного ранее репозитория «blink», мы получим список всех веток, тегов и прочих ссылок в репозитории.

$ git ls-remote https://github.com/schacon/blink 10d539600d86723087810ec636870a504f4fee4d HEAD 10d539600d86723087810ec636870a504f4fee4d refs/heads/master 6a83107c62950be9453aac297bb0193fd743cd6e refs/pull/1/head afe83c2d1a70674c9505cc1d8b7d380d5e076ed3 refs/pull/1/merge 3c8d735ee16296c242be7a9742ebfbc2665adec1 refs/pull/2/head 15c9f4f80973a2758462ab2066b6ad9fe8dcf03d refs/pull/2/merge a5a7751a33b7e86c5e9bb07b26001bb17d775d1a refs/pull/4/head 31a45fc257e8433c8d8804e3e848cf61c9d3166c refs/pull/4/merge

Аналогично, если вы, находясь в своём репозитории, выполните команду git ls-remote origin или укажете любой другой удалённый репозиторий, то результат будет схожим.

Если репозиторий находится на GitHub и существуют открытые запросы слияния, то эти ссылки будут отображены с префиксами refs/pull/ . По сути это ветки, но так как они находятся не в refs/heads/ , то они не копируются при клонировании или получении изменений с сервера — процесс получения изменений игнорирует их по умолчанию.

Для каждого запроса слияния существует две ссылки, одна из которых записана в /head и указывает на последний коммит в ветке запроса на слияние. Таким образом, если кто-то открывает запрос на слияние в наш репозиторий из своей ветки bug-fix , которая указывает на коммит a5a775 , то в нашем репозитории не будет ветки bug-fix (так как она находится в форке), при этом у нас появится pull//head , которая указывает на a5a775 . Это означает, что мы можем стянуть все ветки запросов слияния одной командой не добавляя набор удалённых репозиториев.

Теперь можно получить ссылки напрямую.

$ git fetch origin refs/pull/958/head From https://github.com/libgit2/libgit2 * branch refs/pull/958/head -> FETCH_HEAD

Эта команда указывает Git: «Подключись к origin репозиторию и скачай ссылку refs/pull/958/head ». Git с радостью слушается и выкачивает всё необходимое для построения указанной ссылки, а так же устанавливает указатель на коммит в .git/FETCH_HEAD . Далее, вы можете слить изменения в нужную ветку при помощи команды git merge FETCH_HEAD , однако сообщение коммита слияния будет выглядеть немного странно. Так же это становится утомительным, если вы просматриваете много запросов на слияние.

Существует способ получать все запросы слияния и поддерживать их в актуальном состоянии при подключении к удалённому репозиторию. Откройте файл .git/config в текстовом редакторе и обратите внимание на секцию удалённого репозитория origin . Она должна выглядеть как-то так:

[remote "origin"] url = https://github.com/libgit2/libgit2 fetch = +refs/heads/*:refs/remotes/origin/*

Строка, начинающаяся с fetch = , является спецификацией ссылок («refspec»). Это способ сопоставить названия в удалённом репозитории с названиями в локальном каталоге .git . Конкретно эта строка говорит Git: «все объекты удалённого репозитория из refs/heads должны сохраняться локально в refs/remotes/origin ». Вы можете изменить это поведение добавив ещё одну строку спецификации:

[remote "origin"] url = https://github.com/libgit2/libgit2.git fetch = +refs/heads/*:refs/remotes/origin/* fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

Последняя строка говорит Git: «Все ссылки, похожие на refs/pull/123/head , должны быть сохранены локально как refs/remotes/origin/pr/123 ». Теперь, если сохранить файл и выполнить команду git fetch , вы получите:

$ git fetch # … * [new ref] refs/pull/1/head -> origin/pr/1 * [new ref] refs/pull/2/head -> origin/pr/2 * [new ref] refs/pull/4/head -> origin/pr/4 # …

Все запросы слияния из удалённого репозитория представлены в локальном репозитории как ветки слежения; они только для чтения и обновляются каждый раз при выполнении git fetch . Таким образом, локальное тестирование кода запроса слияния становится очень простым:

$ git checkout pr/2 Checking out files: 100% (3769/3769), done. Branch pr/2 set up to track remote branch pr/2 from origin. Switched to a new branch 'pr/2'

Особо внимательные из вас заметили head в конце спецификации, относящейся к удалённому репозиторию. Так же на стороне GitHub существует ссылка refs/pull/#/merge , которая представляет коммит, формируемый при нажатии кнопки «merge» на сайте. Это позволяет вам протестировать слияние перед нажатием этой кнопки.

Запросы слияния на запросы слияния

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

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

При открытии запроса на слияние вверху страницы вы увидите меню для выбора целевой и исходной веток. Если нажать кнопку Edit справа, то станет доступным выбор не только исходной ветки, а ещё и форка.

Рисунок 117. Ручное изменение форка и ветки для запроса слияния

Здесь можно указать вашу новую ветку для слияния с другим запросом слияния или другим форком проекта.

Упоминания и уведомления

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

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

Рисунок 118. Напишите @ для упоминания кого-либо

Так же можно упомянуть пользователя, не указанного в выпадающем списке, но с помощью автодополнения это можно сделать быстрее.

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

Если кто-то будет упомянут в запросе слияния или проблеме, то он автоматически «подписывается» и будет получать уведомления о последующей активности. Вы так же будете подписаны на некоторые уведомления если просто откроете запрос слияния или проблему, станете отслеживать репозиторий или если оставите комментарий. Для прекращения отправки вам уведомлений нажмите кнопку «Unsubscribe».

Рисунок 119. Отказ от подписки на проблему или запрос слияния

Страница уведомлений

Когда мы говорим «уведомления» в контексте GitHub, мы имеем ввиду способ, которым GitHub пытается связаться с вами в случае возникновения каких-либо событий, настроить который можно несколькими способами. Для просмотра настроек уведомлений перейдите на закладку «Notification center» на странице настроек.

Рисунок 120. Настройки центра уведомлений

Доступны два вида уведомлений: посредствам «Email» и «Web». Вы можете выбрать один, ни одного или оба, если активно участвуете в событиях отслеживаемых репозиториев.

Web уведомления

Такие уведомления существуют только на GitHub и посмотреть их можно только на GitHub. Если эта опция включена у вас в настройках и уведомление сработало для вас, то вы увидите небольшую синюю точку на иконке уведомлений вверху экрана, как показано на рисунке Центр уведомлений.

Рисунок 121. Центр уведомлений

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

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

Email уведомления

Email уведомления — это ещё один способ, которым вы можете получать уведомления от GitHub. Если эта опция включена, то вы будете получать по письму на каждое уведомление. Примеры вы видели в разделах Комментарии, отправленные по электронной почте и Email уведомление о новом запросе слияния. Письма объединяются в цепочки, что очень удобно при использовании соответствующего почтового клиента.

GitHub включает много дополнительных метаданных в заголовки каждого письма, что полезно при настройке различных фильтров и правил сортировки.

Например, если взглянуть на заголовки письма, отправленного Тони в примере Email уведомление о новом запросе слияния, то можно увидеть следующее:

To: tonychacon/fade Message-ID: Subject: [fade] Wait longer to see the dimming effect better (#1) X-GitHub-Recipient: tonychacon List-ID: tonychacon/fade List-Archive: https://github.com/tonychacon/fade List-Post: List-Unsubscribe: . X-GitHub-Recipient-Address: tchacon@example.com

Здесь можно увидеть несколько интересных вещей. Если вы хотите выделить или перенаправить письма конкретного проекта или запроса на слияние, то информация, содержащаяся в заголовке Message-ID , предоставляет вам соответствующие сведения в формате /// . Для задачи вместо «pull» будет указано «issues».

Заголовки List-Post и List-Unsubscribe , при наличии у вас почтового клиента, который их понимает, позволяют легко написать в список рассылки или отписаться от неё. Это то же самое, что и нажать кнопку «mute» в веб версии уведомлений или «Unsubscribe» на странице задачи или запроса на слияние.

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

Особенные файлы

Существует несколько особенных файлов, которые GitHub заметит при наличии их в вашем репозитории.

README

Первый — это файл README , он может быть в любом формате, который GitHub в состоянии распознать. Например, это может быть README , README.md , README.asciidoc и так далее. Если GitHub увидит такой файл в вашем исходном коде, то отобразит его на заглавной странице проекта.

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

• Для чего предназначен проект
• Инструкции по конфигурации и установке
• Примеры использования
• Используемую лицензию
• Правила участия в проекте

В этот файл можно встраивать изображения или ссылки для простоты восприятия информации.

CONTRIBUTING

Следующий файл — это CONTRIBUTING . Если в вашем репозитории будет файл CONTRIBUTING с любым расширением, то GitHub будет показывать ссылку на него при создании любого запроса на слияние.

Рисунок 122. Создание запроса на слияние при наличии файла CONTRIBUTING

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

Управление проектом

Для одного проекта не так уж и много администраторских действий, но есть несколько стоящих внимания.

Изменение основной ветки

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

Рисунок 123. Изменение основной ветки проекта

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

Передача проекта

Если вы хотите передать проект другому пользователю или организации на GitHub, то это можно сделать нажатием кнопки «Transfer ownership» в настройках репозитория на закладке «Options».

Рисунок 124. Передача проекта другому пользователю или организации на GitHub

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

Это действие приведёт не только к передаче репозитория со всеми его подписчиками и звёздами, но и добавит перенаправление с вашего URL на новый. Кроме этого, изменятся ссылки для клонирования и получения изменений из Git, а не только для веб запросов.

Как использовать GitHub Pages?

GitHub — это сайт «социальной разработки». Он позволяет загружать репозитории кода для хранения в системе управления версиями Git. После загрузки вы можете сотрудничать с другими участниками для работы над общим проектом, а ещё это система с открытым исходным кодом по умолчанию: любой человек в мире может найти ваш код на GitHub, использовать его, учиться по нему и улучшать его. Вы тоже можете взаимодействовать с кодом других людей! В этой статье представлено базовое руководство по публикации контента с использованием функции gh-pages Github.

Публикация контента

GitHub — очень важное и полезное сообщество для участия, а Git/GitHub — очень популярная система управления версиями — большинство технологических компаний теперь использует её в своём рабочем процессе. У GitHub есть очень полезная функция GitHub Pages, которая позволяет публиковать живую демонстрацию кода в виде сайта в Интернете.

Базовая установка Github

1. Прежде всего, установите Git на свой компьютер. Это базовое программное обеспечение для управления версиями, поверх которого работает GitHub.
2. Затем зарегистрируйтесь на GitHub. Это просто.
3. После того, как вы зарегистрировались, войдите в свою учётную запись на github.com с помощью своих имени пользователя и пароля.

Подготовка кода для загрузки

В репозитории на Github вы можете хранить любой код, который вам нравится, но для полноценного использования функции GitHub Pages ваш код должен быть структурирован как типичный веб-сайт, то есть, основной точкой входа должен быть HTML-файл с именем index.html .

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

Направьте командную строку в вашу папку test-site (или папку с любым другим названием, содержащую ваш сайт). Для этого используйте команду cd (т.е. «change directory» — «поменяй директорию»). Вот что вы бы набрали, если бы разместили свой сайт в папке test-site на рабочем столе:

cd Desktop/test-site 

git init 

Дополнительно об интерфейсах командной строки

Лучший способ загрузить код в Github — использовать командную строку. Это окно, в котором вы вводите команды, чтобы делать такие вещи, как создавать файлы и запускать программы, вместо того чтобы кликать внутри пользовательского интерфейса. Оно будет выглядеть примерно так:

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

Каждая операционная система поставляется с инструментом командной строки:

• Windows: Командную строку (Command Prompt) можно вызвать, нажав клавишу Windows, набрав Command Prompt и выбрав её из появившегося списка. Обратите внимание, что в Windows свои собственные условные обозначения команд, отличные от Linux и OS X, поэтому приведённые ниже команды могут отличаться на вашем компьютере.
• OS X: Терминал (Terminal) можно найти в Applications > Utilities.
• Linux: Обычно терминал можно вызвать с помощью Ctrl + Alt + T. Если это не сработает, найдите Terminal в панели приложений или меню.

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

Создание репозитория для вашего кода

1. Затем вам нужно создать новый репозиторий для ваших файлов. Нажмите «Плюс» (+) в правом верхнем углу главной страницы GitHub и выберите «Новый репозиторий» (New Repository).
2. На этой странице в поле «Имя репозитория» (Repository name) введите имя для своего репозитория, например my-repository.
3. Также добавьте описание, чтобы уточнить, что будет содержать ваш репозиторий. Ваш экран должен выглядеть так:
4. Нажмите «Создать репозиторий» (Create repository); откроется следующая страница:

Загрузка файлов на GitHub

1. На текущей странице вас интересует раздел …or push an existing repository from the command line («. или загрузите существующий репозиторий с помощью командной строки»). В этом разделе вы должны увидеть две строки кода. Скопируйте всю первую строку, вставьте её в командную строку и нажмите Enter. Команда должна выглядеть примерно так:

git remote add origin https://github.com/chrisdavidmills/my-repository.git

git add --all git commit -m 'adding my files to my repository' 

git push -u origin main 

Больше информации о GitHub

Если вы хотите поменять что-то на своем тестовом сайте и загрузить результат на GitHub, вам просто нужно внести изменения в свои файлы, как и раньше. Затем вам потребуется ввести следующие команды (нажимая Enter после каждой), чтобы загрузить их на GitHub:

git add --all git commit -m 'another commit' git push

Вы можете написать более подходящее сообщение вместо another commit, чтобы уточнить, что именно вы только что изменили.

Мы едва коснулись Git. Чтобы узнать больше, начните с нашей статьи Git и GitHub.

Found a content problem with this page?

• Edit the page on GitHub.
• Report the content issue.
• View the source on GitHub.

This page was last modified on 3 авг. 2023 г. by MDN contributors.

Your blueprint for a better internet.

Как посмотреть проект на гитхабе

Руководство
по GitHub
для гуманитариев
⚡ 13/11/2019
⏱ 17 минут

Чтение профилей на Github это как чтение состава чипсов. Кажется сложным, но можно быстро разобраться. Сегодня попробуем разобраться и сделать так, чтобы нахождение профиля разработчика на Github вызывало только «ох, сейчас разработчику в душу прям заглянем».

Разберемся с терминами
Потому что это пугает больше всего.

Git — это распределенная система контроля версий кода. Она помогает разработчикам сохранять все изменения, внесённые в код, отслеживать изменения в файлах и работать совместно с командой.

Github — это cервис для хостинга (то есть хранения) репозиториев. На Github есть возможность контролировать разные версии кода, управлять исходным кодом и работать вместе с командой. То есть делать то же, что и Git.

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

Open Source — это прозрачный подход к созданию проектов. Разработчики открывают код продуктов, над которыми работают — над ним можно вместе работать, а ещё — копировать. И всё это на Github.

Коммит (commit) — это публичное сохранение, фиксация (в архиве, репозитории и др.) изменений в коде.

Репозиторий (repo) — это хранилище версий кода какого-то проекта**.** В репозитории есть журнал коммитов, которые были добавлены в него. У репозитория могут быть разные ветки — у каждого своя история и происхождение. По умолчанию основная ветвь называется «мастер». Как правило, весь готовый код объединяется в мастер.

Форк (fork) — клон репозитория. В копии репозитория можно вносить свои собственные изменения, редактировать файлы. Например, вы решили внести изменения в чей-то репозиторий, внесли, а теперь можете поделиться им и отправить автору оригинального репозитория. Это будет считаться запросом на слияние и называться pull request.

Вот, смотрите, справа от Scala иконка форкнутого репозитория.

Issue — это условные карточки-задачи, которые вы можете создавать, чтобы отслеживать работу над багами, внедрение новых функций или других запросов. Как тикеты в Trello.

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

Contribution — это действия пользователя Github, по которым считается его активность на платформе:

• commit в мастер-ветку;
• открытие issue;
• предложение сделать pull request;
• отправка pull request на проверку.

Что ещё важно знать?

Давайте вернемся к вопросу: что такое Github в принципе. Это платформа, где разработчики и компании (да, в том числе) могут хранить проекты, редактировать их вместе. Но мы видим только часть репозиториев — те, что доступны всем.

Итак, пример. Разработчик, который активен на Github (у него регулярно что-то появляется), является автором или участником крупного проекта с открытым исходным кодом (open source). Делаем вывод, что, скорее всего, у него большой разработки на языке проекта. То есть активность и ценность вклада разработчика в целом рассказывает нам об уровне его навыков.

Но! Не каждый разработчик использует Github, и не каждый может — есть много компаний, которые запрещают ребятам участвовать в open source проектах.

На что обратить внимание в профиле?

1. Стек
Github — идеальный инструмент, чтобы узнать больше про технологический стек. Вы можете просто посмотреть, репозиториев с какой технологией больше всего или над чем он работал в последнее время.
И тут вам пригодятся вот эти инструменты:

Github User Languages

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

Github Awards

Инструмент, который поможет понять, какое мест о в рейтинге вообще занимает разработчик.

Profile Summary for Github

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