У вас есть некоторый опыт веб-разработки, но вы не знаете, как начать вносить свой вклад в проект с открытым исходным кодом?

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

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

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

Что это значит для вас?

Из этой статьи вы узнаете:

  • что вам не нужно быть исключительно умным или хорошо разбираться в проекте, чтобы начать вносить свой вклад
  • какие файлы проверять в первую очередь в новом проекте JavaScript и как ориентироваться в большом репозитории с открытым исходным кодом
  • как запустить vue-next модульные тесты
  • о структуре пакета vue-next

Репо Vue 3 уже доступно

Эван Ю выпустил для публики vue-next, который в будущем станет Vue 3. В настоящее время он находится на стадии предварительной альфа-версии, а это значит, что он еще не завершен. Это более быстрая, компактная и удобная в обслуживании переписанная среда Vue на TypeScript. Поскольку мне нравится использовать Vue, я проверил vue-next, чтобы подробнее узнать о новых функциях.

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

Базовая настройка

Только люди из команды Vue могут отправлять запросы на вытягивание непосредственно из репозитория vue-next. Все остальные должны создать вилку репозитория, нажав кнопку вилки в графическом интерфейсе GitHub. Разветвляя проект, вы копируете полную историю проекта в свою учетную запись GitHub. Затем вы можете протестировать его, внести некоторые изменения и, возможно, отправить запрос на изменение.

После создания вилки я клонировал ее на свой локальный компьютер, чтобы отредактировать исходный код и использовать более мощные функции поиска моей доверенной IDE:

git clone https://github.com/your-user-name/vue-next

Затем я добавил исходное репозиторий vue-next в качестве исходного репозитория, чтобы я мог синхронизировать его с моим репозиторием, если новые изменения будут зафиксированы в исходном репозитории.

git remote add upstream https://github.com/vuejs/vue-next.git

Если вы хотите синхронизировать новые изменения, просто выполните следующие команды git в главной ветке вилки:

git pull upstream master
git push

Начать обучение

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

Руководство по участию

Первое, что вам следует найти в своей среде IDE, - это файлы README.md и вспомогательное руководство.

vue-next Руководство для участников предоставит вам информацию о:

  • настройка разработки и как запускать тесты
  • vue-next структура проекта и общий обзор пакетов
  • рекомендации по запросу на вытягивание и как отформатировать коммит
  • как Lerna помогает управлять всеми пакетами Vue в монорепозитории

package.json

Есть и более мелкие проекты, чем Vue. В этих проектах участвует лишь небольшое количество людей, и из-за этого часто нет руководства. Чтобы узнать больше о проекте, полезно взглянуть на root package.json, который определяет рабочий процесс разработки и технический стек.

В разделе scripts вы можете найти команды разработки, которые мы уже видели в вспомогательном руководстве:

  • build: компилирует и объединяет файлы машинописного текста с объединением в один файл JavaScript.
  • dev: смотреть все файлы и восстанавливать, если они меняются
  • lint: лучше работает с каждым файлом TypeScript
  • test: запускает шутливые тесты

Вы также можете узнать больше о том, как vue-next использует git-hooks с yorkie для линтинга вашего зафиксированного кода и проверки того, что вы следуете рекомендациям по сообщениям коммита.

devDependencies показывает технический стек проекта. Из этого раздела мы можем узнать, что vue-next использует typescript (как и было обещано), rollup для объединения файлов в единую точку входа для браузера и lerna для управления вложенными репозиториями.

Структура проекта

На момент написания в vue-next monorepo было девять подпакетов. В каждом таком пакете также есть один package.json файл, в котором в разделе dependencies объявлены внутренние зависимости. Давайте нарисуем внутренний график зависимостей пакетов, чтобы взглянуть на структуру пакета:

По сравнению с Vue 2, пакеты намного более модульны и могут быть установлены независимо в будущем. Одной из основных причин для этого было облегчение разработки собственных сред выполнения (iOS, Android,…). Такие пакеты будут просто использовать абстракцию ядра времени выполнения, чтобы получить базовую реактивность, а также функции жизненного цикла Vue, но затем улучшить их с помощью собственного кода. На данный момент уже существует пакет runtime-test. Он используется для запуска тестов без использования среды, подобной браузеру.

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

Копаем глубже - пакет реактивности

Пакеты без внутренних зависимостей - это пакеты shared, compiler-core и reactivity. Пакет shared содержит только базовые функции, такие как isObject, которые вы можете найти в любом проекте, поэтому меня это не особо интересовало. Пакет compiler-core имеет некоторые внешние зависимости, которые вам нужно понять, и я не хотел углубляться в это. Итак, я начал с пакета reactivity.

Чтобы получить общий обзор пакета reactivity, я просмотрел файл README пакета. К сожалению, это не дало много информации о конкретной реализации этого пакета. Затем давайте посмотрим на тесты, чтобы собрать больше информации:

Обучение с помощью тестов

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

  • вычислен
  • эффект
  • реактивный
  • только чтение
  • ссылка

Некоторые из них уже опубликованы в Composition API RFC, который является прекрасным чтением о Vue 3.

При дальнейшем изучении тестов было обнаружено: код, в который я мог внести свой вклад. Вот отрывок из WeakSet.spec.ts, как было раньше:

Вы можете заметить ошибку?

Тест экземпляра WeakSet не проверяет, является ли он экземпляром WeakSet, а вместо этого снова проверяет нормальный Set. Это простая ошибка копирования и вставки.

Как внести свой вклад?

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

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

Для моего конкретного случая я создал новую ветку:

git checkout -b test/reactivity-collections

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

Я повторно провожу тесты (только для пакета реактивности, потому что я фиксировал только там тесты):

yarn test reactivity

Все прошло!

Теперь я попытался зафиксировать свою работу:

git commit -am "fixed a small copy & paste mistake in the reactivity/collections tests"

О нет, что случилось? Мне было представлено довольно пугающее сообщение об ошибке:

ERROR invalid commit message format.
Proper commit message format is required for automated changelog generation. Examples:
feat(compiler): add ‘comments’ option
  fix(v-model): handle events on blur (close #28)
See .github/commit-convention.md for more details.
You can also use npm run commit to interactively generate a commit message.

Это был хук vue-next commit-msg: он не проверял мое сообщение о фиксации, потому что не соответствовал соглашениям о фиксации.

Я быстро исправил это и снова совершил:

git commit -am "test(reactivity): fixed small copy & paste error"
git push -u origin test/reactivity-collections

Вернувшись в GitHub, его графический интерфейс сразу же спросил меня, хочу ли я отправить это изменение как запрос на перенос в основной проект vue-next. И я так и сделал. После того, как их CI-конвейер и человек по имени znck (член команды Vue) подтвердили мои изменения, через несколько часов он был объединен Эваном Ю.

Это было не так сложно, как я ожидал, и я надеюсь внести больший вклад, узнав больше о Vue. Теперь твоя очередь!

«Но у меня недостаточно опыта, чтобы внести свой вклад!»

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

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

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

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

  • статья Кента С. Доддса, в которой он также рассказывает о своем первом вкладе в открытый исходный код
  • Небольшой совет от Дэна Абрамова: просто наблюдайте за всей активностью GitHub для vue-next (верхний правый угол в графическом интерфейсе)
  • исчерпывающее руководство о том, почему и как внести свой вклад

Заключение

Из этой статьи вы узнали:

  • как получить общий обзор проекта с открытым исходным кодом
  • новая и улучшенная структура пакета vue-next
  • как сделать pull-реквест специально для vue-next
  • что никакой вклад не слишком мал
  • что изучение вашего любимого программного обеспечения с открытым исходным кодом - хороший способ начать работу с открытым исходным кодом

Следующие темы

Следующее сообщение в блоге будет немного более техническим. Мы углубимся в новый пакет reactivity и узнаем больше о прокси-серверах ES6, символах и WeakMaps.