Announcement collides with ${changes.version} property

You have misunderstood the purpose of this parameter. The use case for it is to override the project.version of the artifact you are announcing. It does not specify the version of the changes plugin in any way.

The current doc for the parameter says:

"Version of the artifact."

How can we improve this text to prevent this from happening to others?

Well I did read about the version parameter but I was not aware of the fact that $

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <configuration>
    <version>2.0</version>
  </configuration>
</plugin>

<properties>
  <changes.version>2.0</changes.version>
</properties>

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <version>{${changes.version}}</version>
  <configuration>
    <onlyCurrentVersion>true</onlyCurrentVersion>
  </configuration>
  <reportSets>
    <reportSet>
      <reports>
        <report>jira-report</report>
      </reports>
    </reportSet>
  </reportSets>
</plugin>

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <version>{${changes.version}}</version>
  <configuration>
    <onlyCurrentVersion>true</onlyCurrentVersion>
    <generateJiraAnnouncement>true</generateJiraAnnouncement>
  </configuration>
</plugin>

supersedes this. If this was clear to anyone else then I'm fine with closing this issue as invalid or whatever. If that is not the case extending the version parameter description should be sufficient, e.g.:

"Version of the artifact. Defaults to $

or $

."

Sebastian,

You misunderstood me again.

The following section does not set the version of maven-changes-plugin. It tells maven-changes-plugin that you want to fetch issues for version 2.0 of your own artifact from your project's JIRA.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <configuration>
    <version>2.0</version>
  </configuration>
</plugin>

The following section has no meaning at all with regards to maven-changes-plugin.

<properties>
  <changes.version>2.0</changes.version>
</properties>

In the following section, you should not use changes.version, but the actual version of maven-changes-plugin that you want to use. I'd recommend the 2.2 version.

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <version>{${changes.version}}</version>
  <configuration>
    <onlyCurrentVersion>true</onlyCurrentVersion>
  </configuration>
  <reportSets>
    <reportSet>
      <reports>
        <report>jira-report</report>
      </reports>
    </reportSet>
  </reportSets>
</plugin>

Now, the correct way to configure this is:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-changes-plugin</artifactId>
  <version>2.2</version>
  <configuration>
    <onlyCurrentVersion>true</onlyCurrentVersion>
  </configuration>
  <reportSets>
    <reportSet>
      <reports>
        <report>jira-report</report>
      </reports>
    </reportSet>
  </reportSets>
</plugin>

The plugin will pick up the version of your artifact from the <project>/<version> element of your artifacts POM. This is the default behavior and does not normally need to be changed.

If you want to change the version that you are releasing, and I don't think that you need to, you can do this in two ways. Either you add a <configuration>/<version> element to the plugin configuration in your POM, thereby telling maven-changes-plugin that you want to fetch issue for that particular version from JIRA. Or you can add a command line parameter when you invoke Maven, like this if you want to fetch issues for version 4.6 from JIRA:

mvn changes:announcement-generate -Dchanges.version=4.6

Ok I think this is more of a language related issues. I'll try again with a more complete example:

<project>
  <properties>
    <changes.version>2.2</changes.version>
  </properties>

  <build>
    <plugins>

      ...

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>{${changes.version}}</version>
        <configuration>
          <onlyCurrentVersion>true</onlyCurrentVersion>
          <generateJiraAnnouncement>true</generateJiraAnnouncement>
        </configuration>
      </plugin>

      ...

    </plugins>
  </build>
  <reporting>
    <plugins>
      
      ...

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-changes-plugin</artifactId>
        <version>{${changes.version}}</version>
        <configuration>
          <onlyCurrentVersion>true</onlyCurrentVersion>
        </configuration>
        <reportSets>
          <reportSet>
            <reports>
              <report>jira-report</report>
            </reports>
          </reportSet>
        </reportSets>
      </plugin>
      
      ...

    </plugins>
  </reporting>
</project>

So what I was trying to do was to set the version of the maven-changes-plugin itself via the changes.version property. I did not know that this property sets the version parameter of the maven-changes-plugin (again not the version of the plugin itself) and did not find anything regarding the changes.version property anywhere in the plugin documentation. On a closer look though the information is right there, yet slightly hidden[1]. I never paid much attention to those expressions since I don't like to specify properties via the command line but rather have them all in my POM and never "collided" with any other plugin specific expression before. Lesson learned I guess

[1]: http://maven.apache.org/plugins/maven-changes-plugin/announcement-generate-mojo.html#version

One thing I do to avoid problems like this is to avoid using dots when naming properties. So in your example I would name the property "changesVersion" instead of "changes.version".

We have a naming convention for plugin parameters that are specified on the command line. It looks loosely like this:
<plugin-name>.<property-name>

It isn't implemented everywhere, but at least new parameters use that convention. So staying away from naming your own properties in that way can help you avoid confusion.