Как внести свой вклад в программное обеспечение с открытым исходным кодом

Как внести свой вклад в программное обеспечение с открытым исходным кодом

Это легко, весело и важно

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

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

В этой статье я буду специально говорить о запросе на перенос проекта документации Microsoft .NET. Рабочий процесс, инструменты и примеры, которые я предоставляю, будут специфичными для этого проекта и команды, которая его поддерживает, но общие концепции должны быть применимы ко многим проектам, с которыми вы сталкиваетесь.

Найдите проект, в который вы можете внести свой вклад

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

На прошлых выходных я узнал, что меня приняли в .NET Foundation. Это большое дело для вечного поклонника Microsoft (и поклонника .NET с 2001 года), и мне захотелось найти способы внести больший вклад во все, что связано с .NET.

Так случилось, что я нашел ветку в Твиттере, которая заинтересовала меня:

Я решил последовать их совету и поискать проекты документации .NET. В конце концов, писать по техническим вопросам - это всего лишь немного в моей рулевой рубке.

Выберите хороший первый выпуск

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

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

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

Если вы не знаете, над чем хотите работать, перейдите на вкладку «Проблема» в репозитории и посмотрите доступные теги. Вы хотите просмотреть проблемы, которые в настоящее время открыты и к которым применены «Хорошая первая проблема», «Готово к работе» или аналогичные теги.

Команда документации Microsoft тщательно проверила и прокомментировала все в своем бэклоге, и мне было легко найти проблемы, которые были доступны.

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

В моем случае я выбрал улучшение примеров INotifyPropertyChanged в C # и VB .NET. Код как есть был прекрасен, но .NET со временем развивается, и по мере развития появляются более эффективные способы работы. Это была моя возможность поделиться лучшими практиками в области, в которой я являюсь экспертом, поэтому я ухватился за этот шанс.

Разобраться в проблеме

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

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

Я также сделал комментарий, в котором объявил о своем намерении работать над этой проблемой, а также о предполагаемых изменениях. Частично это было сделано для того, чтобы увидеть, передаст ли команда мне задачу или попросит меня заняться другой проблемой, но ответа не последовало.

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

Несмотря на то, что вы можете клонировать репозитории локально, не создавая их, вы не сможете сделать запрос на перенос, если сначала не разветвите репозиторий.

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

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

Я большой поклонник GitKraken в качестве клиента Git, поэтому я скопировал URL-адрес и клонировал его из GitKraken, используя этот URL-адрес, но командная строка или другое приложение по вашему выбору будет работать для вас так же хорошо.

Понять рабочий процесс команды

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

К счастью, вам не нужно угадывать эти вещи в большинстве репозиториев, поскольку сообщество стандартизировало создание файла contributing.md или readme.md, который поможет вам начать работу с репозиторием, включая структуры веток и рабочий процесс git.

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

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

Прежде чем вы начнете работать в редакторе, я рекомендую создать ветку в git на основе соответствующей стартовой ветки (см. Предыдущее обсуждение). Обязательно проверьте предыдущие ветки и файлы contributing.md и / или readme.md на предмет соглашений об именах ветвей.

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

Ориентируйтесь

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

В моем случае этим редактором должен был быть Visual Studio, однако я не смог найти .sln файл в корне репозитория, поэтому я предположил, что проект вместо этого предназначался как рабочее пространство Visual Studio Code. .

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

Вы вряд ли будете работать с такой замечательной командой, как команда Microsoft Documentation (и если да, я уверен, они хотели бы услышать, что они могут улучшить).

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

Как только я начал выявлять закономерности, я начинаю искать файлы, связанные с кодом, который я собираюсь изменить.

В моем случае Microsoft снова упростила задачу, отметив их в проблеме на GitHub.

Итак, по проблеме я нашел how-to-implement-property-change-notifications.md и просмотрел файл уценки в поисках раздела, содержащего примеры кода для обновления.

То, что я обнаружил, было удивительным:

Вместо страницы, содержащей пример, он ссылался на пример из другого репозитория git, поддерживаемого командой: репозитория Samples.

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

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

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

Внесите и проверьте свои изменения

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

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

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

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

Создайте свой запрос на слияние

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

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

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

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

Обратите внимание, что в самом последнем лайке написано Fixed dotnet/docs#10675.

Это волшебная строка, которую GitHub анализирует, чтобы связать мою фиксацию с правильной проблемой (# 10675) в репозитории docs (напомним, я вносил изменения в репозиторий samples).

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

Когда будете готовы, нажмите Create pull request.

Что произойдет дальше?

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

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

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

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

Заключительные мысли

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

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

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

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

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

Первоначально опубликовано на https://killalldefects.com 26 января 2020 г.