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

Вклад в Hugo

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

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

Примечание: этот репозиторий содержит только исходный код Hugo. Для только запросов на внесение изменений в документацию используйте репозиторий hugoDocs.

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

Содержание

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

Задание вопросов поддержки

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

Сообщение об ошибках

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

• Проблемы Hugo · gohugoio/hugo
• Проблемы документации Hugo · gohugoio/hugoDocs
• Проблемы тем Hugo · gohugoio/hugoThemesSite

Вклад в код

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

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

Если функциональность имеет некоторую сложность, вкладчик ожидается поддерживать и поддерживать новую функцию в будущем (отвечать на вопросы на форуме, исправлять ошибки и т.д.). Любые значительные изменения кода должны обновлять открытые issues. Значительные изменения кода без ссылки на issue с одним из тегов bug или enhancement не будут приняты. Обратите внимание, что мы не принимаем новые функции, требующие CGO. Есть одно исключение из этого правила, а именно LibSASS.

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

Подача патчей

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

Правила вклада в код

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

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

Правила для сообщений о коммитах в Git

Этот блоговый пост является хорошим ресурсом для изучения того, как писать хорошие сообщения о коммитах. Самым важным аспектом является то, что каждое сообщение о коммите должно иметь заголовок/тему в повелительном наклоне, начинающийся с заглавной буквы и без точки в конце: "js: Возвращать ошибку, если опция x не установлена", НЕ "возвращая какую-то ошибку."

Большинство заголовков/тем должны иметь префикс в нижнем регистре с двоеточием и одним пробелом. Префикс может быть:

• Именем пакета, где (большинство) изменений были внесены (например, media: Добавить текст/calendar)
• Если имя пакета глубоко вложено/длинное, попытайтесь сократить его слева, например, markup/goldmark допустимо, resources/resource_transformers/js можно сократить до js.
• Если этот коммит затрагивает несколько пакетов с общим функциональным контекстом, используйте этот контекст в качестве префикса, например, errors: Решить правильные номера строк
• Если этот коммит затрагивает много пакетов без общего функционального контекста, используйте префикс all:, например, all: Пересоздать Go код
• Если это обновление документации, используйте префикс docs:.
• Если ни одно из вышеперечисленного не применимо, просто оставьте префикс без изменений.
• Обратите внимание, что вышеупомянутые существительные, которые можно увидеть в других репозиториях, исключены, например, "chore:". Также, если ваш коммит ссылается на один или несколько GitHub-тикетов, всегда заканчивайте тело сообщения о коммите строкой See #1234 или Fixes #1234. Замените 1234 на ID тикета в GitHub. Последний пример закроет тикет при слиянии коммита в master.

Пример:

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

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

Fixes #1949

Получение исходного кода из GitHub

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

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

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

go install 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. Теперь вы готовы отправить pull request на основе новой ветки в вашем форке.

Сборка 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

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

mage -l

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

HUGO_BUILD_TAGS=extended mage install