У вас есть некоторый опыт веб-разработки, но вы не знаете, как начать вносить свой вклад в проект с открытым исходным кодом?
Это был я несколько дней назад. Есть много ресурсов о том, что внести свой вклад в качестве первого проекта. Этот совет, например, Кент С. Доддс, запомнил меня долгое время:
Вы делаете лучший вклад в то, что используете регулярно
Это все хорошо. Но я не мог найти много подробных руководств о том, как люди действительно начинают вносить свой вклад. Итак, сегодня я собираюсь рассказать вам, как я воспользовался советом Кента, и покажу вам, как именно я начал свой путь к открытому исходному коду.
Что это значит для вас?
Из этой статьи вы узнаете:
- что вам не нужно быть исключительно умным или хорошо разбираться в проекте, чтобы начать вносить свой вклад
- какие файлы проверять в первую очередь в новом проекте 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.