Код

Последнее обновление Mar 3rd, 2021 | История страницы | Улучшить эту страницу | Сообщить о проблеме

Support the team building MODX with a monthly donation.

The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.

Backers

Budget

$301 per month—let's make that $500!

Learn more

Итак, вы хотите помочь в разработке MODX Revolution? Эта идея уже делает вас лучшим человеком на свете. =)

Здесь много работы, поэтому ваше участие в основном коде будет весьма признательно и может оказать реальное влияние на будущие выпуски MODX. Никакого давления - просто рад, что ты даже это читаешь.

В этом разделе мы проведем вас через некоторые процессы разработки исправления или новой функции для MODX.

Вы не совсем разработчик, но все же хотите помочь с кодом? Узнайте, как вы можете помочь, тестируя вклад других, сортируя проблемы, или переводя MODX на разные языки.

Лицензионное соглашение участника¶

Во-первых, немного легального. Прежде чем какое-либо улучшение может быть принято, проект MODX требует, чтобы вы подписали (в цифровой форме) Лицензионное соглашение с участниками (сокращенно CLA), что в основном означает, что вы даете проекту MODX право взять своего участника и поделиться им. Вам нужно будет сделать это только один раз, и это не займет больше нескольких минут.

При создании pull request полезный @cla-bot автоматически проверит, подписывали ли вы CLA раньше, так что вы также можете забыть об этом сейчас и вернуться к нему, когда будет предложено ботом.

Подпишите CLA здесь.

Шаг 1: найдите над чем поработать¶

Если вы пришли на эту страницу с идеей исправить что-то, что вас беспокоит: поздравляю, вы только что выполнили этот шаг! :) Перейдите к шагу 2 ниже.

Но если у вас еще нет конкретной задачи, начните с просмотра системы отслеживания проблем на GitHub. Буквально сотни открытых проблем ждут, когда кто-то возьмет на себя инициативу и исправит их.

Очевидно, что вопрос, который вам подходит, зависит от ваших скилов. Чтобы сузить круг вопросов, используйте фильтры Label и Milestone.

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

Также полезны метки state/confirmed и state/accepting-pull-request. Этот ярлык означает, что проблема была подтверждена кем-то, проводившим сортировку, и определенно заслуживает исправления. (Однако отсутствие метки не означает, что проблема не заслуживает исправления!)

Существуют также ярлыки приоритета (priority-1-urgent, priority-2-high), которые могут быть более важными проблемами.

Наконец, простой поиск темы, которая вам удобна, может помочь понять, над чем работать. Возможно, "extjs", "design", "frontend"...

Когда вы нашли свою цель, пора начинать кодить!

Шаг 2: выбор базовой ветки¶

Если вы впервые работаете над кодом Revolution, вам необходимо правильно настроить среду разработки. По сути, это экземпляр MODX, который был установлен непосредственно из git, с некоторыми дополнительными настройками, упрощающими разработку. Обычно у вас будет одна среда для каждой основной версии (2.x и 3.x), чтобы избежать многократного переключения между ними.

Далее следует выбрать базовую ветку для использования. В общем:

Исправления ошибок помещаются в ветку для текущей версии, например, 2.8.x (или 2.x, если 2.8.x не существует). Такие ветки будут доступны, время от времени будут отличаться, но правильное должно быть довольно легко определить.
Новые функции помещаются в ветку для текущего minor выпуска, например 2.x. Когда выпускается новая минорная версия, из нее создается новая ветка выпуска патча (например, 2.9.x).
Критические изменения вносятся в следующую основную ветку, например, 3.x.

Примечание: на момент написания (февраль 2021 г.) основное внимание уделялось MODX3. Это означает, что исправления ошибок для текущего выпуска должны быть помещены в 2.x, а новые функции должны быть созданы для ветки 3.x. Также большое внимание уделяется исправлению ошибок в 3.x. Это временное отклонение от приведенных выше рекомендаций и немного сбивает с толку.

После выхода версии 3.0 мы добавим отдельную ветку 3.0.x для исправлений ошибок версии 3.0, а новые функции будут нацелены на 3.x., как описано выше.

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

Шаг 3: приступайте к программированию!¶

Теперь, когда вы определились, над чем собираетесь работать и на какой ветке это будет основано, пора приступить к работе.

Еще не настроили среду разработки? Сначала следуйте этим инструкциям.

Начните с создания новой ветки проблемы/функции в вашей локальной установке git. По соглашению используется формат bug-{issue_number}, feature-{issue_number} или issue-{issue_number}, но вы можете выбрать что-то другое.

git fetch upstream
git checkout -b bug-12345 upstream/2.x

Не забудьте настроить upstream/2.x на feature/bug ветвь, если это необходимо.

Теперь займитесь поставленной задачей. В зависимости от того, над чем вы работаете, есть доступные инструменты для создания ресурсов, моделей и т.д.

Когда проблема решена или функция добавлена, зафиксируйте изменения в ветке feature/bug. Используйте git status, git add . или git add file1 file2 иgit commit -m "здесь идет сообщение о фиксации".

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

Затем отправьте свои коммиты в свой собственный форк, обычно называемый origin. Указав -u в приведенной ниже команде, он настроен на «track the remote branch», что означает, что в следующий раз вы можете просто выполнить git push без конкретных аргументов.

git push -u origin bug-12345

Результат этой команды будет выглядеть примерно так:

Counting objects: 18, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (18/18), done.
Writing objects: 100% (18/18), 111.86 KiB | 1.43 MiB/s, done.
Total 18 (delta 12), reused 0 (delta 0)
remote: Resolving deltas: 100% (12/12), completed with 9 local objects.
remote:
remote: Create a pull request for 'bug-12345' on GitHub by visiting:
remote:      https://github.com/YourUsername/revolution/pull/new/bug-12345
remote:
To github.com:YourUsername/revolution.git
 * [new branch]      bug-12345 -> bug-12345

Видите эту полезную ссылку для создания запроса на перенос? Когда вы довольны своей работой, щелкните ее, чтобы сразу перейти и создать запрос на перенос.

Шаг 4: создайте Pull Request¶

Если вы не перешли по ссылке «create a pull request» на предыдущем шаге, вы также можете перейти со своего форка на GitHub, выбрать ветку на вкладке «Code» и щелкнуть ссылки «Pull Request» или «Compare» на серой панели под селектором ветки.

При создании запроса на перенос убедитесь, что для Base Repository установлено значение modxcms/revolution, а для base установлено значение ветки, которую вы ранее выбрали в качестве базовой. GitHub не всегда автоматически выбирает правильную базовую ветку.

Head repository и head должны указывать на ваши изменения, которые должны быть предварительно заполнены.

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

Шаг 5: доведите до слияния¶

Когда вы создали pull request, он (в основном) не в ваших руках. Теперь он должен быть рассмотрен основными интеграторами и тестировщиками, что иногда может занять больше времени, чем хотелось бы.

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

Но когда ваш pull request действительно объединяется, поздравляю! :) Теперь вы являетесь частью постоянной истории MODX, а также довольно крутым человеком.

Шаг 6: промыть и повторить¶

Первый запрос на включение может показаться трудоемким. Заполнение шаблонов, git, base и head веток ... это может быть непросто.

С опытом станет легче.

Если вы застряли (особенно когда вы только начинаете!), Обратитесь за помощью. Slack (запросите приглашение здесь) - полезное место, которое до краев заполнено энтузиастами, включая разработчиков ядра и интеграторы.

Наша общая цель - сделать MODX лучше, поэтому мы будем благодарны вам за вашу помощь, независимо от того, насколько она велика или мала.

Дополнительная информация и советы¶

Новичок в git и github? См. Эту страницу для получения более общей информации и общие команды/сценарии git.
- Также есть множество онлайн-ресурсов, таких как GitHub's Git Handbook, cheatsheets, и интерактивные демонстрации ветвления git.
- Хотя существуют также пользовательские интерфейсы для git (включая встроенные во многие редакторы кода), если вы совершенно новичок, возможно, лучше сначала изучить git на терминале. Как только вы усвоите концепцию, вы можете довольно легко перенести знания о git с терминала в визуальный пользовательский интерфейс, но наоборот - сложнее.
Хотите знать, как проверяется ваш pull request? Подробнее о тестировании запросов на вытягивание ....
Стандарты кодирования можно найти здесь. Вообще говоря, придерживайтесь стандартов кодирования, используемых в коде, который вы редактируете.

Каковы шансы на принятие pull request?¶

Как правило, довольно много, но основные интеграторы тщательно проверяют pull requests. Как только запрос на вытягивание принят, он становится официальным, и его нужно будет поддерживать в обозримом будущем, поэтому интеграторы иногда могут быть осторожны.

Чтобы улучшить свои шансы:

Одно исправление или функция для каждого pull request.
Будьте отзывчивы, если вам задают вопросы или изменяют их.
Быть почтительным. Мы все проводим здесь свое время добровольно.
Прежде чем приступить к работе, убедитесь, что есть консенсус, особенно когда речь идет о новых функциях. Обсуждалось ли это раньше, и если да, то каков был результат? У разных людей могут быть разные идеи, но ядро у нас только одно.