Avoid Hardcoding Version in pom.xml and Use Git Version Instead

[vchendrix]

The pom.xml file currently has the version hardcoded as 2.0.0. This can lead to issues with maintaining and updating the version across different branches and releases. It would be more efficient to dynamically retrieve the version from the git tags.

Proposed Solution

• Modify the pom.xml configuration to use a plugin that can fetch the version from git tags.
• This change will ensure that the version is always in sync with the current git tag, reducing the risk of discrepancies.

Implementation Example

To dynamically retrieve the version from git tags in the pom.xml of the NCEAS/osti-elink repository, follow these steps:

1. Add the Maven Git Versioning Plugin: Modify the pom.xml file to include the Maven Git Versioning Plugin.
2. Configure the Plugin: Update the pom.xml file to use the plugin for versioning.

Here’s how you can modify the pom.xml file:

Step 1: Add the Plugin

Insert the following configuration into the <build> section of your pom.xml file:

<plugin>
    <groupId>pl.project13.maven</groupId>
    <artifactId>git-commit-id-plugin</artifactId>
    <version>4.0.0</version>
    <executions>
        <execution>
            <goals>
                <goal>revision</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
        <generateGitPropertiesFile>true</generateGitPropertiesFile>
        <gitPropertiesFile>${project.build.outputDirectory}/git.properties</gitPropertiesFile>
    </configuration>
</plugin>

Step 2: Update the Version Property

Replace the hardcoded version with a property that pulls from the git commit ID:

<properties>
    <revision>${git.commit.id.describe}</revision>
</properties>
<version>${revision}</version>

Example Updated pom.xml

Here’s how the relevant sections of your pom.xml will look after making these changes:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>edu.ucsb.nceas</groupId>
    <artifactId>osti-elink</artifactId>
    <properties>
        <revision>${git.commit.id.describe}</revision>
    </properties>
    <version>${revision}</version>
    <build>
        <plugins>
            <!-- Other plugins -->
            <plugin>
                <groupId>pl.project13.maven</groupId>
                <artifactId>git-commit-id-plugin</artifactId>
                <version>4.0.0</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>revision</goal>
                        </goals>
                    </execution>
                </executions>
                <configuration>
                    <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
                    <generateGitPropertiesFile>true</generateGitPropertiesFile>
                    <gitPropertiesFile>${project.build.outputDirectory}/git.properties</gitPropertiesFile>
                </configuration>
            </plugin>
        </plugins>
    </build>
</project>

Benefits

• Easier version management.
• Reduces the chances of human error when updating the version.

References

• Maven Git Versioning Extension

Now, the pom.xml will dynamically retrieve the version from the git tags, ensuring it is always in sync with the current git tag.

[mbjones]

While I like the automation this proposal would provide, it is also contrary to our current use of semantic versioning to clarify the intent and impact of a release. We specifically choose to use semver versions so that users of a software package can differentiate between patch releases, minor version increments, and major backwards-incompatible releases. This is important for determining upgrade impacts for libraries and packages as people migrate across versions. Consequently, we consider software release an intentional act of authorship, and not simply a side-effect of the software development process and commits. Our releases are tied to specific version tags in the release repository, and git commit hashes have no specific semantics wrt releases (i.e., while each tagged release is associated with a specific commit hash, there are many commit hashes that are not associated with a versioned release and should not be considered releases per se (particularly commit hashes from development branches).

If we were to add automation to sync versions, I think it should be tied to git tags rather than commit hashes.