This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-changes-plugin.git
The following commit(s) were added to refs/heads/master by this push:
new 5b3a90c Refresh the site documentation and README
5b3a90c is described below
commit 5b3a90ce71c06d51cf73a500341468500d8e4b58
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Wed Nov 18 07:32:33 2026 +0000
Refresh the site documentation and README
---
README.md | 115 ++++++---------
src/site/changes/sample-changes.xml | 2 +-
.../examples/alternate-changes-xml-location.md.vm | 5 +-
.../examples/changes-file-validation.md.vm | 7 +-
.../markdown/examples/check-changes-file.md.vm | 4 +-
.../examples/configuring-github-report.md.vm | 30 ++--
.../examples/configuring-trac-report.md.vm | 35 ++---
.../examples/customizing-jira-report.md.vm | 25 +++-
.../examples/include-announcement-file.md.vm | 3 +-
.../markdown/examples/smtp-authentication.md.vm | 12 +-
.../markdown/examples/specifying-mail-sender.md.vm | 4 +-
.../using-a-custom-announcement-template.md.vm | 17 ++-
src/site/markdown/faq.md | 31 ++--
src/site/markdown/index.md | 114 ++++++++++----
src/site/markdown/usage.md.vm | 164 +++++++++++----------
src/site/markdown/using-changes-xsd.md | 7 +-
src/site/site.xml | 13 +-
17 files changed, 319 insertions(+), 269 deletions(-)
diff --git a/README.md b/README.md
index f861da9..d58eed5 100644
--- a/README.md
+++ b/README.md
@@ -14,70 +14,51 @@
See the License for the specific language governing permissions and
limitations under the License.
-->
-Contributing to [Apache Maven Changes
Plugin](https://maven.apache.org/plugins/maven-changes-plugin/)
-======================
-
-[][license]
-[](https://search.maven.org/artifact/org.apache.maven.plugins/maven-changes-plugin)
-[][build]
-[][test-results]
-
-
-You have found a bug, or you have an idea for a cool new feature? Contributing
-code is a great way to give something back to the open source community. Before
-you dig right into the code, there are a few guidelines that we need
-contributors to follow so that we can have a chance of keeping on top of
-things.
-
-Getting Started
----------------
-
-+ Make sure you have a [GitHub account](https://github.com/signup/free).
-+ If you're planning to implement a new feature, it makes sense to discuss
your changes
- on the [dev list][ml-list] first.
- This way you can make sure you're not wasting your time on something that
isn't
- considered to be in Apache Maven's scope.
-+ Submit a ticket for your issue, assuming one does not already exist.
- + Clearly describe the issue, including steps to reproduce when it is a bug.
- + Make sure you fill in the earliest version that you know has the issue.
-+ Fork the repository on GitHub.
-
-Making and Submitting Changes
---------------
-
-We accept Pull Requests via GitHub. The [developer mailing list][ml-list] is
the
-main channel of communication for contributors.
-There are some guidelines which will make applying PRs easier for us:
-+ Create a topic branch from where you want to base your work (this is usually
the master branch).
- Push your changes to a topic branch in your fork of the repository.
-+ Make commits of logical units.
-+ Respect the original code style: by using the same [codestyle][code-style],
- patches should only highlight the actual difference, not being disturbed by
any formatting issues:
- + Only use spaces for indentation.
- + Create minimal diffs - disable on save actions like reformat source code
or organize imports.
- If you feel the source code should be reformatted, create a separate PR
for this change.
- + Check for unnecessary whitespace with `git diff --check` before committing.
-+ Make sure you have added the necessary tests (JUnit/IT) for your changes.
-+ Run all the tests with `mvn -Prun-its verify` to assure nothing else was
accidentally broken.
-+ Submit a pull request to the repository in the Apache organization.
-
-If you plan to contribute on a regular basis, please consider filing a
[contributor license agreement][cla].
-
-Additional Resources
---------------------
-
-+ [Contributing
patches](https://maven.apache.org/guides/development/guide-maven-development.html#Creating_and_submitting_a_patch)
-+ [Contributor License Agreement][cla]
-+ [General GitHub documentation](https://help.github.com/)
-+ [GitHub pull request
documentation](https://help.github.com/send-pull-requests/)
-+ [Apache Maven X Account](https://x.com/ASFMavenProject)
-+ [Apache Maven Bluesky Account](https://bsky.app/profile/maven.apache.org)
-+ [Apache Maven Mastodon
Account](https://mastodon.social/deck/@[email protected])
-
-[license]: https://www.apache.org/licenses/LICENSE-2.0
-[ml-list]: https://maven.apache.org/mailing-lists.html
-[code-style]: https://maven.apache.org/developers/conventions/code.html
-[cla]: https://www.apache.org/licenses/#clas
-[maven-wiki]: https://cwiki.apache.org/confluence/display/MAVEN/Index
-[test-results]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master/lastCompletedBuild/testReport/
-[build]:
https://ci-maven.apache.org/job/Maven/job/maven-box/job/maven-changes-plugin/job/master/
+
+# Apache Maven Changes Plugin
+
+[](https://www.apache.org/licenses/LICENSE-2.0)
+[](https://central.sonatype.com/artifact/org.apache.maven.plugins/maven-changes-plugin)
+[](https://github.com/apache/maven-changes-plugin/actions/workflows/maven-verify.yml)
+
+Tells your users what changed between releases. The plugin reads the changes
from a `changes.xml` file in the
+project or from an issue tracker (JIRA, GitHub or Trac), renders them as site
reports, and generates a release
+announcement that it can also send by email.
+
+```shell
+mvn changes:changes # report from src/changes/changes.xml
+mvn changes:github-changes # report from the GitHub issues in
<issueManagement>
+mvn changes:changes-validate # validate changes.xml against its schema
+mvn changes:announcement-generate # write target/announcement/announcement.vm
+```
+
+The plugin requires Maven 3.9.0 or later and Java 8 or later.
+
+- Documentation: <https://maven.apache.org/plugins/maven-changes-plugin/>
+- Issues: <https://github.com/apache/maven-changes-plugin/issues>
+- Mailing lists: <https://maven.apache.org/mailing-lists.html>
+
+## Build
+
+```shell
+mvn verify
+```
+
+Integration tests run with the `run-its` profile. The JIRA, GitHub and mail
tests use local mock servers:
+
+```shell
+mvn -Prun-its verify
+```
+
+Build the site with the sample reports:
+
+```shell
+mvn install -DskipTests
+mvn site -Preporting
+```
+
+## Contributing
+
+Open an issue or a pull request on GitHub. Before you push, run `mvn
spotless:apply` and `mvn -Prun-its verify`. Larger
+changes are best discussed on the [developer mailing
list](https://maven.apache.org/mailing-lists.html) first. See
+the [guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html) for more.
diff --git a/src/site/changes/sample-changes.xml
b/src/site/changes/sample-changes.xml
index 879bd2d..4394c6f 100644
--- a/src/site/changes/sample-changes.xml
+++ b/src/site/changes/sample-changes.xml
@@ -18,7 +18,7 @@ under the License.
-->
<document xmlns="http://maven.apache.org/changes/2.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/changes/2.0.0
http://maven.apache.org/xsd/changes-2.0.0.xsd">
+ xsi:schemaLocation="http://maven.apache.org/changes/2.0.0
https://maven.apache.org/xsd/changes-2.0.0.xsd">
<properties>
<title>Sample Changes Report: Title</title>
<author email="[email protected]">Johnny R. Ruiz III</author>
diff --git a/src/site/markdown/examples/alternate-changes-xml-location.md.vm
b/src/site/markdown/examples/alternate-changes-xml-location.md.vm
index e3202a6..bd0a9f0 100644
--- a/src/site/markdown/examples/alternate-changes-xml-location.md.vm
+++ b/src/site/markdown/examples/alternate-changes-xml-location.md.vm
@@ -26,9 +26,10 @@ under the License.
# Alternate Location for the `changes.xml` File
-**Note:** Unless you have a specific reason to have your `changes.xml` file in
a different location, we advice you to put it in the default location
`${esc.d}{basedir}/src/changes/changes.xml`. If nothing else, it saves you from
having to configure it.
+**Note:** Unless you have a specific reason to have your `changes.xml` file in
a different location, we advise you to put it in the default location
`${esc.d}{basedir}/src/changes/changes.xml`. If nothing else, it saves you from
having to configure it.
-If you _really_ want to have your `changes.xml` in another location than the
default location, you can do this by configuring your `pom.xml`. In this
example we want to use the file `${esc.d}{basedir}/src/site/changes.xml`:
+If you want to have your `changes.xml` in another location, set `<xmlPath>` in
your `pom.xml`. The goals
+`changes-validate`, `changes-check` and `announcement-generate` have the same
parameter. In this example we want to use the file
`${esc.d}{basedir}/src/site/changes.xml`:
```xml
<project>
diff --git a/src/site/markdown/examples/changes-file-validation.md.vm
b/src/site/markdown/examples/changes-file-validation.md.vm
index 9720859..b60aae1 100644
--- a/src/site/markdown/examples/changes-file-validation.md.vm
+++ b/src/site/markdown/examples/changes-file-validation.md.vm
@@ -26,7 +26,12 @@ under the License.
# Validate Your changes.xml File
-Since 2.1, a [goal](../changes-validate-mojo.html) is provided to validate
your `changes.xml` file.
+The [changes-validate](../changes-validate-mojo.html) goal validates your
`changes.xml` file against the
+[XML schema](../using-changes-xsd.html). You can also run it from the command
line:
+
+```
+mvn changes:changes-validate
+```
You can attach this goal to the `pre-site` phase if you want the validation to
be performed automatically when you generate the site.
diff --git a/src/site/markdown/examples/check-changes-file.md.vm
b/src/site/markdown/examples/check-changes-file.md.vm
index 4f7599b..1f7777d 100644
--- a/src/site/markdown/examples/check-changes-file.md.vm
+++ b/src/site/markdown/examples/check-changes-file.md.vm
@@ -26,7 +26,9 @@ under the License.
# Check Your changes.xml File
-Since version 2.4 this plugin has a [goal](../changes-check-mojo.html) that
checks that your `changes.xml` file has a valid release date.
+The [changes-check](../changes-check-mojo.html) goal checks that your
`changes.xml` file has a release for the
+current project version and that its release date is valid. Set
`<skipSnapshots>` to `true` to skip the check for
+`-SNAPSHOT` versions.
You can attach this goal to the `verify` phase if you want the check to be
performed automatically when you build the project.
diff --git a/src/site/markdown/examples/configuring-github-report.md.vm
b/src/site/markdown/examples/configuring-github-report.md.vm
index 75dd7ac..b3c02b7 100644
--- a/src/site/markdown/examples/configuring-github-report.md.vm
+++ b/src/site/markdown/examples/configuring-github-report.md.vm
@@ -26,17 +26,21 @@ under the License.
# Configuring the GitHub Report
-**Note:** See the [goal documentation](../github-changes-mojo.html) for
detailed info on which feature was added in which version.
+The `github-changes` report reads the issues of the repository named in
`<issueManagement>/<url>`, which must look
+like `https://github.com/OWNER/REPO/issues/`. See the [goal
documentation](../github-changes-mojo.html) for all
+parameters.
Using GitHub Enterprise
-----------------------
-Additional configurations are not needed. Address of your **GitHub** instance
will be taken from `project -> issueManagement -> url`
+No additional configuration is needed. The address of your **GitHub** instance
is taken from
+`<issueManagement>/<url>` in your POM.
Authenticating to the GitHub REST API
-------------------------------------
-If you are using GitHub Enterprise or you want to authenticate to GitHub,
configure the server in settings.xml like so:
+Anonymous requests to the GitHub REST API have a low rate limit. If you are
using GitHub Enterprise or you want to
+authenticate to GitHub, configure the server in `settings.xml` like so:
```xml
<settings>
@@ -51,20 +55,22 @@ If you are using GitHub Enterprise or you want to
authenticate to GitHub, config
</settings>
```
-Only the `password` item is used as your token for `Authorization: Bearer
YOUR-TOKEN`
+Only the `password` item is used, as the token in `Authorization: Bearer
YOUR-TOKEN`. It can be
+[encrypted](https://maven.apache.org/guides/mini/guide-encryption.html).
The default serverId is `github`. You can change it by setting the
`<githubAPIServerId>` configuration parameter.
-[Authenticating to the REST
API](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
+See [Authenticating to the REST
API](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
+in the GitHub documentation.
Filtering Issues
----------------
-We'll start off by creating a GitHub Report for one or more versions of your
project. There are two ways to do this.
+By default the report includes open and closed issues, but only issues that
have a milestone.
#[[### Only include closed issues]]#
-If you only want to include closed issues in your report make sure to
configure the includeOpenIssues to false in your configuration, which is true
by default.
+If you only want to include closed issues in your report, set
`<includeOpenIssues>` to `false`. It is `true` by default.
```xml
<project>
@@ -88,7 +94,8 @@ If you only want to include closed issues in your report make
sure to configure
#[[### Include issues without milestones]]#
-If you only want to include issues that do not have a milestone attached to
them in your report make sure to configure the onlyMilestoneIssues to false in
your configuration, which is true by default.
+If you also want to include issues that do not have a milestone attached to
them, set `<onlyMilestoneIssues>` to
+`false`. It is `true` by default.
```xml
<project>
@@ -112,7 +119,7 @@ If you only want to include issues that do not have a
milestone attached to them
#[[### Using the current version]]#
-If you are lazy and only ever want the latest release in you GitHub Report,
you can use the `<onlyCurrentVersion>` configuration parameter. It will take
the version from your project's POM and try to match it against the milestone
title of the GitHub issues.
+If you only ever want the current release in your GitHub Report, you can use
the `<onlyCurrentVersion>` configuration parameter. It will take the version
from your project's POM and try to match it against the milestone title of the
GitHub issues.
Once you have configured this, you can forget about it, as it updates itself
when you change the version number in your POM.
@@ -141,7 +148,8 @@ Once you have configured this, you can forget about it, as
it updates itself whe
Selecting columns
-----------------
-You can select which columns to include in the report.
+You can select which columns to include in the report. Valid columns for
GitHub are `Assignee`, `Created`,
+`Fix Version`, `Id`, `Reporter`, `Status`, `Summary`, `Type` and `Updated`.
```xml
<project>
@@ -153,7 +161,7 @@ You can select which columns to include in the report.
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <columnNames>Type,Key,Summary,Assignee,Status,Fix
Version</columnNames>
+ <columnNames>Type,Id,Summary,Assignee,Status,Fix
Version</columnNames>
</configuration>
...
</plugin>
diff --git a/src/site/markdown/examples/configuring-trac-report.md.vm
b/src/site/markdown/examples/configuring-trac-report.md.vm
index e8d0ed2..c48a591 100644
--- a/src/site/markdown/examples/configuring-trac-report.md.vm
+++ b/src/site/markdown/examples/configuring-trac-report.md.vm
@@ -26,27 +26,31 @@ under the License.
# Configuring the Trac Report
+**Note:** The Trac integration is deprecated and prepared for removal in the
next major version due to lack of
+maintainers.
+
Configuring your Trac instance
------------------------------
-The plugin needs to be told details of your Trac installation so that it can
connect and query the open tickets. The Trac installation needs to be
accessible via no authentication, basic authentication or NTLM authentication.
If you've used form authentication then you are out of luck.
+The plugin needs to be told details of your Trac installation so that it can
connect and query the open tickets. The Trac installation needs to be
accessible via no authentication, basic authentication or NTLM authentication.
+Form-based authentication is not supported.
Your Trac installation needs to have the [XML-RPC
plugin](https://trac-hacks.org/wiki/XmlRpcPlugin) installed and working for
this plugin to be able to read the tickets.
#[[### Basic Report Configuration]]#
-The most basic report configuration is read from the `<issueManagement>`
section of your POM. This should work with no additional configuration, but by
default all ticket will be listed
+The most basic report configuration is read from the `<issueManagement>`
section of your POM. This works with no additional configuration, but by
default all tickets are listed.
```xml
<issueManagement>
<system>trac</system>
- <url>http://mytracserver.local/trac/MYPROJECT/</url>
+ <url>https://trac.example.com/trac/MYPROJECT/</url>
</issueManagement>
```
#[[### Configuring a Custom Query]]#
-The exact query can configured in the `<query>` element. See
[TracQuery](https://trac.edgewall.org/wiki/TracQuery) for the exact syntax.
+The exact query can be configured in the `<query>` element. See
[TracQuery](https://trac.edgewall.org/wiki/TracQuery) for the exact syntax.
```xml
...
@@ -91,24 +95,5 @@ If you have your Trac sitting behind Apache on Windows with
mod_sspi doing authe
#[[### Using custom encoding]]#
-If you have to support non-western encodings, then specify an
`<outputEncoding>` in the configuration.
-
-```xml
-<project>
- ...
- <reporting>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-changes-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- ...
- <outputEncoding>Windows-31J</outputEncoding>
- </configuration>
- </plugin>
- </plugins>
- </reporting>
- ...
-</project>
-```
+The report has no encoding parameter of its own. It is written in the output
encoding of the site, which you set
+with the `outputEncoding` parameter of the [Maven Site
Plugin](https://maven.apache.org/plugins/maven-site-plugin/site-mojo.html).
diff --git a/src/site/markdown/examples/customizing-jira-report.md.vm
b/src/site/markdown/examples/customizing-jira-report.md.vm
index 0a32cb9..883b38e 100644
--- a/src/site/markdown/examples/customizing-jira-report.md.vm
+++ b/src/site/markdown/examples/customizing-jira-report.md.vm
@@ -26,7 +26,9 @@ under the License.
# Customizing the JIRA Report
-**Note:** Most of the features used in this document were introduced in
version **2.0** of the Changes Plugin. See the [goal
documentation](../jira-changes-mojo.html) for detailed info on which feature
was added in which version.
+The `jira-changes` report reads issues through the JIRA REST API. See the
[goal documentation](../jira-changes-mojo.html)
+for all parameters. For a private JIRA instance, put the credentials in a
`<server>` of your `settings.xml` and refer
+to it with `<jiraServerId>`.
Selecting version(s)
--------------------
@@ -35,7 +37,8 @@ We'll start off by creating a JIRA Report for one or more
versions of your proje
#[[### Using fix version id(s)]]#
-This is the manual way of doing it. You specify one or more fix version ids,
separated by commas. The version ids are usually five digit numbers, but that
depends on your JIRA installation.
+This is the manual way of doing it. You specify one or more fix versions,
separated by commas, either by name or by
+JIRA's internal version id.
The good thing about this method is that you can specify exactly which
versions you want, but you have to remember to update your configuration for
every new release that you want to include in the report.
@@ -49,7 +52,7 @@ The good thing about this method is that you can specify
exactly which versions
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <fixVersionIds>13722,12515</fixVersionIds>
+ <fixVersionIds>2.12,2.12.1</fixVersionIds>
</configuration>
...
</plugin>
@@ -61,7 +64,7 @@ The good thing about this method is that you can specify
exactly which versions
#[[### Using the current version]]#
-If you are lazy and only ever want the latest release in you JIRA Report, you
can use the `<onlyCurrentVersion>` configuration parameter. It will take the
version from your project's POM and try to match it against the "Fix for"
version of the JIRA issues.
+If you only ever want the current release in your JIRA Report, you can use the
`<onlyCurrentVersion>` configuration parameter. It will take the version from
your project's POM and try to match it against the "Fix for" version of the
JIRA issues.
Once you have configured this, you can forget about it, as it updates itself
when you change the version number in your POM.
@@ -90,7 +93,9 @@ Once you have configured this, you can forget about it, as it
updates itself whe
Selecting columns
-----------------
-If you are a fan of the Issue Navigator in JIRA, you are going to love this.
You can select which columns to include in the report and also specify in which
way the issues are sorted.
+You can select which columns to include in the report and also specify in
which way the issues are sorted. Valid
+columns for JIRA are `Assignee`, `Component`, `Created`, `Fix Version`, `Id`,
`Key`, `Priority`, `Reporter`,
+`Resolution`, `Status`, `Summary`, `Type`, `Updated` and `Version`.
In this example we have selected a couple of extra columns, that are not
included by default. We want the issues sorted by `Type` first and by `Key`
secondly. The keys will be sorted in descending order thanks to the `DESC`
marker. Normally they are sorted in ascending order.
@@ -150,9 +155,13 @@ You can also filter by `<component>` and `<priorityIds>`.
See the [goal document
#[[### Using JIRA syntax]]#
-Another way to filter and sort issues is to configure the plugin using a JIRA
syntaxed filter. You can grab this from the URL if you filter and sort issues
in the Issue Navigator in JIRA. Just remember that you have to escape the
ampersand (&) characters, when you put them into the XML based POM.
+Another way to filter and sort issues is to give the plugin a complete
[JQL](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/)
+query in `<filter>`. You can copy it from the advanced search in JIRA. The
query replaces everything the plugin would
+otherwise build, including the project, the version and the other filter
parameters above, so it must name the project
+itself. Remember to escape `&`, `<` and `>` characters when you put them into
the XML based POM.
-In this example we are filtering out issues with _Fixed_ as resolution and
sorting them by _type_, in ascending order.
+In this example we are only including issues with _Fixed_ as resolution and
sorting them by _type_, in ascending
+order.
```xml
<project>
@@ -164,7 +173,7 @@ In this example we are filtering out issues with _Fixed_ as
resolution and sorti
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
-
<filter>resolution=1&sorter/field=issuetype&sorter/order=ASC</filter>
+ <filter>project = MCHANGES AND fixVersion = 2.12.1 AND resolution =
Fixed ORDER BY issuetype ASC</filter>
</configuration>
...
</plugin>
diff --git a/src/site/markdown/examples/include-announcement-file.md.vm
b/src/site/markdown/examples/include-announcement-file.md.vm
index 9f19de3..0b35411 100644
--- a/src/site/markdown/examples/include-announcement-file.md.vm
+++ b/src/site/markdown/examples/include-announcement-file.md.vm
@@ -26,7 +26,8 @@ under the License.
# Include an Announcement File in Your Packaging
-Since version 2.4 this plugin has options that allows you to put the generated
announcement file anywhere you like. This makes it possible to include the
generated announcement in your packaging.
+The `announcement-generate` goal can put the generated announcement file
anywhere you like. This makes it possible
+to include the generated announcement in your packaging.
Configuring the Plugin
----------------------
diff --git a/src/site/markdown/examples/smtp-authentication.md.vm
b/src/site/markdown/examples/smtp-authentication.md.vm
index 4b1c872..79a3188 100644
--- a/src/site/markdown/examples/smtp-authentication.md.vm
+++ b/src/site/markdown/examples/smtp-authentication.md.vm
@@ -26,9 +26,10 @@ under the License.
# SMTP Authentication
-If the SMTP host needs authentication, you can provide your `<username>` and
`<password>` in the `<configuration>` section:
+If the SMTP host needs authentication, you can provide your `<username>` and
`<password>` in the `<configuration>`
+section. Use `<sslMode>` for SMTPS or `<startTls>` for STARTTLS:
-```
+```xml
<project>
...
<build>
@@ -38,9 +39,10 @@ If the SMTP host needs authentication, you can provide your
`<username>` and `<p
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <smtpHost>mail.yourhost.com</smtpHost>
- <smtpPort implementation="java.lang.Integer">25</smtpPort>
- <username>[email protected]</username>
+ <smtpHost>mail.example.com</smtpHost>
+ <smtpPort>587</smtpPort>
+ <startTls>true</startTls>
+ <username>[email protected]</username>
<password>somepassword</password>
...
</configuration>
diff --git a/src/site/markdown/examples/specifying-mail-sender.md.vm
b/src/site/markdown/examples/specifying-mail-sender.md.vm
index 59b4d1f..099626c 100644
--- a/src/site/markdown/examples/specifying-mail-sender.md.vm
+++ b/src/site/markdown/examples/specifying-mail-sender.md.vm
@@ -40,7 +40,7 @@ To specify which developer is used to send the announcement,
simply specify the
<developer>
<id>jsmith</id>
<name>John Smith</name>
- <email>[email protected]</email>
+ <email>[email protected]</email>
</developer>
...
</developers>
@@ -86,7 +86,7 @@ If you want to specify the sender explicitly and not rely on
the `developers` se
<configuration>
<mailSender>
<name>Release Notification</name>
- <email>[email protected]</email>
+ <email>[email protected]</email>
</mailSender>
</configuration>
</plugin>
diff --git
a/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
b/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
index 9155c9f..8579168 100644
--- a/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
+++ b/src/site/markdown/examples/using-a-custom-announcement-template.md.vm
@@ -31,9 +31,9 @@ The `announcement-generate` goal uses a
[Velocity](https://velocity.apache.org/)
Configuring the Plugin
----------------------
-First you must configure the plugin and tell it where your template is. In
this example we want to use the template
`${esc.d}{basedir}/src/main/resources/our-announcements/my-announcement.vm`.
+First you must configure the plugin and tell it where your template is. In
this example we want to use the template
`${esc.d}{basedir}/src/announcement/my-announcement.vm`. A directory outside
`src/main/resources` keeps the template out of your JAR file.
-**Note:** The `<templateDirectory>` must be a subdirectory of
`${esc.d}{basedir}/src/main/resources/`.
+**Note:** The `<templateDirectory>` is relative to the project base directory,
`${esc.d}{basedir}`.
```xml
<project>
@@ -46,7 +46,7 @@ First you must configure the plugin and tell it where your
template is. In this
<version>${project.version}</version>
<configuration>
<template>my-announcement.vm</template>
- <templateDirectory>our-announcements</templateDirectory>
+ <templateDirectory>src/announcement</templateDirectory>
</configuration>
</plugin>
</plugins>
@@ -58,7 +58,8 @@ First you must configure the plugin and tell it where your
template is. In this
Creating Your Template
----------------------
-Next you want to create your own template. A wise thing is to start with the
default one that is included in the plugin. You can download it from
[here](https://github.com/apache/maven-changes-plugin/blob/master/src/main/resources/org/apache/maven/plugins/announcement/announcement.vm).
It will provide you with examples on how to iterate over the actions of a
release among other things.
+Next you want to create your own template. A wise thing is to start with the
default one that is included in the plugin. You can find it in the source
repository:
+[announcement.vm](https://github.com/apache/maven-changes-plugin/blob/master/src/main/resources/org/apache/maven/plugins/changes/announcement/announcement.vm).
It will provide you with examples on how to iterate over the actions of a
release among other things.
Available Variables
-------------------
@@ -67,7 +68,7 @@ Here's a list of the variables that you have at your
disposal, when creating you
|Variable|Type|Since|Description|
|:---|:---|:---|:---|
-|releases*|List|2.0|All the releases from either the changes.xml file or from
JIRA.|
+|releases*|List|2.0|All the releases from the changes.xml file or the issue
tracker.|
|groupId*|String|2.0|The groupId from your project's pom.|
|artifactId*|String|2.0|The artifactId from your project's pom.|
|version*|String|2.0|The version from your project's pom.|
@@ -75,10 +76,10 @@ Here's a list of the variables that you have at your
disposal, when creating you
|release*|Release|2.0|The release that you are announcing.|
|project*|MavenProject|2.1|The Maven Project being released.|
|url|String|2.0|Distribution url of the artifact. **Default value is**:
`${esc.d}{project.url}`.|
-|introduction|String|2.0|A short description or introduction of the released
artifact. **Default value is**: `${esc.d}{project.description}`.|
+|introduction|String|2.0|A short description or introduction of the released
artifact. **Default value is**: `${esc.d}{project.description}`, or `url` if
that is empty.|
|developmentTeam|String|2.0|Name of the team that develops the artifact.
**Default value is**: `${esc.d}{project.name} team`.|
|finalName|String|2.0|The name of the artifact to be used in the announcement.
**Default value is**: `${esc.d}{project.build.finalName}`.|
-|urlDownload|String|2.0|URL where the artifact can be downloaded. **Default
value is**: `${esc.d}{project.url}`.|
+|urlDownload|String|2.0|URL where the artifact can be downloaded. No default
value.|
|announceParameters|Map|2.1|A Map of custom parameters that can be specified
in the plugin's configuration.|
[Variables marked with \* are read-only.]
@@ -109,4 +110,4 @@ Finally each `Action` has the following variables:
Velocity Context contains all default tools provided by the
[ToolManager](https://velocity.apache.org/tools/devel/standalone.html). See the
[Tools Usage
Summary](https://velocity.apache.org/tools/devel/tools-summary.html) for
further details.
-For information on how to access variables in your template and more, see the
[Velocity user
guide](https://velocity.apache.org/engine/devel/developer-guide.html).
+For information on how to access variables in your template and more, see the
[Velocity user guide](https://velocity.apache.org/engine/devel/user-guide.html).
diff --git a/src/site/markdown/faq.md b/src/site/markdown/faq.md
index 11b5c9b..5551073 100644
--- a/src/site/markdown/faq.md
+++ b/src/site/markdown/faq.md
@@ -26,33 +26,28 @@ under the License.
# Frequently Asked Questions
1. [What's the difference between the changes-maven-plugin at Mojo and this
one?](#question1)
-2. [I get a `org.xml.sax.SAXParseException`, when generating the JIRA Report.
What can do about it?](#question2)
+2. [I get a `org.xml.sax.SAXParseException` when generating the JIRA Report.
What can I do about it?](#question2)
+3. [Why does the Changes Report link to the wrong issue URL?](#question3)
<a id="question1"></a>
### What's the difference between the changes-maven-plugin at Mojo and this
one?
-This plugin started out at [the Mojo project](http://mojo.codehaus.org/). In
March of 2006 the plugin was moved
-to Apache and the Maven sandbox. So it's the same plugin, but this one is
newer.
+This plugin started out at the Mojo project (now
[MojoHaus](https://www.mojohaus.org/)). In March of 2006 the plugin
+was moved to Apache. So it's the same plugin, and this one is the maintained
version.
<a id="question2"></a>
-### I get a `org.xml.sax.SAXParseException`, when generating the JIRA Report.
What can do about it?
+### I get a `org.xml.sax.SAXParseException` when generating the JIRA Report.
What can I do about it?
-If you have a lot of entities in the xml file returned from your JIRA
installation, you might get an error like
-this one, when you run the JIRA Report:
+Old versions of the plugin downloaded issues as XML from JIRA and could hit
the parser's entity expansion limit.
+The plugin now reads issues through the JIRA REST API, which returns JSON, so
this error no longer occurs. Upgrade to
+the latest version of the plugin.
-```
-org.xml.sax.SAXParseException: Parser has reached the entity expansion limit
"64,000" set by the Application.
-```
+<a id="question3"></a>
-If that happens you need to tell the xml parser to use a higher limit. This
can be accomplished by adding a
-command line parameter. In the following example we have set it to double the
original value:
+### Why does the Changes Report link to the wrong issue URL?
-```
-mvn -DentityExpansionLimit=128000 ...
-```
-
-Unfortunately we have not been able to set this in Java. If someone knows how
to do this, then please reopen
-[MCHANGES-75](https://issues.apache.org/jira/browse/MCHANGES-75), and tell us
how. It would be nicer if this
-could be set using a parameter in the POM.
+The link is built from `<issueManagement>/<url>` with the last `/` and
everything after it removed. For GitHub, end
+the URL with a slash (`https://github.com/example/project/issues/`). See
+[Linking to Your Issue Management
System](./usage.html#Linking_to_Your_Issue_Management_System).
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 10e20d4..5d1567b 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -25,63 +25,113 @@ under the License.
-->
# Apache Maven Changes Plugin
-This plugin is used to inform your users of the changes that have occurred
between different releases of your project. The plugin can extract these
changes, either from a `changes.xml` file or from an issue management system
(Jira, Trac and GitHub supported), and presents them as a report.
-You also have the option of creating a release announcement and even sending
it via email to your users.
+The Changes Plugin tells your users what changed between releases of your
project. It reads the changes either
+from a `changes.xml` file that you keep in the project, or from an issue
tracker (JIRA, GitHub or Trac), and turns
+them into a site report or a plain-text release announcement.
+
+Most users come for one of these tasks:
+
+- Publish a changes report built from `src/changes/changes.xml`. Add the
`changes` report to the `<reporting>`
+ section and run `mvn site`, or run the report on its own:
+
+ ```
+ mvn changes:changes
+ ```
+
+- Publish a report of the issues in your tracker, here GitHub (configured in
`<issueManagement>`):
+
+ ```
+ mvn changes:github-changes
+ ```
+
+- Check `changes.xml` against the schema and make sure the release you build
has a release date:
+
+ ```
+ mvn changes:changes-validate changes:changes-check
+ ```
+
+- Generate a release announcement text in `target/announcement/`, and
optionally send it by email:
+
+ ```
+ mvn changes:announcement-generate
+ ```
+
+The plugin requires Maven 3.9.0 or later and Java 8 or later.
## Goals Overview
-- [changes:announcement-mail](./announcement-mail-mojo.html) send a release
announcement via email.
-- [changes:announcement-generate](./announcement-generate-mojo.html) generate
a release announcement.
-- [changes:changes-check](./changes-check-mojo.html) check that the
`changes.xml` file contains a valid release date.
-- [changes:changes-validate](./changes-validate-mojo.html) validate the
`changes.xml` file.
-- [changes:changes](./changes-mojo.html) create a report from `changes.xml`
file.
-- [changes:jira-changes](./jira-changes-mojo.html) create a report from issues
downloaded from [JIRA](https://www.atlassian.com/software/jira/).
-- [changes:trac-changes](./trac-changes-mojo.html) create a report from issues
downloaded from [Trac](https://trac.edgewall.org/).
-- [changes:github-changes](./github-changes-mojo.html) create a report from
issues downloaded from [GitHub](https://github.com/).
+- [changes:changes](./changes-mojo.html) creates a report from the
`changes.xml` file.
+- [changes:github-changes](./github-changes-mojo.html) creates a report from
issues downloaded from
+ [GitHub](https://github.com/).
+- [changes:jira-changes](./jira-changes-mojo.html) creates a report from
issues downloaded from
+ [JIRA](https://www.atlassian.com/software/jira).
+- [changes:trac-changes](./trac-changes-mojo.html) creates a report from
issues downloaded from
+ [Trac](https://trac.edgewall.org/). Deprecated, see
[below](#Deprecate_Trac_integration).
+- [changes:changes-validate](./changes-validate-mojo.html) validates the
`changes.xml` file against its XML schema.
+- [changes:changes-check](./changes-check-mojo.html) checks that the
`changes.xml` file contains a valid release date
+ for the current version.
+- [changes:announcement-generate](./announcement-generate-mojo.html) generates
a release announcement.
+- [changes:announcement-mail](./announcement-mail-mojo.html) generates the
release announcement and sends it by email.
+- [changes:help](./help-mojo.html) displays help information on the plugin.
+
+The goals `changes-report`, `github-report`, `jira-report` and `trac-report`
are deprecated aliases of the report
+goals above; see [Report goals and output
names](#Report_goals_and_output_names).
+
## Usage
-General instructions on how to use the Changes Plugin can be found on the
[usage page](./usage.html). Some more specific use cases are described in the
examples given below.
+General instructions on how to use the Changes Plugin can be found on the
[usage page](./usage.html). Some more
+specific use cases are described in the examples given below.
-In case you still have questions regarding the plugin's usage, please have a
look at the [FAQ](./faq.html) and feel free to contact the [user mailing
list](./mailing-lists.html). The posts to the mailing list are archived and
could already contain the answer to your question as part of an older thread.
Hence, it is also worth browsing/searching the [mail
archive](./mailing-lists.html).
+If you still have questions about the plugin's usage, have a look at the
[FAQ](./faq.html) and contact the
+[user mailing list](./mailing-lists.html). The posts to the mailing list are
archived and could already contain the
+answer to your question as part of an older thread.
-If you feel like the plugin is missing a feature or has a defect, you can fill
a feature request or bug report in our [issue
tracker](./issue-management.html). When creating a new issue, please provide a
comprehensive description of your concern. Especially for fixing bugs it is
crucial that the developers can reproduce your problem. For this reason, entire
debug logs, POMs or most preferably little demo projects attached to the issue
are very much appreciated. Of course, patches are wel [...]
+If the plugin is missing a feature or has a defect, file a feature request or
bug report in our
+[issue tracker](./issue-management.html). Especially for bugs, the developers
need to be able to reproduce your
+problem, so a small demo project or a debug log (`mvn -X`) helps a lot. Pull
requests are welcome, too: contributors
+can check out the project from our [source repository](./scm.html) and find
more information in the
+[guide to helping with
Maven](https://maven.apache.org/guides/development/guide-helping.html).
## Migration to 3.x
### changes.xml - schema changes
-- you should update schema in your changes.xml to `2.0.0` - [Using the XML
Schema](./using-changes-xsd.html).
-- tag `action/dueto` - was removed, you can put your data into existing
`due-to` and `due-to-email` attributes of `action` tag, which can be comma
separated.
-- tag `action/fixedIssues` - was changed to an attribute `fixed-issues` of
**action** tag, it also can be comma separated.
-### Report goals and output names
+- Update the schema in your `changes.xml` to `2.0.0`; see [Using the XML
Schema](./using-changes-xsd.html).
+- The element `action/dueto` was removed. Put its data into the `due-to` and
`due-to-email` attributes of the
+ `action` element, which accept comma-separated lists.
+- The element `action/fixedIssues` was changed to the attribute `fixed-issues`
of the `action` element, which also
+ accepts a comma-separated list.
-The reports output filename and goals name were changed for alignment with
other reporting plugins from `org.apache.maven.plugins`.
+### Report goals and output names
-See the following table for changes:
+The report goals and their output file names were renamed in line with the
other reporting plugins from
+`org.apache.maven.plugins`. The old goal names still work but are deprecated.
-|goal name|output name|
-|:---|:---|
-|changes-report -> changes|changes-report.html -> changes.html|
-|github-report -> github-changes|github-report.html ->
github-changes.html|
-|jira-report -> jira-changes|jira-report.html -> jira-changes.html|
-|trac-report -> trac-changes|trac-report.html -> trac-changes.html|
+|Old goal name|New goal name|Old output name|New output name|
+|:---|:---|:---|:---|
+|changes-report|changes|changes-report.html|changes.html|
+|github-report|github-changes|github-report.html|github-changes.html|
+|jira-report|jira-changes|jira-report.html|jira-changes.html|
+|trac-report|trac-changes|trac-report.html|trac-changes.html|
### Deprecate Trac integration
-**Trac** integration is prepared for removal in next major version due to lack
of maintainers.
+The **Trac** integration is prepared for removal in the next major version due
to lack of maintainers. The
+`trac-changes` goal is deprecated already.
## Examples
-To provide you with better understanding of some usages of the Changes Plugin,
you can take a look at the following examples:
+To provide you with better understanding of some usages of the Changes Plugin,
you can take a look at the following
+examples:
- [Alternate Location for the `changes.xml`
File](./examples/alternate-changes-xml-location.html)
- [Check Your `changes.xml` File](./examples/check-changes-file.html)
-- [Configuring the Trac Report](./examples/configuring-trac-report.html)
-- [Customizing the JIRA Report](./examples/customizing-jira-report.html)
+- [Validate Your `changes.xml` File](./examples/changes-file-validation.html)
- [Configuring the GitHub Report](./examples/configuring-github-report.html)
+- [Customizing the JIRA Report](./examples/customizing-jira-report.html)
+- [Configuring the Trac Report](./examples/configuring-trac-report.html)
- [Include an Announcement File in Your
Packaging](./examples/include-announcement-file.html)
-- [SMTP authentication](./examples/smtp-authentication.html)
-- [Specifying the mail sender](./examples/specifying-mail-sender.html)
- [Using a Custom Announcement
Template](./examples/using-a-custom-announcement-template.html)
-- [Validate Your `changes.xml` File](./examples/changes-file-validation.html)
+- [Specifying the Mail Sender](./examples/specifying-mail-sender.html)
+- [SMTP Authentication](./examples/smtp-authentication.html)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index b57b114..d53fabd 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -28,12 +28,14 @@ under the License.
# Usage
-This plugin is used to create a Changes Report, a JIRA Report and an
Announcement text file. It is also able to send the announcement via email.
+This plugin creates a Changes Report from a `changes.xml` file, issue reports
from JIRA, GitHub or Trac, and a
+release announcement text. It can also send the announcement by email.
How to Generate the Changes Report
----------------------------------
-In order to use this goal, simply create a `changes.xml` file in the
`src/changes/` directory. Here's an example of a typical `changes.xml`, showing
the syntax:
+Create a `changes.xml` file in the `src/changes/` directory. Here's an example
of a typical `changes.xml`, showing
+the syntax:
```xml
<document xmlns="http://maven.apache.org/changes/2.0.0"
@@ -41,24 +43,26 @@ In order to use this goal, simply create a `changes.xml`
file in the `src/change
xsi:schemaLocation="http://maven.apache.org/changes/2.0.0
https://maven.apache.org/xsd/changes-2.0.0.xsd">
<properties>
<title>Changes Tester Project</title>
- <author email="[email protected]">Johnny R. Ruiz III</author>
+ <author email="[email protected]">John Smith</author>
</properties>
<body>
- <release version="1.1" date="2005-03-01" description="Subsequent release">
- <action dev="jruiz" type="add">
+ <release version="1.1" date="2026-03-01" description="Subsequent release">
+ <action dev="jsmith" type="add">
Added additional documentation on how to configure the plugin.
</action>
- <action dev="aramirez" type="fix" issue="MPJIRA-11">
+ <action dev="jdoe" type="fix" issue="PROJ-11">
Enable retrieving component-specific issues.
</action>
- <action dev="jruiz" type="remove" due-to="Allan Ramirez"
due-to-email="[email protected]">
- The element type " link " must be terminated by the matching end-tag.
+ <action dev="jsmith" type="remove" due-to="Jane Roe, Joe Bloggs"
due-to-email="[email protected], [email protected]">
Deleted the erroneous code.
</action>
+ <action dev="jsmith" type="update" fixed-issues="PROJ-12,PROJ-13">
+ Updated the default announcement template.
+ </action>
</release>
- <release version="1.0" date="2005-01-01" description="First release">
- <action dev="jruiz" type="update">
+ <release version="1.0" date="2026-01-01" description="First release">
+ <action dev="jsmith" type="update">
Uploaded documentation on how to use the plugin.
</action>
</release>
@@ -66,7 +70,8 @@ In order to use this goal, simply create a `changes.xml` file
in the `src/change
</document>
```
-See the [Changes Reference](./changes.html) for details regarding the
`<release>` and `<action>` elements and their attributes.
+See the [Changes Reference](./changes.html) for details regarding the
`<release>` and `<action>` elements and their
+attributes. The supported action types are `add`, `fix`, `update` and `remove`.
To generate the Changes Report, insert the Changes Plugin in the `<reporting>`
section of your project's `pom.xml`
@@ -99,26 +104,34 @@ and execute the `site` phase to generate the report.
mvn site
```
+You can also run the report on its own; it is written to
`target/reports/changes.html`:
+
+```
+mvn changes:changes
+```
+
#[[### Linking to Your Issue Management System]]#
-If you use the `issue` attribute in your `changes.xml` file and have the
`<issueManagement>` element configured in your `pom.xml`, the report will
contain links to the issues in your issue management system.
+If you use the `issue` or `fixed-issues` attribute in your `changes.xml` file
and have the `<issueManagement>`
+element configured in your `pom.xml`, the report links each issue to your
issue management system.
-Starting with version 2.4 the plugin comes pre-configured for a whole bunch of
different issue management systems. All you have to to is enter your issue
management system and the URL to it in your POM. It can look like this:
+The plugin comes pre-configured for many issue management systems. All you
have to do is enter your issue management
+system and its URL in your POM. It can look like this:
```xml
<project>
...
<issueManagement>
<system>JIRA</system>
- <url>http://jira.company.com/</url>
+ <url>https://jira.example.com/browse/PROJ</url>
</issueManagement>
...
</project>
```
-If you have a previous configuration for `<issueLinkTemplatePerSystem>` in
your POM, you can probably throw that away when you start using version 2.4,
unless you use more than one issue management system.
-
-The following table shows the pre-configured issue management systems and the
templates they use to create links from your Changes Report directly to the
issues in your issue management system.
+The following table shows the pre-configured issue management systems and the
templates they use to create links
+from your Changes Report directly to the issues in your issue management
system. The value of
+`<issueManagement>/<system>` must match the name in the first column, ignoring
case.
|System|Issue Link Template|
|:---|:---|
@@ -128,24 +141,31 @@ The following table shows the pre-configured issue
management systems and the te
|GoogleCode|%URL%/detail?id=%ISSUE%|
|JIRA|%URL%/%ISSUE%|
|Mantis|%URL%/view.php?id=%ISSUE%|
-|MKS Integrity|%URL%/viewissue?selection=%ISSUE%|
+|MKS|%URL%/viewissue?selection=%ISSUE%|
|Redmine|%URL%/issues/show/%ISSUE%|
|Scarab|%URL%/issues/id/%ISSUE%|
-|SourceForge|http\://sourceforge.net/support/tracker.php?aid=%ISSUE%|
+|SourceForge|`http://sourceforge.net/support/tracker.php?aid=%ISSUE%`|
|SourceForge2|%URL%/%ISSUE%|
|Trac|%URL%/ticket/%ISSUE%|
|Trackplus|%URL%/printItem.action?key=%ISSUE%|
|Tuleap|%URL%/?aid=%ISSUE%|
|YouTrack|%URL%/issue/%ISSUE%|
-If you use an issue management system other than the ones above, you need to
[configure an issue link template for
it](./changes-mojo.html#issueLinkTemplatePerSystem). We would love to extend
the table above with more issue management systems, so if you have a working
configuration that is not listed above, please tell us about it by [creating an
issue for it](./issue-tracking.html).
+If you use an issue management system other than the ones above, or need to
link to more than one, you need to
+[configure an issue link template for
it](./changes-mojo.html${esc.hash}issueLinkTemplatePerSystem). We would love
+to extend the table above with more issue management systems, so if you have a
working configuration that is not
+listed above, please tell us about it by [creating an issue for
it](./issue-management.html).
-**Note:** Make sure that your `<issueManagement>/<url>` is correct. In
particular, make sure that it has a trailing slash if it needs one. The plugin
can't add this for you, because it needs to handle different issue management
systems. If your issue management system is at
`http://www.company.com/bugzilla/` the links will not work if you enter
`http://www.company.com/bugzilla` in your `pom.xml`.
+**Note:** `%URL%` is the value of `<issueManagement>/<url>` with the last `/`
and everything after it removed. For
+JIRA, `https://jira.example.com/browse/PROJ` gives links like
`https://jira.example.com/browse/PROJ-11`. For GitHub,
+end the URL with a slash, as in `https://github.com/example/project/issues/`,
so that the links point to
+`https://github.com/example/project/issues/11`; without the trailing slash the
`issues` part is dropped.
How to Generate the JIRA Report
-------------------------------
-**Note:** To use the JIRA Report, the `<issueManagement>` section in the
`pom.xml` of your project must be configured. It might look something like this:
+**Note:** To use the JIRA Report, the `<issueManagement>` section in the
`pom.xml` of your project must be
+configured. It might look something like this:
```xml
<project>
@@ -158,7 +178,8 @@ How to Generate the JIRA Report
</project>
```
-To generate the JIRA Report, insert the Changes Plugin in the `<reporting>`
section of your project's `pom.xml`
+The plugin reads the issues through the JIRA REST API. To generate the JIRA
Report, insert the Changes Plugin in the
+`<reporting>` section of your project's `pom.xml`
```xml
<project>
@@ -189,19 +210,21 @@ and execute the site goal to generate the report.
mvn site
```
-For info on how to modify the JIRA Report see the [Customizing the JIRA
Report](./examples/customizing-jira-report.html) example.
+For info on how to modify the JIRA Report see the [Customizing the JIRA
Report](./examples/customizing-jira-report.html)
+example.
How to Generate the GitHub Report
---------------------------------
-**Note:** To use the GitHub Report, the `<issueManagement>` section in the
`pom.xml` of your project must be configured. It might look something like this:
+**Note:** To use the GitHub Report, the `<issueManagement>` section in the
`pom.xml` of your project must be
+configured. It might look something like this:
```xml
<project>
...
<issueManagement>
<system>GitHub</system>
- <url>https://github.com/rails/rails/issues</url>
+ <url>https://github.com/apache/maven-changes-plugin/issues/</url>
</issueManagement>
...
</project>
@@ -238,57 +261,25 @@ and execute the site goal to generate the report.
mvn site
```
-For info on how to modify the JIRA Report see the [Configuring the GitHub
Report](./examples/configuring-github-report.html) example.
+For info on how to modify the GitHub Report see the [Configuring the GitHub
Report](./examples/configuring-github-report.html)
+example.
How to generate and send the Announcement via Email
---------------------------------------------------
-As usual we start by configuring your project's `pom.xml`. We add a basic
configuration for sending emails and specify the lucky recipients of the
announcement emails.
-
-For info on how to change the sender of the email see the [Specifying the mail
sender](./examples/specifying-mail-sender.html) example.
-
-If you have customizations for JIRA that add additional issue types, or if you
are using an IMS that isn't fully-supported in this plugin, you will need to
configure any additional issue types here.
-
-For each issue type, you have to map it to one of three action types: _add_,
_fix_, or _update_. These terms are a bit arbitrary. By default, for JIRA,
_add_ corresponds to 'New Feature', _fix_ corresponds to 'Bug', and _update_
corresponds to 'Improvement'.
-
-```xml
-<project>
- ...
- <build>
- <plugins>
- <plugin>
- <groupId>org.apache.maven.plugins</groupId>
- <artifactId>maven-changes-plugin</artifactId>
- <version>${project.version}</version>
- <configuration>
- ...
- <smtpHost>mail.yourhost.com</smtpHost>
- <smtpPort implementation="java.lang.Integer">25</smtpPort>
- <toAddresses>
- <toAddress
implementation="java.lang.String">[email protected]</toAddress>
- <toAddress
implementation="java.lang.String">[email protected]</toAddress>
- </toAddresses>
- ...
- <issueTypes>
- <add>Story</add>
- <fix>Defect, Malfunction</fix>
- </issueTypes>
- ...
- </configuration>
- </plugin>
- </plugins>
- </build>
- ...
-</project>
-```
-
-You can now generate the announcement by executing the command below:
+The `announcement-generate` goal writes the announcement text, by default to
+`target/announcement/announcement.vm`. Set `<announcementFile>` to choose
another file name. By default the
+announcement is built from the `changes.xml` file:
```
mvn changes:announcement-generate
```
-If you want to generate the announcement based on JIRA you need to configure
that in your `pom.xml`, like this:
+To build the announcement from an issue tracker instead, list it in
`<issueManagementSystems>`. Valid values are
+`changes.xml`, `JIRA`, `GitHub` and `Trac`; the tracker must also be the one
configured in `<issueManagement>`.
+To generate the announcement based on **both** a `changes.xml` file and JIRA
you should configure your `pom.xml`
+like this. `<onlyCurrentVersion>` makes JIRA return the issues of the version
you release; without it, the plugin
+fetches only the latest `<maxEntries>` (25) issues, which might not include
that version:
```xml
<project>
@@ -300,11 +291,11 @@ If you want to generate the announcement based on JIRA
you need to configure tha
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- ...
<issueManagementSystems>
+ <issueManagementSystem>changes.xml</issueManagementSystem>
<issueManagementSystem>JIRA</issueManagementSystem>
</issueManagementSystems>
- ...
+ <onlyCurrentVersion>true</onlyCurrentVersion>
</configuration>
</plugin>
</plugins>
@@ -313,7 +304,21 @@ If you want to generate the announcement based on JIRA you
need to configure tha
</project>
```
-To generate the announcement based on **both** a `changes.xml` file and JIRA
you should configure your `pom.xml` like this:
+The announcement groups issues from a tracker by action type: _add_, _fix_,
_update_ or _remove_. By default, for
+JIRA, _add_ corresponds to 'New Feature', _fix_ to 'Bug', and _update_ to
'Improvement', 'Task', 'Wish' and
+'Dependency upgrade'; for GitHub, _add_ corresponds to the label 'enhancement'
and _fix_ to 'bug'. If your tracker uses
+other issue types, map them with `<issueTypes>`, separating several types with
commas:
+
+```xml
+<configuration>
+ <issueTypes>
+ <add>Story</add>
+ <fix>Defect,Malfunction</fix>
+ </issueTypes>
+</configuration>
+```
+
+To send the announcement by email, configure the mail server and the
recipients:
```xml
<project>
@@ -325,12 +330,12 @@ To generate the announcement based on **both** a
`changes.xml` file and JIRA you
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- ...
- <issueManagementSystems>
- <issueManagementSystem>changes.xml</issueManagementSystem>
- <issueManagementSystem>JIRA</issueManagementSystem>
- </issueManagementSystems>
- ...
+ <smtpHost>mail.example.com</smtpHost>
+ <smtpPort>25</smtpPort>
+ <toAddresses>
+ <toAddress>[email protected]</toAddress>
+ <toAddress>[email protected]</toAddress>
+ </toAddresses>
</configuration>
</plugin>
</plugins>
@@ -339,8 +344,11 @@ To generate the announcement based on **both** a
`changes.xml` file and JIRA you
</project>
```
-This is how you send an email with the generated announcement:
+The `announcement-mail` goal runs `announcement-generate` first and then sends
the result:
```
mvn changes:announcement-mail
```
+
+For info on how to change the sender of the email see the [Specifying the Mail
Sender](./examples/specifying-mail-sender.html)
+example, and for a server that needs a login see [SMTP
Authentication](./examples/smtp-authentication.html).
diff --git a/src/site/markdown/using-changes-xsd.md
b/src/site/markdown/using-changes-xsd.md
index 272fc5b..682b068 100644
--- a/src/site/markdown/using-changes-xsd.md
+++ b/src/site/markdown/using-changes-xsd.md
@@ -26,7 +26,9 @@ under the License.
# Using the XML Schema Changes 2.0.0
-The Changes XSD is located
[here](https://maven.apache.org/xsd/changes-2.0.0.xsd).
+The current version of the `changes.xml` schema is 2.0.0. The XSD is published
at
+<https://maven.apache.org/xsd/changes-2.0.0.xsd>, and a copy is part of this
site:
+[changes-2.0.0.xsd](./xsd/changes-2.0.0.xsd).
Your favorite IDE probably supports validation and/or syntax highlighting for
XML files by using XSD schemas. For this to work you need to specify the schema
in your `changes.xml` file:
@@ -37,3 +39,6 @@ Your favorite IDE probably supports validation and/or syntax
highlighting for XM
...
</document>
```
+
+To validate the file during the build, use the
[changes-validate](./changes-validate-mojo.html) goal; see
+[Validate Your changes.xml File](./examples/changes-file-validation.html).
diff --git a/src/site/site.xml b/src/site/site.xml
index 3695cb6..4f7f518 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -37,20 +37,17 @@ under the License.
<item name="changes.xml" href="changes.html"/>
<item name="changes.xsd" href="xsd/changes-2.0.0.xsd"/>
</menu>
- <menu name="Samples">
- <item name="Sample Changes Report" href="changes.html"/>
- </menu>
<menu name="Examples">
<item name="Alternate Location for the changes.xml File"
href="examples/alternate-changes-xml-location.html"/>
<item name="Check Your changes.xml File"
href="examples/check-changes-file.html"/>
- <item name="Configuring the Trac Report"
href="examples/configuring-trac-report.html"/>
- <item name="Customizing the JIRA Report"
href="examples/customizing-jira-report.html"/>
+ <item name="Validate Your changes.xml File"
href="examples/changes-file-validation.html"/>
<item name="Configuring the GitHub Report"
href="examples/configuring-github-report.html"/>
+ <item name="Customizing the JIRA Report"
href="examples/customizing-jira-report.html"/>
+ <item name="Configuring the Trac Report"
href="examples/configuring-trac-report.html"/>
<item name="Include an Announcement File in Your Packaging"
href="examples/include-announcement-file.html"/>
- <item name="SMTP Authentication"
href="examples/smtp-authentication.html"/>
- <item name="Specifying the Mail Sender"
href="examples/specifying-mail-sender.html"/>
<item name="Using a Custom Announcement Template"
href="examples/using-a-custom-announcement-template.html"/>
- <item name="Validate Your changes.xml File"
href="examples/changes-file-validation.html"/>
+ <item name="Specifying the Mail Sender"
href="examples/specifying-mail-sender.html"/>
+ <item name="SMTP Authentication"
href="examples/smtp-authentication.html"/>
</menu>
</body>
</site>