Участие в проекте Hugo

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

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

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

Изменения в кодовой базе и связанной документации, например, для новой функции, всё равно должны использовать один запрос на вытягивание.

Содержание

• Запросы поддержки
• Отчёты об ошибках
• Отправка исправлений
  • Рекомендации по внесению кода
  • Руководство по написанию сообщений Git Commit
  • Получение источников с GitHub
  • Сборка Hugo с вашими изменениями

Запросы поддержки

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

Отчёты об ошибках

Если вы считаете, что обнаружили дефект в Hugo или его документации, используйте трекер проблем GitHub, чтобы сообщить о проблеме сопровождающим Hugo. Если вы не уверены, ошибка это или нет, начните с вопроса на форуме для обсуждения. Сообщая о проблеме, пожалуйста, укажите версию используемого Hugo (hugo version) и вашу операционную систему.

• Проблемы Hugo · gohugoio/hugo
• Документация Hugo · gohugoio/hugoDocs
• Тема веб-сайта Hugo · gohugoio/hugoThemesSite

Вклад в код

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

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

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

Рекомендуется открыть обсуждение на Форуме Hugo, чтобы получить отзывы о вашей идее, прежде чем вы начнёте. Если вы отправляете сложную функцию, создайте небольшое проектное предложение в системе отслеживания проблем Hugo, прежде чем начать.

Обратите внимание, что мы не принимаем новые функции, требующие CGO. У нас есть одно исключение из этого правила — LibSASS.

Исправления ошибок, конечно, всегда приветствуются.

Отправка исправлений

Проект Hugo приветствует всех участников независимо от уровня навыков или опыта. Если вы заинтересованы в помощи проекту, мы поможем вам с вашим вкладом.

Рекомендации по внесению кода

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

Чтобы сделать процесс внесения вклада максимально плавным, мы просим следующее:

• Идите вперёд и разветвите проект и внесите свои изменения. Мы призываем к запросам на вытягивание. Разрешить обсуждение и анализ изменений в коде.

• Когда вы будете готовы создать запрос на включение (pull request), обязательно:*

  • Подпишите CLA.
  • Создайте тестовые случаи для нового кода. Если у вас есть вопросы о том, как это сделать, пожалуйста, задайте их в своём запросе на включение.
  • Запустите go fmt.
  • Добавьте документацию, если вы добавляете новые функции или изменяете функциональность. Сайт с документацией находится в /docs.
  • Объедините свои коммиты в один коммит. git rebase -i. Можно принудительно обновить свой запрос на включение с помощью git push -f.
  • Убедитесь, что mage check успешно завершён. Travis CI (Windows, Linux и macOS) не сможет собрать проект, если mage check завершится неудачно.
  • Следуйте приведённым ниже правилам оформления сообщений Git Commit.

Правила оформления сообщений Git Commit

Эта статья в блоге — хороший ресурс для изучения того, как писать хорошие сообщения коммитов. Самое важное правило заключается в том, что каждое сообщение коммита должно иметь заголовок/тему в повелительном наклонении, начинающуюся с заглавной буквы и без точки в конце: «Return error on wrong use of the Paginator», НЕ «returning some error.»

Также, если ваш коммит ссылается на одну или несколько проблем GitHub, всегда заканчивайте тело сообщения коммита словами See #1234 или Fixes #1234. Замените 1234 на идентификатор проблемы GitHub. Последний пример закроет проблему, когда коммит будет объединён с master.

Иногда имеет смысл предварить сообщение коммита именем пакета (или папки docs), все строчные буквы заканчиваются двоеточием. Это нормально, но остальные правила выше применяются. Таким образом, это «tpl: Add emojify template func», а не «tpl: add emojify template func.», и «docs: Document emoji», а не «doc: document emoji».

Пожалуйста, используйте краткое и описательное имя ветки, например, НЕ «patch-1». Это очень распространено, но создаёт конфликт имён каждый раз, когда запрос на включение извлекается для проверки.

Пример:

tpl: Добавить пользовательскую функцию индекса

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

Исправлено #1949

Получение источников с GitHub

С Hugo 0.48 Hugo использует поддержку Go Modules, встроенную в Go 1.11, для сборки. Проще всего клонировать Hugo в каталог вне GOPATH, как в следующем примере:

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install

Примечание: Некоторые инструменты Go могут ещё не полностью поддерживать Go Modules. Одним из примеров может быть LiteIDE. Следуйте этому обходному пути, чтобы продолжить работу с Hugo ниже GOPATH.

Для некоторых удобных целей сборки и тестирования также необходимо установить Mage:

go get github.com/magefile/mage

Теперь, чтобы внести изменения в исходный код Hugo:

1. Создайте новую ветку для своих изменений (имя ветки произвольное):

   git checkout -b iss1234

2. После внесения изменений зафиксируйте их в новой ветке:

   git commit -a -v

3. Вилка Hugo на GitHub.

4. Добавьте свою вилку в качестве нового удалённого (название удалённого, «fork» в этом примере, произвольно):

   git remote add fork git@github.com:USERNAME/hugo.git

5. Отправьте изменения на новый удалённый сервер:

   git push --set-upstream fork iss1234

6. Теперь вы готовы отправить PR на основе новой ветки в вашем разветвлённом репозитории.

Сборка Hugo с вашими изменениями

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

cd $HOME/go/src/github.com/gohugoio/hugo

Чтобы собрать Hugo:

mage hugo

Чтобы установить hugo в $HOME/go/bin:

mage install

Чтобы запустить тесты:

mage hugoRace
mage -v check

Чтобы вывести список всех доступных команд вместе с descriptions:

mage -l

Note: From Hugo 0.43 мы добавили тег сборки extended, который добавляет поддержку SCSS. Для сборки требуется установленный компилятор C. Вы можете включить эту функцию при сборке с помощью команды:

HUGO_BUILD_TAGS=extended mage install