Из-за потребностей бизнеса Youzan создал много колес, особенно библиотеки компонентов, включая React, Vue и небольшие программы.Другие проекты с открытым исходным кодом включаютzan-proxyпрокси, фреймворк для PHPzanphpЖдать. Некоторым может быть интересно, зачем Youzan делать так много колес? На самом деле причина очень проста, потому что существующие альтернативы не могут удовлетворить потребности нашего собственного бизнеса, они могут не соответствовать нашим потребностям в настройке или функции могут не соответствовать нашим требованиям. В соответствии с потребностями бизнеса мы обобщили набор подпрограмм и спецификаций, подходящих для себя, и превратили эти подпрограммы и спецификации в инструменты, библиотеки компонентов или фреймворки.
Это, вероятно, причина, по которой Youzan начал эти проекты внутри компании. Позже, с постепенным улучшением этих проектов, естественной идеей будет открыть их исходный код, возможно, у других есть такие же потребности, как и у нас.
Потихоньку на любимом Github появляется много проектов с открытым исходным кодом. В процессе поддержки этих проектов с открытым исходным кодом мы обобщили некоторые извлеченные уроки и поделились ими с вами здесь.
1. Понравилось использование Github
Github имеет определенные социальные атрибуты. Помимо хорошо написанного кода, также очень важно поддерживать проект с открытым исходным кодом. Некоторые положения также очень важны. Мы суммируем некоторые моменты, чтобы поделиться с вами.
1. Хороший README важен
Файл README - это первое впечатление о проекте.Так называемые люди полагаются на одежду и лошадей.Очень важно, чтобы проект с открытым исходным кодом имел хорошее лицо, особенно когда проект все еще является фронтенд-проектом. Вот несколько предложений для файлов README:
- Единый формат для README от одной организации
- Лучше иметь английскую версию README
- Плюс ссылка на руководство разработчика
Преимущество унификации формата README заключается в том, что другие могут с первого взгляда определить, что этот проект принадлежит определенной компании или определенной компании, а спецификация README поддерживается внутри компании. Содержание шаблона очень простое, но это гарантирует, что наш проект будет иметь определенную степень узнаваемости.
Английская версия README не предназначена для принуждения.Если вы уверены, что все ваши пользователи находятся в Китае, вам нужна только китайская версия README. Но в большинстве случаев мейнтейнеры проекта надеются, что их код сможет помочь большему количеству людей, в том числе и иностранным пользователям.В настоящее время отражается ценность англоязычного README.
Руководство разработчика легко игнорировать, оно существует, чтобы помочь разработчикам, которые хотят присоединиться к разработке проекта, быстро приступить к работе. Как разработчики, работающие над проектами с открытым исходным кодом, чего они ожидают от руководств по разработке? Я думаю, не более чем несколько моментов:
- Как построить среду разработки?
- С какими открытыми вопросами вам нужна помощь?
- Как отправить код?
Если руководство по разработке сможет ответить на эти вопросы, опытные разработчики смогут быстрее принять участие.
2. Эффективно используйте шаблоны Github Issue и PR.
Я думаю, что многие сталкивались с таким конфузом: кто-то поднял вопрос на Github, но вы не можете понять описание проблемы и не знаете, как воспроизвести проблему.
Github предоставляет специалистам проекта механизм предварительного написания шаблона для Issue или PR, а другие могут изменить этот шаблон, когда они придут, чтобы поднять Issue или PR. Шаблон может быть нацелен на то, чтобы сообщить эмитенту, кто должен заполнить информацию, чтобы в большинстве случаев можно было избежать неловкой сцены, упомянутой выше.
Создание этих шаблонов также просто,общий путьОн заключается в создании соответствующего Markdown-файла шаблона в скрытой директории .github хранилища. Недавно Github только что обновил механизм шаблонов, что позволяет одновременно создавать несколько шаблонов Issue/PR.
Например, шаблон задачи в репозитории babel имеет несколько шаблонов, и каждый шаблон соответствует разным типам задач.здесь.
3. Labels
Функция Labels в Github в основном используется для классификации Issue/PR, что удобно для индексации и поиска. Главное здесь в том, что метки, созданные Github по умолчанию, не просты в использовании, мы рекомендуем разделить метку на несколько ортогональных, каждая размерность соответствует нескольким различным меткам, вы можете обратиться кэта статья.
Многие новички, как правило, игнорируют функцию «Ярлык». При правильной классификации ярлыков каждый выпуск может иметь очень интуитивно понятное отображение статуса.
4. Система непрерывной интеграции
Интеграция Github и системы CI очень близка, и я лично считаю, что опыт очень хороший. Систему непрерывной интеграции можно использовать для модульного тестирования, проверки стиля кода и т. д. Данные о покрытии кода в файлах README во многих репозиториях генерируются и фиксируются в системе CI.
Помимо одностороннего запуска, CI также можно использовать для других необходимых проверок кода. НапримерZentВ репозитории есть скрипт, который проверит написан ли присылаемый код в соответствии со спецификациями на CI.Если формат кода окажется неверным, то очень вероятно, что разработчик не установил наш git hook локально . В это время мы предложим разработчику установить его локально. Подцепите, отформатируйте код и повторите отправку.
#!/bin/bash
# Ensure everyone installs the git hook.
# The result is a guess, but false positive
# is not an issue here.
RED='\033[0;31m'
basepath=$(dirname $0)
fail () {
printf "${RED}$@\nAborting\n"
exit -1
}
pushd $basepath/.. >/dev/null 2>&1
yarn prettify
git diff-index --quiet HEAD --
rv=$?
popd >/dev/null 2>&1
if [ $rv -ne 0 ]; then
git diff-index HEAD --
fail 'Git hooks not installed. Follow these instructions on your local machine:\n1. yarn install\n2. yarn prettify\n3. Commit your changes and push.'
fi
Вот, кстати, об опыте использования двух систем CI, обычно используемых на Github:
- Стабильность службы Travis относительно хорошая, а сборка Travis PR выполняется на основе результата слияния исходной ветки и текущей ветки PR.
- CircleCI имеет хорошую производительность, но стабильность относительно низкая, и иногда это отстой.
Github недавно добавил новую функциюChecks API, эту функцию можно рассматривать как обновленную версию оригинальной интеграции PR и CI, и вы можете увидеть более подробные тесты и отчеты Lint.
5. Контроль выполнения проекта
На GitHub есть два инструмента управления проектами: Milestone и Project. Project может отображать функцию, подобную канбану, в то время как Milestone является более легким, похожим на инструмент управления сроками для коллекций задач. Для большинства проектов с открытым исходным кодом больше подходит Milestone.
2. Обмен навыками
Выше приведены некоторые навыки использования Github, а также несколько советов по разработке, выпуску и обслуживанию проекта. Проект с открытым исходным кодом — это отнюдь не просто набор кодов, это технический продукт, который требует от нас смотреть на эту проблему с точки зрения требований к продукту.
1. Выпуски версий соответствуют спецификациям экосистемы.
Взяв в качестве примера внешний интерфейс, большинство пакетов в экосистеме NPM используютSemantic VersioningДа, если пакет нашего проекта не соответствует этому правилу, пользователю легко преподнести "сюрприз". Не беспокойтесь о том, что номер версии становится все больше и больше, это просто число.
2. Спецификации кода
Я считаю, что пока это зрелый проект, он должен иметь свои собственные спецификации кодирования.Некоторые проекты могут предоставлять документы, чтобы сообщить участникам кода, как кодировать, а также будут соответствующие проверки, чтобы убедиться, что код соответствует требованиям. технические характеристики. Однако, если это просто спецификация стиля кода, мы рекомендуем использовать инструменты для обеспечения реализации спецификации. Мы не предоставляем документацию по соглашениям о написании кода, но у нас есть сценарии для форматирования всего представленного кода. В результате код может быть написан как угодно, но финальная отправка в основную ветку должна быть написана в соответствии с той же спецификацией.
Существует много таких инструментов форматирования, например, те, которые используются во внешнем интерфейсе.Prettier, который поставляется с языком Gogofmt, и причиныrefmtЖдать. Найдите время в Google и найдите инструмент форматирования, который подойдет для вашего проекта.
3. Squash Merging
Github предоставляет PRТри варианта слияния, рекомендуется включать только слияние сквоша. Так называемое сквош-слияние означает слияние всех коммитов в ветке PR в новый коммит, а затем быстрое слияние коммита в целевую ветку Мы считаем этот метод наиболее подходящим для PR-проектов. Конечно, если вы хотите сохранить каждую запись коммита в PR, рекомендуется использовать метод перебазирования, будь то операция Github или ваша собственная локальная перебазировка перед отправкой.
4. Список изменений
Чтобы уменьшить нагрузку на каждый выпуск, наши предыдущие журналы изменений автоматически генерировались сценариями на основе Github Issues и PR-записей. Однако постепенно мы обнаружили, что читабельность журнала изменений стала плохой из-за плохой стандартизации названия Issue и PR. Другая проблема заключается в том, что созданный машиной список изменений не может группировать изменения одного и того же компонента вместе, что также является одной из причин плохой читабельности.
Наш текущий журнал изменений заключается в создании «черновика» с помощью сценария, а затем издатель пакета обобщает и извлекает на его основе легко читаемый журнал изменений. Этот метод увеличивает нагрузку на некоторых издателей, но удобочитаемость журнала изменений значительно улучшается, а соотношение ввода-вывода остается приемлемым.
5. Сервисное обслуживание технических изделий.
«Послепродажное обслуживание» — это самый упускаемый момент при работе над проектами с открытым исходным кодом.Если мы поддерживаем проект с открытым исходным кодом в соответствии с требованиями технических продуктов, то мы несем ответственность за оказание необходимой поддержки пользователям. Эта поддержка включает в себя: исчерпывающую документацию по продуктам, группы вопросов и ответов и некоторые технические блоги по продуктам. С помощью этих «послепродажных услуг» мы можем сформировать полный замкнутый цикл технических продуктов и постоянно улучшать их благодаря отзывам пользователей.
3. Резюме
Эта статья начинается с позиции использования Github и делится некоторыми опытом обслуживания проектов с открытым исходным кодом, которые мы считаем правильными с точки зрения разработки проекта, выпуска, обслуживания и создания документов. Мы всегда открыты и приветствуем ваши предложения по улучшению управления проектами с открытым исходным кодом.
приложение
Некоторые потенциально полезные ссылки на инструменты:
- lerna: Инструмент управления монорепозиторием
- github-changelog-generator: Инструмент автоматической генерации журнала изменений
- conventional-changelog: Еще один генератор журнала изменений
- git-labelmaker: Автоматически создавать ярлыки Github.