Port the site documentation from APT to Markdown
13 page(s) converted with doxia-converter and then cleaned up by hand:
- <<<code>>> becomes backticks, <<bold>> becomes **bold**, {{{url}text}}
becomes [text](url)
- the ASF license header becomes a single block HTML comment
- a page whose only Velocity reference was ${project.name} is now a plain
.md with the title spelled out
- a page that keeps a reference stays a .vm. Velocity reads ## as a line
comment and would silently swallow every ATX heading below level one, so
subsections use setext underlines and anything deeper is wrapped in
#[[ ... ]]#
- a reference APT rendered literally is escaped with ${esc.d}, which always
yields a literal dollar; a backslash only works when the reference itself
resolves
Verified by building the site before and after and comparing every generated
page: the visible text and the link targets are unchanged apart from
<b>/<i> becoming <strong>/<em> and quotes and ellipses in prose picking up
the Markdown module's typographic substitution.
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 058212c..7631efc 100644
--- a/src/site/markdown/examples/alternate-changes-xml-location.md.vm
+++ b/src/site/markdown/examples/alternate-changes-xml-location.md.vm
@@ -1,44 +1,29 @@
- ------
- Alternate Location for the changes.xml File
- ------
- Dennis Lundberg
- ------
- 15 July 2006
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Alternate Location for the `changes.xml` File
-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 advice you to put it in the default location
- <<<$\{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 <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 <<<$\{basedir\}/src/site/changes.xml>>>:
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -62,4 +47,4 @@
</reporting>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/examples/changes-file-validation.md.vm b/src/site/markdown/examples/changes-file-validation.md.vm
index 8dd8668..1a3a96b 100644
--- a/src/site/markdown/examples/changes-file-validation.md.vm
+++ b/src/site/markdown/examples/changes-file-validation.md.vm
@@ -1,45 +1,34 @@
- ------
- Validate Your changes.xml File
- ------
- Olivier Lamy
- ------
- 2011-03-30
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Validate Your changes.xml File
-Validate Your changes.xml File
+Since 2.1, a [goal](../changes-validate-mojo.html) is provided to validate your `changes.xml` file.
- Since 2.1, a {{{../changes-validate-mojo.html}goal}} is
- provided to validate your <<<changes.xml>>> file.
+You can attach this goal to the `pre-site` phase if you want the validation to be performed automatically when you generate the site.
- You can attach this goal to the <<<pre-site>>> phase if you want the
- validation to be performed automatically when you generate the site.
+Configuring the Plugin
+----------------------
-* Configuring the Plugin
+First you must configure the plugin and tell it to validate your `changes.xml` file.
- First you must configure the plugin and tell it to validate your <<<changes.xml>>> file.
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -67,5 +56,4 @@
</build>
...
</project>
-+-----------------+
-
+```
diff --git a/src/site/markdown/examples/check-changes-file.md.vm b/src/site/markdown/examples/check-changes-file.md.vm
index b3b4b06..9a7cfcf 100644
--- a/src/site/markdown/examples/check-changes-file.md.vm
+++ b/src/site/markdown/examples/check-changes-file.md.vm
@@ -1,46 +1,34 @@
- ------
- Check Your changes.xml File
- ------
- Dennis Lundberg
- ------
- 2011-03-30
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Check Your changes.xml File
-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.
- Since version 2.4 this plugin has a {{{../changes-check-mojo.html}goal}} that
- checks that your <<<changes.xml>>> file has a valid release date.
+You can attach this goal to the `verify` phase if you want the check to be performed automatically when you build the project.
- You can attach this goal to the <<<verify>>> phase if you want the check to
- be performed automatically when you build the project.
+Configuring the Plugin
+----------------------
-* Configuring the Plugin
+Configure the plugin like this to tell it to check your `changes.xml` file.
- Configure the plugin like this to tell it to check your <<<changes.xml>>>
- file.
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -63,4 +51,4 @@
</build>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/examples/configuring-github-report.md.vm b/src/site/markdown/examples/configuring-github-report.md.vm
index aaca72f..c6e26c8 100644
--- a/src/site/markdown/examples/configuring-github-report.md.vm
+++ b/src/site/markdown/examples/configuring-github-report.md.vm
@@ -1,46 +1,37 @@
- ------
- Configuring the GitHub Report
- ------
- Bryan Baugher
- ------
- 2012-06-21
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Configuring the GitHub Report
-Configuring the GitHub Report
+**Note:** See the [goal documentation](../github-changes-mojo.html) for detailed info on which feature was added in which version.
- <<Note:>> See the {{{../github-changes-mojo.html}goal documentation}} for
- detailed info on which feature was added in which version.
+Using GitHub Enterprise
+-----------------------
-* Using GitHub Enterprise
+Additional configurations are not needed. Address of your **GitHub** instance will be taken from `project -> issueManagement -> url`
- Additional configurations are not needed. Address of your <<GitHub>> instance will be taken from <<<project -> issueManagement -> url>>>
+Authenticating to the GitHub REST API
+-------------------------------------
-* 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:
- If you are using GitHub Enterprise or you want to authenticate to GitHub, configure the server in settings.xml like so:
-
-+-----------------+
+```xml
<settings>
...
<servers>
@@ -51,25 +42,24 @@
</servers>
...
</settings>
-+-----------------+
+```
- Only the <<<password>>> item is used as your token for <<<Authorization: Bearer YOUR-TOKEN>>>
+Only the `password` item is used as your token for `Authorization: Bearer YOUR-TOKEN`
- The default serverId is <<<github>>>. You can change it by setting the <<<\<githubAPIServerId\>>>> configuration parameter.
+The default serverId is `github`. You can change it by setting the `<githubAPIServerId>` configuration parameter.
- {{{https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api}Authenticating to the REST API}}
+[Authenticating to the REST API](https://docs.github.com/en/rest/authentication/authenticating-to-the-rest-api)
-* Filtering Issues
+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.
+We'll start off by creating a GitHub Report for one or more versions of your project. There are two ways to do this.
-** Only include closed issues
+#[[### 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 make sure to configure the includeOpenIssues to false in your configuration, which is true by default.
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -87,15 +77,13 @@
</reporting>
...
</project>
-+-----------------+
+```
-** Include issues without milestones
+#[[### 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 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.
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -113,24 +101,17 @@
</reporting>
...
</project>
-+-----------------+
+```
-** Using the current version
+#[[### 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 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.
- Once you have configured this, you can forget about it, as it updates itself
- when you change the version number in your POM.
+Once you have configured this, you can forget about it, as it updates itself when you change the version number in your POM.
- <<Note:>> The names of your milestones in GitHub must match the ones you use in
- your POM. The <-SNAPSHOT> part of the version in your POM is handled
- automatically by the plugin, so you don't need to include <-SNAPSHOT> in the
- names of your milestones in GitHub.
+**Note:** The names of your milestones in GitHub must match the ones you use in your POM. The _-SNAPSHOT_ part of the version in your POM is handled automatically by the plugin, so you don't need to include _-SNAPSHOT_ in the names of your milestones in GitHub.
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -148,14 +129,14 @@
</reporting>
...
</project>
-+-----------------+
+```
+Selecting columns
+-----------------
-* Selecting columns
+You can select which columns to include in the report.
- You can select which columns to include in the report.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -173,4 +154,4 @@
</reporting>
...
</project>
-+-----------------+
\ No newline at end of file
+```
diff --git a/src/site/markdown/examples/configuring-trac-report.md.vm b/src/site/markdown/examples/configuring-trac-report.md.vm
index 001e6c5..d8d79af 100644
--- a/src/site/markdown/examples/configuring-trac-report.md.vm
+++ b/src/site/markdown/examples/configuring-trac-report.md.vm
@@ -1,83 +1,64 @@
- ------
- Configuring the Trac Report
- ------
- David Roussel
- ------
- 2009-10-02
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Configuring the Trac Report
-Configuring the Trac Report
+Configuring your Trac instance
+------------------------------
-* 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.
- If you've used form authentication then you are out of luck.
+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.
- Your Trac installation needs to have the {{{https://trac-hacks.org/wiki/XmlRpcPlugin}XML-RPC plugin}}
- installed and working for this plugin to be able to read the tickets.
+#[[### Basic Report Configuration]]#
-** 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 should work with no additional configuration, but by default all ticket
- will be listed
-
-+-----------------+
+```xml
<issueManagement>
<system>trac</system>
<url>http://mytracserver.local/trac/MYPROJECT/</url>
</issueManagement>
-+-----------------+
+```
-** Configuring a Custom Query
+#[[### Configuring a Custom Query]]#
- The exact query can configured in the <<<\<query\>>>> element.
- See {{{https://trac.edgewall.org/wiki/TracQuery}TracQuery}} for the exact syntax.
+The exact query can configured in the `<query>` element. See [TracQuery](https://trac.edgewall.org/wiki/TracQuery) for the exact syntax.
-+-----------------+
+```unknown
...
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-changes-plugin</artifactId>
<version>${project.version}</version>
<configuration>
- <query>status=accepted&status=assigned&status=new&status=reopened&order=priority&component=\${project.artifactId}</query>
+ <query>status=accepted&status=assigned&status=new&status=reopened&order=priority&component=${esc.d}{project.artifactId}</query>
</configuration>
</plugin>
...
-+-----------------+
+```
+#[[### Configuring Basic Authentication]]#
-** Configuring Basic Authentication
+If your Trac is protected by basic authentication then you'll need to add the `<tracUser>` and `<tracPassword>` configuration elements so that the plugin knows who to authenticate as.
- If your Trac is protected by basic authentication then you'll need to add
- the <<<\<tracUser\>>>> and <<<\<tracPassword\>>>> configuration elements
- so that the plugin knows who to authenticate as.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -95,23 +76,17 @@
</reporting>
...
</project>
-+-----------------+
+```
+#[[### Configuring NTLM Authentication]]#
-** Configuring NTLM Authentication
+If you have your Trac sitting behind Apache on Windows with mod\_sspi doing authentication with Active Directory, then the plugin should authenticate to the server as the current user without any extra config. No `<tracUser>` and `<tracPassword>` configuration elements are needed.
- If you have your Trac sitting behind Apache on Windows with mod_sspi
- doing authentication with Active Directory, then the plugin should
- authenticate to the server as the current user without any extra config.
- No <<<\<tracUser\>>>> and <<<\<tracPassword\>>>> configuration elements
- are needed.
+#[[### Using custom encoding]]#
-** Using custom encoding
+If you have to support non-western encodings, then specify an `<outputEncoding>` in the configuration.
- If you have to support non-western encodings, then specify an <<<\<outputEncoding\>>>> in the
- configuration.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -129,6 +104,4 @@
</reporting>
...
</project>
-+-----------------+
-
-
+```
diff --git a/src/site/markdown/examples/customizing-jira-report.md.vm b/src/site/markdown/examples/customizing-jira-report.md.vm
index a4f0900..eac16d8 100644
--- a/src/site/markdown/examples/customizing-jira-report.md.vm
+++ b/src/site/markdown/examples/customizing-jira-report.md.vm
@@ -1,55 +1,38 @@
- ------
- Customizing the JIRA Report
- ------
- Dennis Lundberg
- ------
- 2008-02-10
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Customizing the JIRA Report
-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.
- <<Note:>> Most of the features used in this document were introduced in version
- <<2.0>> of the Changes Plugin. See the
- {{{../jira-changes-mojo.html}goal documentation}} for detailed info on which
- feature was added in which version.
+Selecting version(s)
+--------------------
-* Selecting version(s)
+We'll start off by creating a JIRA Report for one or more versions of your project. There are two ways to do this.
- We'll start off by creating a JIRA Report for one or more versions of your
- project. There are two ways to do this.
+#[[### Using fix version id(s)]]#
-** 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 version ids,
- separated by commas. The version ids are usually five digit numbers, but that
- depends on your JIRA installation.
+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.
- 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.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -67,24 +50,17 @@
</reporting>
...
</project>
-+-----------------+
+```
-** Using the current version
+#[[### 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 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.
- Once you have configured this, you can forget about it, as it updates itself
- when you change the version number in your POM.
+Once you have configured this, you can forget about it, as it updates itself when you change the version number in your POM.
- <<Note:>> The names of your versions in JIRA must match the ones you use in
- your POM. The <-SNAPSHOT> part of the version in your POM is handled
- automatically by the plugin, so you don't need to include <-SNAPSHOT> in the
- names of your versions in JIRA.
+**Note:** The names of your versions in JIRA must match the ones you use in your POM. The _-SNAPSHOT_ part of the version in your POM is handled automatically by the plugin, so you don't need to include _-SNAPSHOT_ in the names of your versions in JIRA.
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -102,21 +78,16 @@
</reporting>
...
</project>
-+-----------------+
+```
+Selecting columns
+-----------------
-* 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.
- 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.
+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.
- 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.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -135,23 +106,18 @@
</reporting>
...
</project>
-+-----------------+
+```
+Filtering issues
+----------------
-* Filtering issues
+Is your report filled with issues that you don't want to publicise? Does it contain duplicate issues and stuff that you decided not to fix? Then this part is for you.
- Is your report filled with issues that you don't want to publicise? Does it
- contain duplicate issues and stuff that you decided not to fix? Then this part
- is for you.
+#[[### Using Maven syntax]]#
-** Using Maven syntax
+In the following example we are only including issues that have _Fixed_ as their resolution. The status must be either _Resolved_ or _Closed_. Only issues with one of the types _Bug_, _New Feature_, _Improvement_ or _Wish_ are included in the report.
- In the following example we are only including issues that have <Fixed> as
- their resolution. The status must be either <Resolved> or <Closed>. Only
- issues with one of the types <Bug>, <New Feature>, <Improvement> or <Wish> are
- included in the report.
-
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -171,22 +137,17 @@
</reporting>
...
</project>
-+-----------------+
+```
- You can also filter by <<<\<component\>>>> and <<<\<priorityIds\>>>>. See the
- {{{../jira-changes-mojo.html}goal documentation}} for info on how to use them.
+You can also filter by `<component>` and `<priorityIds>`. See the [goal documentation](../jira-changes-mojo.html) for info on how to use them.
-** Using JIRA syntax
+#[[### 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 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.
- 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 filtering out issues with _Fixed_ as resolution and sorting them by _type_, in ascending order.
-+-----------------+
+```xml
<project>
...
<reporting>
@@ -204,4 +165,4 @@
</reporting>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/examples/include-announcement-file.md.vm b/src/site/markdown/examples/include-announcement-file.md.vm
index ed98d52..332a783 100644
--- a/src/site/markdown/examples/include-announcement-file.md.vm
+++ b/src/site/markdown/examples/include-announcement-file.md.vm
@@ -1,45 +1,32 @@
- ------
- Include an Announcement File in Your Packaging
- ------
- Dennis Lundberg
- ------
- 2011-01-01
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Include an Announcement File in Your Packaging
-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.
- 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.
+Configuring the Plugin
+----------------------
-* Configuring the Plugin
+In this example we want to call the generated announcement file `CHANGES.txt` and have it put into the `META-INF` directory of the project's JAR file. To do this we configure the Changes Plugin like this:
- In this example we want to call the generated announcement file
- <<<CHANGES.txt>>> and have it put into the <<<META-INF>>> directory of the
- project's JAR file. To do this we configure the Changes Plugin like this:
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -57,7 +44,7 @@
</goals>
<configuration>
<announcementFile>CHANGES.txt</announcementFile>
- <announcementDirectory>\${project.build.outputDirectory}/META-INF</announcementDirectory>
+ <announcementDirectory>${esc.d}{project.build.outputDirectory}/META-INF</announcementDirectory>
</configuration>
</execution>
</executions>
@@ -66,4 +53,4 @@
</build>
...
</project>
-+-----------------+
+```
diff --git a/src/site/markdown/examples/smtp-authentication.md.vm b/src/site/markdown/examples/smtp-authentication.md.vm
index 14f14e3..3d5e441 100644
--- a/src/site/markdown/examples/smtp-authentication.md.vm
+++ b/src/site/markdown/examples/smtp-authentication.md.vm
@@ -1,39 +1,27 @@
- ------
- SMTP Authentication
- ------
- Allan Ramirez
- ------
- 21 October 2005
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# SMTP Authentication
-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:
-
--------------------
+```
<project>
...
<build>
@@ -54,4 +42,4 @@
</build>
...
</project>
--------------------
+```
diff --git a/src/site/markdown/examples/specifying-mail-sender.md.vm b/src/site/markdown/examples/specifying-mail-sender.md.vm
index 97363ab..e817058 100644
--- a/src/site/markdown/examples/specifying-mail-sender.md.vm
+++ b/src/site/markdown/examples/specifying-mail-sender.md.vm
@@ -1,44 +1,32 @@
- ------
- Specifying the Mail Sender
- ------
- Stephane Nicoll
- ------
- 2011-03-30
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Specifying the Mail Sender
-Specifying the Mail Sender
+The identity used to send the announcement mail can be customized. It can be either a member of the `<developers>` section of the POM or it can be specified explicitly with the `<mailSender>` parameter of the plugin.
- The identity used to send the announcement mail can be customized. It can be
- either a member of the <<<\<developers\>>>> section of the POM or it can be
- specified explicitly with the <<<\<mailSender\>>>> parameter of the plugin.
+Specifying the developer to use
+-------------------------------
-* Specifying the developer to use
+To specify which developer is used to send the announcement, simply specify the `id` of the developer as in the example below:
- To specify which developer is used to send the announcement, simply specify the <<<id>>> of
- the developer as in the example below:
-
-+-----------------+
+```xml
<project>
<developers>
...
@@ -64,24 +52,22 @@
</build>
...
</project>
-+-----------------+
+```
- If no developer <<<id>>> is specified, the first <<<\<developer\>>>> in the list will be used.
+If no developer `id` is specified, the first `<developer>` in the list will be used.
- You can also do this from the command line, if the person doing the release
- changes between releases.
+You can also do this from the command line, if the person doing the release changes between releases.
-+-----------------+
+```shell
mvn -Dchanges.fromDeveloperId=jsmith changes:announcement-mail
-+-----------------+
+```
+Specifying the sender explicitly
+--------------------------------
-* Specifying the sender explicitly
+If you want to specify the sender explicitly and not rely on the `developers` section of your POM, define the `mailSender` parameter of the plugin.
- If you want to specify the sender explicitly and not rely on the <<<developers>>> section of your POM,
- define the <<<mailSender>>> parameter of the plugin.
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -101,5 +87,4 @@
</build>
...
</project>
-+-----------------+
-
+```
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 4356eda..a188c51 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
@@ -1,48 +1,34 @@
- ------
- Using a Custom Announcement Template
- ------
- Dennis Lundberg
- ------
- 2011-03-30
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Using a Custom Announcement Template
-Using a Custom Announcement Template
+The `announcement-generate` goal uses a [Velocity](https://velocity.apache.org/) template to create an announcement. If you want to, you can create your own custom template.
- The <<<announcement-generate>>> goal uses a {{{https://velocity.apache.org/}Velocity}}
- template to create an announcement. If you want to, you can create your own
- custom template.
+Configuring the Plugin
+----------------------
-* 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
- <<<$\{basedir\}/src/main/resources/our-announcements/my-announcement.vm>>>.
+**Note:** The `<templateDirectory>` must be a subdirectory of `${esc.d}{basedir}/src/main/resources/`.
- <<Note:>> The <<<\<templateDirectory\>>>> must be a subdirectory of
- <<<$\{basedir\}/src/main/resources/>>>.
-
-+-----------------+
+```xml
<project>
...
<build>
@@ -60,96 +46,60 @@
</build>
...
</project>
-+-----------------+
+```
+Creating Your Template
+----------------------
-* 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 download it from
- {{{https://github.com/apache/maven-changes-plugin/blob/master/src/main/resources/org/apache/maven/plugins/announcement/announcement.vm}here}}.
- It will provide you with examples on how to iterate over the actions of a
- release among other things.
+Available Variables
+-------------------
+Here's a list of the variables that you have at your disposal, when creating your own template:
-* Available Variables
+|Variable|Type|Since|Description|
+|:---|:---|:---|:---|
+|releases*|List|2.0|All the releases from either the changes.xml file or from JIRA.|
+|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.|
+|packaging*|String|2.0|The packaging from your project's pom.|
+|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}`.|
+|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}`.|
+|announceParameters|Map|2.1|A Map of custom parameters that can be specified in the plugin's configuration.|
+[Variables marked with \* are read-only.]
- Here's a list of the variables that you have at your disposal, when creating
- your own template:
+Each `Release` also has a set of variables:
-*-----------------+----------+-----------+-----------------+
-| <<Variable>> | <<Type>> | <<Since>> | <<Description>>
-*-----------------+----------+-----------+-----------------+
-| releases* | List | 2.0 | All the releases from either the changes.xml file or from JIRA.
-*-----------------+----------+-----------+-----------------+
-| 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.
-*-----------------+----------+-----------+-----------------+
-| packaging* | String | 2.0 | The packaging from your project's pom.
-*-----------------+----------+-----------+-----------------+
-| 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>>: <<<$\{project.url\}>>>.
-*-----------------+----------+-----------+-----------------+
-| introduction | String | 2.0 | A short description or introduction of the released artifact. <<Default value is>>: <<<$\{project.description\}>>>.
-*-----------------+----------+-----------+-----------------+
-| developmentTeam | String | 2.0 | Name of the team that develops the artifact. <<Default value is>>: <<<$\{project.name\} team>>>.
-*-----------------+----------+-----------+-----------------+
-| finalName | String | 2.0 | The name of the artifact to be used in the announcement. <<Default value is>>: <<<$\{project.build.finalName\}>>>.
-*-----------------+----------+-----------+-----------------+
-| urlDownload | String | 2.0 | URL where the artifact can be downloaded. <<Default value is>>: <<<$\{project.url\}>>>.
-*-----------------+----------+-----------+-----------------+
-| announceParameters | Map | 2.1 | A Map of custom parameters that can be specified in the plugin's configuration.
-*-----------------+----------+-----------+-----------------+
-<Variables marked with * are read-only.>
+|Variable|Type|Since|Description|
+|:---|:---|:---|:---|
+|actions*|List|2.0|All actions that were completed in this release.|
+|dateRelease*|String|2.0|The date when this release is made.|
+|description*|String|2.0|A description of the release.|
+|version*|String|2.0|The version of this release.|
+[Variables marked with \* are read-only.]
- Each <<<Release>>> also has a set of variables:
+Finally each `Action` has the following variables:
-*-----------------+----------+-----------+-----------------+
-| <<Variable>> | <<Type>> | <<Since>> | <<Description>>
-*-----------------+----------+-----------+-----------------+
-| actions* | List | 2.0 | All actions that were completed in this release.
-*-----------------+----------+-----------+-----------------+
-| dateRelease* | String | 2.0 | The date when this release is made.
-*-----------------+----------+-----------+-----------------+
-| description* | String | 2.0 | A description of the release.
-*-----------------+----------+-----------+-----------------+
-| version* | String | 2.0 | The version of this release.
-*-----------------+----------+-----------+-----------------+
-<Variables marked with * are read-only.>
+|Variable|Type|Since|Description|
+|:---|:---|:---|:---|
+|action*|String|2.0|What was done.|
+|date|String|2.0|Fix date.|
+|dev*|String|2.0|The developer who made the change.|
+|dueTo*|String|2.0|If this was a contribution from a non-committer, the name of that person.|
+|dueToEmail*|String|2.0|If this was a contribution from a non-committer, the e-mail address of that person.|
+|issue*|String|2.0|The key of the issue in your issue tracking system.|
+|type*|String|2.0|What kind of change was this.|
+|dueTos*|List|3.0|Collection of parsed dueTo and dueToEmail. Each item has variable name and email.|
+|fixedIssues*|List|3.0|Collection of fixed issues.|
+[Variables marked with \* are read-only.]
- 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.
-*-----------------+----------+-----------+-----------------+
-| <<Variable>> | <<Type>> | <<Since>> | <<Description>>
-*-----------------+----------+-----------+-----------------+
-| action* | String | 2.0 | What was done.
-*-----------------+----------+-----------+-----------------+
-| date | String | 2.0 | Fix date.
-*-----------------+----------+-----------+-----------------+
-| dev* | String | 2.0 | The developer who made the change.
-*-----------------+----------+-----------+-----------------+
-| dueTo* | String | 2.0 | If this was a contribution from a non-committer, the name of that person.
-*-----------------+----------+-----------+-----------------+
-| dueToEmail* | String | 2.0 | If this was a contribution from a non-committer, the e-mail address of that person.
-*-----------------+----------+-----------+-----------------+
-| issue* | String | 2.0 | The key of the issue in your issue tracking system.
-*-----------------+----------+-----------+-----------------+
-| type* | String | 2.0 | What kind of change was this.
-*-----------------+----------+-----------+-----------------+
-| dueTos* | List | 3.0 | Collection of parsed dueTo and dueToEmail. Each item has variable name and email.
-*-----------------+----------+-----------+-----------------+
-| fixedIssues* | List | 3.0 | Collection of fixed issues.
-*-----------------+----------+-----------+-----------------+
-<Variables marked with * are read-only.>
-
- Velocity Context contains all default tools provided by the {{{https://velocity.apache.org/tools/devel/standalone.html}ToolManager}}.
- See the {{{https://velocity.apache.org/tools/devel/tools-summary.html}Tools Usage Summary}} for further details.
-
- For information on how to access variables in your template and more,
- see the {{{https://velocity.apache.org/engine/devel/developer-guide.html}Velocity user guide}}.
+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).
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 5d3e4d0..e7da5bf 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -1,135 +1,80 @@
- ------
- Introduction
- ------
- Dennis Lundberg
- ------
- 2013-07-22
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+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.
-${project.name}
+You also have the option of creating a release announcement and even sending it via email to your users.
- 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.
+## Goals Overview
- You also have the option of creating a release announcement and even sending it via email
- to your users.
+- [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/).
+## Usage
-* Goals Overview
+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.
- * {{{./announcement-mail-mojo.html}changes:announcement-mail}} send a release announcement via email.
+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).
- * {{{./announcement-generate-mojo.html}changes:announcement-generate}} generate a release announcement.
+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 welcome, too. Contributors can check out the project from our [source repository](./scm.html) and will find supplementary information in the [guide to helping with Maven](https://maven.apache.org/guides/development/guide-helping.html).
- * {{{./changes-check-mojo.html}changes:changes-check}} check that the <<<changes.xml>>> file contains a valid release date.
+## Migration to 3.x
- * {{{./changes-validate-mojo.html}changes:changes-validate}} validate the <<<changes.xml>>> file.
+### changes.xml - schema changes
- * {{{./changes-mojo.html}changes:changes}} create a report from <<<changes.xml>>> file.
+- 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
- * {{{./jira-changes-mojo.html}changes:jira-changes}} create a report from issues downloaded from {{{https://www.atlassian.com/software/jira/}JIRA}}.
+The reports output filename and goals name were changed for alignment with other reporting plugins from `org.apache.maven.plugins`.
- * {{{./trac-changes-mojo.html}changes:trac-changes}} create a report from issues downloaded from {{{https://trac.edgewall.org/}Trac}}.
-
- * {{{./github-changes-mojo.html}changes:github-changes}} create a report from issues downloaded from {{{https://github.com/}GitHub}}.
+See the following table for changes:
- []
+|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|
-* Usage
+### Deprecate Trac integration
- General instructions on how to use the Changes Plugin can be found on the {{{./usage.html}usage page}}. Some more
- specific use cases are described in the examples given below.
+**Trac** integration is prepared for removal in next major version due to lack of maintainers.
- In case you still have questions regarding the plugin's usage, please have a look at the {{{./faq.html}FAQ}} and feel
- free to contact the {{{./mailing-lists.html}user mailing list}}. 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 {{{./mailing-lists.html}mail archive}}.
+## Examples
- 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-management.html}issue tracker}}. 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 welcome, too. Contributors can check out the project from our
- {{{./scm.html}source repository}} and will find supplementary information in the
- {{{https://maven.apache.org/guides/development/guide-helping.html}guide to helping with Maven}}.
+To provide you with better understanding of some usages of the Changes Plugin, you can take a look at the following examples:
-* Migration to 3.x
-
-** changes.xml - schema changes
-
- * you should update schema in your changes.xml to <<<2.0.0>>> - {{{./using-changes-xsd.html}Using the XML Schema}}.
-
- * 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
-
- The reports output filename and goals name were changed for alignment with other reporting plugins from <<<org.apache.maven.plugins>>>.
-
- See the following table for changes:
-
-*---------------------------------+-------------------------------------------+
-| <<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 |
-*---------------------------------+-------------------------------------------+
-
-** Deprecate Trac integration
-
- <<Trac>> integration is prepared for removal in next major version due to lack of maintainers.
-
-* Examples
-
- To provide you with better understanding of some usages of the Changes Plugin,
- you can take a look at the following examples:
-
- * {{{./examples/alternate-changes-xml-location.html}Alternate Location for the <<<changes.xml>>> File}}
-
- * {{{./examples/check-changes-file.html}Check Your <<<changes.xml>>> File}}
-
- * {{{./examples/configuring-trac-report.html}Configuring the Trac Report}}
-
- * {{{./examples/customizing-jira-report.html}Customizing the JIRA Report}}
-
- * {{{./examples/configuring-github-report.html}Configuring the GitHub Report}}
-
- * {{{./examples/include-announcement-file.html}Include an Announcement File in Your Packaging}}
-
- * {{{./examples/smtp-authentication.html}SMTP authentication}}
-
- * {{{./examples/specifying-mail-sender.html}Specifying the mail sender}}
-
- * {{{./examples/using-a-custom-announcement-template.html}Using a Custom Announcement Template}}
-
- * {{{./examples/changes-file-validation.html}Validate Your <<<changes.xml>>> File}}
+- [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)
+- [Configuring the GitHub Report](./examples/configuring-github-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)
diff --git a/src/site/markdown/usage.md.vm b/src/site/markdown/usage.md.vm
index 0eb5446..10e6fd4 100644
--- a/src/site/markdown/usage.md.vm
+++ b/src/site/markdown/usage.md.vm
@@ -1,46 +1,32 @@
- ------
- Usage
- ------
- Johnny R. Ruiz III
- Allan Ramirez
- Dennis Lundberg
- ------
- 2011-05-31
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
- ~~ Licensed to the Apache Software Foundation (ASF) under one
- ~~ or more contributor license agreements. See the NOTICE file
- ~~ distributed with this work for additional information
- ~~ regarding copyright ownership. The ASF licenses this file
- ~~ to you under the Apache License, Version 2.0 (the
- ~~ "License"); you may not use this file except in compliance
- ~~ with the License. You may obtain a copy of the License at
- ~~
- ~~ http://www.apache.org/licenses/LICENSE-2.0
- ~~
- ~~ Unless required by applicable law or agreed to in writing,
- ~~ software distributed under the License is distributed on an
- ~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- ~~ KIND, either express or implied. See the License for the
- ~~ specific language governing permissions and limitations
- ~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
- ~~ NOTE: For help with the syntax of this file, see:
- ~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# Usage
-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 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.
+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:
-*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:
-
-+-------------------+
+```xml
<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 https://maven.apache.org/xsd/changes-2.0.0.xsd">
@@ -69,15 +55,13 @@
</release>
</body>
</document>
-+-------------------+
+```
- See the {{{./changes.html}Changes Reference}} 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.
- To generate the Changes Report, insert the Changes Plugin in the
- <<<\<reporting\>>>> section of your project's <<<pom.xml>>>
+To generate the Changes Report, insert the Changes Plugin in the `<reporting>` section of your project's `pom.xml`
-+-------------------+
+```xml
<project>
...
<reporting>
@@ -98,25 +82,21 @@
</reporting>
...
</project>
-+-------------------+
+```
- and execute the <<<site>>> phase to generate the report.
+and execute the `site` phase to generate the report.
--------------------
+```
mvn site
--------------------
+```
-** Linking to Your Issue Management System
+#[[### 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` 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.
- 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:
+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:
-+-----+
+```xml
<project>
...
<issueManagement>
@@ -125,73 +105,40 @@
</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.
+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.
-*---------------+--------------------------------------------------------+
-| <<System>> | <<Issue Link Template>> |
-*---------------+--------------------------------------------------------+
-| Bitbucket | %URL%/issue/%ISSUE% |
-*---------------+--------------------------------------------------------+
-| Bugzilla | %URL%/show_bug.cgi?id=%ISSUE% |
-*---------------+--------------------------------------------------------+
-| GitHub | %URL%/%ISSUE% |
-*---------------+--------------------------------------------------------+
-| GoogleCode | %URL%/detail?id=%ISSUE% |
-*---------------+--------------------------------------------------------+
-| JIRA | %URL%/%ISSUE% |
-*---------------+--------------------------------------------------------+
-| Mantis | %URL%/view.php?id=%ISSUE% |
-*---------------+--------------------------------------------------------+
-| MKS Integrity | %URL%/viewissue?selection=%ISSUE% |
-*---------------+--------------------------------------------------------+
-| Redmine | %URL%/issues/show/%ISSUE% |
-*---------------+--------------------------------------------------------+
-| Scarab | %URL%/issues/id/%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% |
-*---------------+--------------------------------------------------------+
+|System|Issue Link Template|
+|:---|:---|
+|Bitbucket|%URL%/issue/%ISSUE%|
+|Bugzilla|%URL%/show\_bug.cgi?id=%ISSUE%|
+|GitHub|%URL%/%ISSUE%|
+|GoogleCode|%URL%/detail?id=%ISSUE%|
+|JIRA|%URL%/%ISSUE%|
+|Mantis|%URL%/view.php?id=%ISSUE%|
+|MKS Integrity|%URL%/viewissue?selection=%ISSUE%|
+|Redmine|%URL%/issues/show/%ISSUE%|
+|Scarab|%URL%/issues/id/%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
- {{{./changes-mojo.html#issueLinkTemplatePerSystem}configure an issue
- link template for it}}.
- 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 {{{./issue-tracking.html}creating an issue for it}}.
+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).
- <<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:** 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`.
+How to Generate the JIRA Report
+-------------------------------
-*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>
...
<issueManagement>
@@ -200,12 +147,11 @@
</issueManagement>
...
</project>
-+-------------------+
+```
- To generate the JIRA Report, insert the Changes Plugin in the
- <<<\<reporting\>>>> section of your project's <<<pom.xml>>>
+To generate the JIRA Report, insert the Changes Plugin in the `<reporting>` section of your project's `pom.xml`
-+-------------------+
+```xml
<project>
...
<reporting>
@@ -226,25 +172,22 @@
</reporting>
...
</project>
-+-------------------+
+```
- and execute the site goal to generate the report.
+and execute the site goal to generate the report.
--------------------
+```
mvn site
--------------------
+```
- For info on how to modify the JIRA Report see the
- {{{./examples/customizing-jira-report.html}Customizing the JIRA Report}}
- example.
-
-*How to Generate the GitHub Report
+For info on how to modify the JIRA Report see the [Customizing the JIRA Report](./examples/customizing-jira-report.html) example.
- <<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:
+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:
+
+```xml
<project>
...
<issueManagement>
@@ -253,12 +196,11 @@
</issueManagement>
...
</project>
-+-------------------+
+```
- To generate the GitHub Report, insert the Changes Plugin in the
- <<<\<reporting\>>>> section of your project's <<<pom.xml>>>
+To generate the GitHub Report, insert the Changes Plugin in the `<reporting>` section of your project's `pom.xml`
-+-------------------+
+```xml
<project>
...
<reporting>
@@ -279,37 +221,28 @@
</reporting>
...
</project>
-+-------------------+
+```
- and execute the site goal to generate the report.
+and execute the site goal to generate the report.
--------------------
+```
mvn site
--------------------
+```
- For info on how to modify the JIRA Report see the
- {{{./examples/configuring-github-report.html}Configuring the GitHub Report}}
- example.
+For info on how to modify the JIRA Report see the [Configuring the GitHub Report](./examples/configuring-github-report.html) example.
-*How to generate and send the Announcement via Email
+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.
+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
- {{{./examples/specifying-mail-sender.html}Specifying the mail sender}} 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'.
+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>
@@ -328,8 +261,8 @@
</toAddresses>
...
<issueTypes>
- <add>Story</add>
- <fix>Defect, Malfunction</fix>
+ <add>Story</add>
+ <fix>Defect, Malfunction</fix>
</issueTypes>
...
</configuration>
@@ -338,18 +271,17 @@
</build>
...
</project>
-+-------------------+
+```
- You can now generate the announcement by executing the command below:
+You can now generate the announcement by executing the command below:
--------------------
+```
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:
+If you want to generate the announcement based on JIRA you need to configure that in your `pom.xml`, like this:
-+-------------------+
+```xml
<project>
...
<build>
@@ -370,12 +302,11 @@
</build>
...
</project>
-+-------------------+
+```
- To generate the announcement based on <<both>> a <<<changes.xml>>> file and JIRA
- you should configure your <<<pom.xml>>> like this:
+To generate the announcement based on **both** a `changes.xml` file and JIRA you should configure your `pom.xml` like this:
-+-------------------+
+```xml
<project>
...
<build>
@@ -397,10 +328,10 @@
</build>
...
</project>
-+-------------------+
+```
- This is how you send an email with the generated announcement:
+This is how you send an email with the generated announcement:
--------------------
+```
mvn changes:announcement-mail
--------------------
+```
diff --git a/src/site/markdown/using-changes-xsd.md b/src/site/markdown/using-changes-xsd.md
index 2b8ef57..a7d8314 100644
--- a/src/site/markdown/using-changes-xsd.md
+++ b/src/site/markdown/using-changes-xsd.md
@@ -1,43 +1,32 @@
- -----
- Using the XML Schema Changes 2.0.0
- -----
- Vincent Siveton
- ------
- 2009-10-02
- ------
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
-~~ Licensed to the Apache Software Foundation (ASF) under one
-~~ or more contributor license agreements. See the NOTICE file
-~~ distributed with this work for additional information
-~~ regarding copyright ownership. The ASF licenses this file
-~~ to you under the Apache License, Version 2.0 (the
-~~ "License"); you may not use this file except in compliance
-~~ with the License. You may obtain a copy of the License at
-~~
-~~ http://www.apache.org/licenses/LICENSE-2.0
-~~
-~~ Unless required by applicable law or agreed to in writing,
-~~ software distributed under the License is distributed on an
-~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-~~ KIND, either express or implied. See the License for the
-~~ specific language governing permissions and limitations
-~~ under the License.
+http://www.apache.org/licenses/LICENSE-2.0
-~~ NOTE: For help with the syntax of this file, see:
-~~ http://maven.apache.org/doxia/references/apt-format.html
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
-Using the XML Schema Changes 2.0.0
+# Using the XML Schema Changes 2.0.0
- The Changes XSD is located {{{https://maven.apache.org/xsd/changes-2.0.0.xsd}here}}.
+The Changes XSD is located [here](https://maven.apache.org/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:
+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:
-+-----+
+```xml
<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 https://maven.apache.org/xsd/changes-2.0.0.xsd">
...
</document>
-+-----+
+```
