Как выпускать AspectJ

AspectJ собирается и выпускается с помощью Maven. На момент написания в корневой папке проекта есть Maven-обёртка, указывающая на Maven 3.6.3, но мы будем использовать простые команды mvn вместо ./mvnw, предполагая, что на вашей работной станции установлена локальная версия Maven. Вы можете легко заменить одну команду на другую.

При развертывании окончательных выпусков на Sonatype OSSRH используется плагин Nexus Staging Maven вместо плагина Maven Deploy. Это помогает создать временное хранилище для выпуска и позже разместить его на Maven Central без необходимости входа в веб-интерфейс Sonatype Nexus. Всё можно сделать из командной строки.

Снапшоты не требуют размещения в временном хранилище и отдельного выпуска, в этом случае для них подходит плагин Maven Deploy. Так что начнём с простого случая:

Выпуск снапшотов

Чтобы опубликовать снапшот, настройте свои учетные данные в ~/.m2/settings.xml примерно так:

<settings>
  <servers>
    <server>
      <id>ossrh</id>
      <username>USERNAME</username>
      <password>PASSWORD</password>
    </server>
  </servers>
</settings>

Затем просто выполните:

mvn clean deploy 

# ИЛИ: Если вы уже запустили тесты локально или CI-процесс на GitHub
mvn -DskipTests clean deploy 

# ИЛИ: Ускорьте процесс, пропустив генерацию документации. В зависимости от вашей оболочки, вам может не потребоваться 
# экранировать символ '!', чтобы деактивировать профиль 'create-docs'. В случае (Git) Bash это необходимо.
mvn -P \!create-docs -DskipTests clean deploy 
```Это размещает только основные артефакты:
  - AspectJ runtime `aspectjrt-[VERSION].jar`,
  - AspectJ tools/compiler `aspecttools-[VERSION].jar`,
  - AspectJ weaver `aspectjweaver-[VERSION].jar`,
  - AspectJ matcher `aspectjmatcher-[VERSION].jar`.

AspectJ installer (`installer/target/aspectj-[VERSION].jar`) должен быть опубликован отдельно, если вы хотите сделать его доступным для публики для этого снапшота.

Чтобы использовать AspectJ снапшот, опубликованный таким образом, используйте репозиторий OSSRH в POM зависимого проекта:

```xml
<repository>
  <id>ossrh</id>
  <url>https://oss.sonatype.org/content/repositories/snapshots</url>
</repository>

Публичные выпуски (milestone, release candidate, final)

Выпущенные артефакты такие же, как и для снапшотов, но процедура требует нескольких дополнительных шагов. Я объясняю руководство по ручной версионированию без использования плагина Maven Release. Это может работать и с Maven Release, т.е.:

• установка версии выпуска во всех POM,
• сборка выпуска,
• запуск тестов (может быть пропущен),
• коммитирование POM выпуска,
• тегирование выпуска,
• развертывание выпуска,
• установка следующей версии снапшота во всех POM,
• коммитирование POM снапшотов,
• отправка предыдущих коммитов и тега выпуска в удалённый репозиторий Git.

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

# Убедитесь, что вы используете JDK 16, так как генерация javadoc зависит от версии JDK
# и может вызвать неожиданные ошибки на других версиях
java -version
# java version "16" 2021-03-16 (...)

# Проверьте, что вы работаете в чистом рабочем каталоге.
# Не должно быть ни staged, ни unstaged, ни.untracked файлов.
git status

# Установите версию выпуска во всех POM
mvn versions:set -DnewVersion=1.9.8.M2

# Проверьте, что изменения POM корректны, затем удалите файлы резервных копий POM
mvn versions:commit
```# Соберите и разверните выпуск в репозитории Nexus для стадии.
 # Профиль 'release' активирует:
 #   - плагин Maven GPG для подписи артефактов (готовьтесь ввести ваш пароль).
 #     На Windows, графический диалог для ввода пароля должен появиться с последней версией GnuPG.
 #     В случае ошибки 'Failed to execute goal org.apache.maven.plugins:maven-gpg-plugin:1.6:sign',
 #     попробуйте 'export GPG_TTY=$(tty)' перед выполнением команды.
 #   - плагин Maven Javadoc
 #   - плагин Nexus Staging Maven
 # Профиль 'create-docs' убедится, что будут сгенерированы документы AspectJ для включения в установщик.
 # По желанию, используйте '-DskipTests', если вы уже запустили все тесты.
 mvn -P release,create-docs clean deploy
 ```Если эта команда была выполнена успешно, это означает, что мы создали временное репозиторий на Sonatype OSSRH, загрузили все артефакты
 и все предварительные проверки на сервере Sonatype прошли успешно, то есть если POM-файлы содержат всю необходимую информацию и если
 в сборке прикреплены артефакты исходного кода и javadoc. Теперь остался только один шаг — выпустить временное репозиторий в Maven Central. На самом деле, плагин Nexus Staging Maven также можно настроить для развертывания и выпуска в Maven Central в одном команде, но
 для того чтобы дать вам возможность вручную скачать и проверить артефакты из стейджингового репозитория, по умолчанию
 конфигурация плагина в родительском POM выглядит так: `<autoReleaseAfterClose>false</autoReleaseAfterClose>`. Изменение значения на`true` приведет к прямому выпуску в Maven Central, если все предыдущие шаги были выполнены успешно.Перед тем как мы выпустим стейджинговый репозиторий, мы хотим сделать коммит и тег для выпуска, а затем установить новую версию снапшота:

```shell
# Сделать коммит релизных POM в Git (лучше сделать это из вашей IDE, проверив
# изменения перед тем, как добавить их в Git для коммита)
git commit -am "Release AspectJ 1.9.8.M2"

# Добавить тег для выпуска
git tag V1_9_8_M2

# Установить новую версию снапшота, увеличив номер версии после финального выпуска
mvn versions:set -DnewVersion=1.9.8-SNAPSHOT

# Проверить, если изменения POM верны, а затем удалить файлы резервных копий POM
mvn versions:commit

# Сделать коммит снапшотов POM в Git
git commit -am "Set version to 1.9.8-SNAPSHOT"

# Отправить предыдущие коммиты на GitHub
git push origin

# Отправить тег выпуска на GitHub
git push origin V1_9_8_M2

Хорошо, домашние дела с Git завершены. Теперь, наконец, давайте насладимся плодами нашей работы и выпустим стейджинговый репозиторий в Maven Central:

# Вероятно, мы забыли записать ID стейджингового репозитория раньше.
# Он был записан где-то в логе Maven:
#   [INFO]  * Created staging repository with ID "orgaspectj-1106".
#   [INFO]  * Staging repository at https://oss.sonatype.org:443/service/local/staging/deployByRepositoryId/orgaspectj-1106
#   ...
#   [INFO]  * Uploading locally staged artifacts to profile org.aspectj
#   [INFO]  * Upload of locally staged artifacts finished.
#   [INFO]  * Closing staging repository with ID "orgaspectj-1106".
#
# Но прокрутить вверх слишком далеко. Так что давайте просто спросим Nexus, какие стейджинговые
# репозитории есть.
mvn nexus-staging:rc-list
# [INFO] ID                   Состояние    Описание
# [INFO] orgaspectj-1106      CLOSED       org.aspectj:aspectjrt:1.9.8.M2
```# Из-за проблем в плагине Nexus Staging Maven с более новыми JDK,
# нам может потребоваться это сначала
export MAVEN_OPTS="--add-opens=java.base/java.util=ALL-UNNAMED --add-opens=java.base/java.lang.reflect=ALL-UNNAMED --add-opens=java.base/java.text=ALL-UNNAMED --add-opens=java.desktop/java.awt.font=ALL-UNNAMED"
```# Используйте ID соответствующего закрытого staging репозитория для выпуска в
# Maven Central
mvn nexus-staging:rc-release -DstagingRepositoryId=orgaspectj-1106

Та-даа! Мы выполнили выпуск AspectJ. Через несколько минут артефакты должны появиться на Maven Central где-то под https://repo1.maven.org/maven2/org/aspectj/, например, AspectJ Tools 1.9.8.M2 появится под https://repo1.maven.org/maven2/org/aspectj/aspectjtools/1.9.8.M2/. Как только вы увидите артефакты там вместо "404 not found", вы можете объявить о доступности выпуска на списке рассылки AspectJ и везде еще, где это уместно.

Наконец, не забудьте опубликовать выпуск на GitHub, прикрепив установщик AspectJ (installer/target/aspectj-[VERSION].jar) к нему.

Опубликуйте документацию на веб-сайтеСодержимое для веб-сайта AspectJ поддерживается в репозитории GitHub

eclipse-aspectj/aspectj-website. На момент написания этого текста, есть несколько базовых PHP-страниц (которые будут перенесены в простой HTML к концу 2024 года, когда поддержка PHP истечет), но основная часть документации проекта генерируется самим проектом AspectJ, то есть этим проектом. Содержимое asciidoc и другие ресурсы в модуле docs преобразуются в то, что мы хотим опубликовать на сайте. Кроме того, документация также упаковывается в установщик AspectJ и публикуется для офлайн использования. Помимо содержимого docs, мы также публикуем javadocs для API runtime и weaver.После полной сборки вы можете найти сгенерированную документацию, включая javadocs, в папке aj-build/dist/docs/doc. Документация также прикрепляется к сборкам GitHub CI, хотя на данный момент без javadocs. Содержимое попадает в папку doc/latest в репозитории сайта или может попасть в папку, названную по выпуску, если мы решим это сделать в будущем. В настоящее время мы публикуем только последнюю документацию, всегда перезаписывая предыдущую версию. Страница входа для сгенерированной документации опубликована здесь. Убедитесь, что проверили изменения перед коммитом:

• Если определенная часть документации (например, блокнот разработчика, руководство по программированию) не изменилась с точки зрения HTML, вы также не должны коммитить соответствующий PDF, даже если он может отличаться бинарно. Но если содержание HTML не изменилось, PDF должен выглядеть так же, как и раньше, если нет причин полагать обратное (например, изменения в стилях опций генератора).
• В зависимости от вашей локальной ОС и конфигурации Git, некоторые изменения могут быть вызваны различиями в разделителях строк, то есть CRLF на Windows и LF на Linux и MacOS. Пожалуйста, избегайте коммитирования таких изменений, возвращая файлы обратно и вперед. Вместо этого запустите dos2unix или unix2dos для этих файлов, чтобы устранить ненужные и, возможно, огромные изменения. * Также вы хотите выявить другие общие изменения, такие как отметки времени, годы в уведомлениях об авторских правах и т. д. Это является непрерывным процессом оптимизации таких изменений для достижения стабильной документации и маленьких коммитов. Если вы заметили что-то, убедитесь, что вы улучшите процесс сборки соответственно. После внесения изменений в репозиторий веб-сайта они должны быть опубликованы автоматически через=batch process= после небольшой задержки (обычно несколько минут).Внимание: Текущий процесс публикации зависит от быстрого обновления изменений, то есть если вы, например, измените или упростите коммиты сайта и затем вынудите их перепushing, изменения могут вообще не быть опубликованы, и вам потребуется открыть запрос в службу поддержки Eclipse, такой как этот, чтобы команда инфраструктуры вручную распространила изменения. Учитывая это, лучше не вынуждать перепushing, если это не абсолютно необходимо (например, удаление коммитов с конфиденциальной информацией).

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