Руководство для авторов

Последнее обновление 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

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

Learn more

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

Ветки¶

Разработка ориентирована на 2 ветки. 2.x, который содержит последнюю версию серии 2.x (например, 2.7 на момент написания), и 3.x, которая содержит MODX 3.

Время от времени могут быть и другие ветки. Например, может существовать ветка 2.6.x, если есть какие-либо изменения, которые необходимо перенести специально на более старые версии. Или, если разработка версии 2.8 продолжается, а 2.7 является последней выпущенной версией, для этого может быть отдельная ветка 2.7.x.

Это соответствует семантическому управлению версиями.

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

Если улучшение нарушает обратную совместимость, оно должно быть нацелено на ветку следующего основного выпуска (например, 3.x или 4.x).
Если улучшение вводит новую функциональность или включает изменения, которые влияют на то, как пользователи работают с MODX, ему необходимо нацелить ветку для младшего следующего выпуска, если эта ветка доступна (например, 2.8.x, если 2.7 является последняя) или ветка для текущего основного выпуска (например, 2.x).
Если улучшение исправляет ошибку, оно должно быть нацелено на ветку для текущего второстепенного выпуска, если эта ветка доступна (например, 2.7.x, если версия 2.7 является последней), или ветвь для текущей основной версии. выпуск (например, 2.x)

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

Ветки мажоной версии¶

Ветвь мажорной версии, например «2.x» и «3.x», по сути, являются виртуальными ветвями «master» для каждого основного выпуска MODX Revolution. Эта ветка всегда доступна и содержит новые функции, которые не нарушают обратную совместимость, предназначенную для следующего второстепенного выпуска. Вы можете думать об этом как о «ветке интеграции», куда вносятся все изменения для следующего значительного выпуска.

Когда код в этих ветвях достигает стабильной точки и готов к выпуску, фиксация помечается новым второстепенным номером выпуска, например v2.7.0, и выпуск производится на основе этого тега.

Ветви второстепенной версии¶

Ветви второстепенных версий не всегда доступны.

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

l10n ветки¶

Время от времени вы будете видеть ветки с префиксом l10n, за которым следует версия. Это ветки localisation, которые CrowdIn автоматически создает и обновляет.

Чтобы отправлять изменения лексики (перевода) для любого языка, кроме английского, используйте платформу CrowdIn вместо GitHub.

Ваш форк на GitHub¶

Первый шаг к внесению вклада в официальный репозиторий - это его форк. Это означает, что вы создадите копию репозитория под своим именем, что позволит вам вносить изменения в код.

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

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

1. Инструменты¶

Интерфейс командной строки (Терминал/iTerm/и т.д.)
Git в вашей системе
PHP Storm или другой клиент. Просто убедитесь, что вы используете 4 пробела вместо табуляции.
Какой-то веб-сервер. Предпочтительно Apache или NGINX. Мы используем боксы Vagrant, но вы также можете использовать MAMP/XAMPP.

2. Github¶

Вам понадобится учетная запись Github, которую можно создать на Github.com.
Тогда вам понадобится форк MODX Revolution. Зайдите сюда и нажмите «Fork» в правом верхнем углу.

3. Подписанное лицензионное соглашение с участниками MODX¶

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

4. Настройка файлов MODX из репозитория Git¶

Участники MODX должны работать напрямую со своими частными форками на GitHub.

Сначала клонируйте форк на локальном компьютере в каталог, который будет вашим корневым веб-каталогом.

Обратите внимание: в приведенных ниже примерах вы заметите SSH-url ([email protected]:YOURNAME/revolution.git). Github также предлагает HTTPS-ссылки, которые проще использовать, если вы новичок https://github.com/YOURNAME/revolution.git. Вы можете просто заменить их в примерах.

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

git clone [email protected]:YOURNAME/revolution.git
cd revolution

Затем добавьте original modxcms/revolution в качестве исходной. Мы обсудим использование этого позже. Прямо сейчас просто сделай это.

git remote add upstream [email protected]:modxcms/revolution.git

Теперь нам нужно проверить (прочитать: загрузить) текущую ветку разработки, которой на момент написания является 2.7.x.

git checkout 2.7.x

Убедитесь, что ваш репозиторий все еще «чистый». Убедитесь, что вы не внесли никаких изменений.

git status
On branch 2.7.x
Your branch is up-to-date with 'origin/2.7.x'.
nothing to commit, working tree clean

Если вы видите это сообщение, все в порядке. Если вы заметили изменения, значит, вы сделали что-то ужасно неправильно! Убедитесь, что он чистый и вы еще не внесли изменений в файлы. В противном случае ваши коммиты позже испортят репозиторий MODX.

Если на тот момент у вас нет чистой ветки 2.7.x, вы можете переустановить локальную ветку 2.7.x с помощью upstream/2.7.x, используя следующую команду. Вы теряете свои локальные изменения с помощью этой команды, поэтому, пожалуйста, сохраните свои изменения или сохраните их в новой ветке:

git fetch upstream
git rebase upstream/2.7.x
First, rewinding head to replay your work on top of it...
Fast-forwarded 2.7.x to upstream/2.7.x.

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

Cd в папку _build и убедитесь, что вы там ;-) Вы можете сделать это с помощью команды 'pwd'. Он покажет текущий путь.

cd _build
pwd
/your-absolute-path-here/revolution/_build

Затем нам нужно скопировать (НЕ ПЕРЕИМЕНОВАТЬ ИХ) следующие 2 файла:

cp build.config.sample.php build.config.php
cp build.properties.sample.php build.properties.php

Обычно вам не нужно изменять содержимое этих файлов, они просто должны там существовать.

Следующий шаг требует, чтобы на вашем пути был PHP. Проверьте, есть ли на вашем пути PHP, выполнив следующие действия:

php -v
PHP 7.0.15 (cli) (built: Jan 22 2017 08:51:45) ( NTS )
Copyright (c) 1997-2017 The PHP Group
Zend Engine v3.0.0, Copyright (c) 1998-2017 Zend Technologies

Если вы не получили что-то подобное, спросите кого-нибудь или Google, как его установить.

Чтобы собрать ядро MODX, выполните следующие действия из папки _build:

php transport.core.php
[2017-02-24 11:52:17] (INFO @ transport.core.php) Beginning build script processes...
[2017-02-24 11:52:17] (INFO @ transport.core.php) Removed pre-existing core/ and core.transport.zip.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Core transport package created.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Core Namespace packaged.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Default workspace packaged.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged modx.com transport provider.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 2 modMenus.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged all default modContentTypes.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged all default modClassMap objects.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 181 default events.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 225 default system settings.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 2 default context settings.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 1 default user groups.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 1 default dashboards.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 1 default media sources.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 5 default dashboard widgets.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 2 default roles Member and SuperUser.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 6 default Access Policy Template Groups.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 7 default Access Policy Templates.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in 12 default Access Policies.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in web context.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in mgr context.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Packaged in connectors.
[2017-02-24 11:52:17] (INFO @ transport.core.php) Beginning to zip up transport package...
[2017-02-24 11:52:18] (INFO @ transport.core.php) Transport zip created. Build script finished.

Execution time: 1.5657 s

Если приведенное выше показывает вам некоторые случайные проблемы с часовым поясом, это не имеет значения. Важно то, что вам нужно сообщение «Транспортный zip создан. Сценарий сборки завершен.». Если нет, поспрашивайте.

5. Выполнение настройки MODX¶

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

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

После установки измените следующие системные настройки:

friendly_urls     => Yes
use_alias_path    => Yes
publish_default   => Yes
cache_disabled    => Yes

Необязательно (но мы не предпочитаем .html-расширений). Измените Content-Type HTML. Удалите расширение файла .html. Вы можете сделать это, щелкнув «Content» в верхнем меню MODX, а затем щелкнув «Content Types».

Очистите кеш.

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

6. Рабочий процесс¶

У нас есть 2 рабочих процесса, разработанных для вас: исправление ошибок (самостоятельная разработка) и тестирование (если вы не слишком увлечены разработкой, но хотите помочь).

6A. Рабочий процесс исправления ошибок¶

1. Выберите проблему из системы отслеживания ошибок MODX ¶

2. Предотвратите дублирование работы, заявив права на нее, комментируя ее¶

Что-то вроде: «Я попробую исправить это сегодня».

3. Затем создайте ветку из вашей текущей ветки разработки (2.6.x), чтобы начать работу в своей собственной среде¶

Если проблема, которую вы хотите исправить, является функцией, назовите ее feature-ISSUENUMBER. Если это ошибка, назовите ее ПРОБЛЕМА. В этом примере мы исправим неработающую ссылку в документации. Проблема может быть найдена здесь. Номер выпуска 13309.

git checkout -b bug-13309

Далее мы исправим нашу проблему и изменим код. Если вы уверены в своих изменениях, мы хотим вернуть их на Github. Мы изменили файл core/lexicon/en/about.inc.php

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

git status
On branch bug-13309
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   core/lexicon/en/about.inc.php

no changes added to commit (use "git add" and/or "git commit -a")

Если файлы, которые вы хотите добавить в MODX, также есть в отчете о статусе выше, у вас все хорошо. Все готово! Нам нужно добавить его в нашу фиксацию и отправить в наш форк на Github. Используйте хэштег, чтобы указать на проблему и/или пометить ее для таких вещей, как MODX Bug Hunt.

git add .
git commit -m "Fixed issue #13309 #modxbughunt"
git push origin
git push --set-upstream origin bug-13309
Counting objects: 4, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 1.69 KiB | 0 bytes/s, done.
Total 4 (delta 2), reused 0 (delta 0)
remote: Resolving deltas: 100% (2/2), completed with 1 local objects.
To github.com:gpsietzema/revolution.git
* [new branch]      bug-13309 -> bug-13309
Branch bug-13309 set up to track remote branch bug-13309 from origin.

Это все, что касается командной строки! Теперь нам нужно зайти в Github, чтобы сделать Pull Request (PR).

4. Перейдите к своей вилке на Github¶

Вероятно, вы увидите сообщение, похожее на «Your recently pushed branches: bug-13309 (2 минуты назад)». Нажмите кнопку «compare & pull request».

Теперь вы видите, как сравниваются два репозитория. Слева находится modxcms/revolution, установите его в base: 2.6.x. Справа вы увидите yourname/revolution с bug-13309.

Если все в порядке, вы увидите сообщение следующего содержания: «Возможно объединение. Эти ветви можно автоматически объединять.

Пожалуйста, убедитесь, что вы ввели какое-то объяснение своего коммита для наших любимых интеграторов (людей, которые фактически объединят ваш код в MODX). Это упростит им проверку.

Как только вы это сделаете, нажмите волшебную кнопку Create pull request

Поздравляю, у вас получилось!

5. Следующий!¶

Если вы хотите исправить другую ошибку, нам сначала нужно снова оказаться в ветке 2.6.x. Для этого мы сначала хотим убедиться, что ветвь 2.6.x нашего Fork синхронизирована с исходной веткой modxcms/2.6.x. Для этого сделайте следующее:

git fetch upstream 2.6.x
git fetch origin 2.6.x
git checkout 2.6.x
git pull upstream 2.6.x

Если на последнем шаге вы получите текстовый редактор с сообщением о слиянии. Просто сохраните и выйдите из редактора, и все будет в порядке. Если это редактор VI, просто нажмите Escape, чтобы выйти из режима ввода, затем введите :wq и нажмите Enter.

Теперь вы обновили свою вилку. Затем вы можете вернуться к шагу 1 в 6a. Промыть и повторить!