JarCastingTrentino Open Data Super POM
Super POM used by Open Data in Trentino Java projects.
For common library toolkit see Tod Commons
Usage
Releases of the POM are on Central. To use it in your project, just write this in your project
<parent>
<groupId>eu.trentorise.opendata</groupId>
<artifactId>tod-super-pom</artifactId>
<version>#{version}</version>
</parent>
and copy plugins list like in Tod Commons pom:
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-release-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
</plugin>
<plugin>
...
</build>
Make sure to put a url tag with the correct github addreass, i.e.:
<url>https://github.com/opendatatrentino/tod-commons</url>
And put the scm:
<scm>
<url>${project.url}</url>
<connection>scm:git:${project.url}.git</connection>
<developerConnection>scm:git:${project.url}.git</developerConnection>
<tag>HEAD</tag>
</scm>
Deploy prerequisites
So far we only tried releasing from a Windows environment. Since Windows, Maven, Git and GPG don't play well together, we resorted to putting passwords in clear in maven .m2/settings.xml (which is not much secure..) and made a bat script to ease the process.
To deploy to Sonatype any tod project, you need this prerequisites:
- Register on sonatype to have username/passoword.
- Create GPG keys
- Edit Maven
.m2/settings.xmlin your user home
These three steps are only needed once for all the projects you might need to maintain.
1. Register to Sonatype
TODO write something
2. Create GPG keys
TODO write something
3. Edit Maven settings.xml
You will need to edit .m2/settings.xml of your user home to add passwords for Sonatype, Github and GPG
Sonatype
Put this in the <servers> section in .m2/settings.xml of your user home:
<server>
<id>sonatype-nexus-snapshots</id>
<username>YOUR_SONATYPE_USERNAME</username>
<password>YOUR_PASSWORD</password>
</server>
<server>
<id>sonatype-nexus-staging</id>
<username>YOUR_SONATYPE_USERNAME</username>
<password>YOUR_PASSWORD</password>
</server>
<server>
<id>ossrh</id>
<username>YOUR_SONATYPE_USERNAME</username>
<password>YOUR_PASSWORD</password>
</server>
GitHub access
For publishing websites to Gitub pages, you also need to put Github server OAuth token in settings.xml. NOTE: anybody with the OAuth token to programmatically access all of your repositories with the given permissions. As such, it is not ideal but it's the simplest to start with.
To get the token:
- Go to https://github.com/settings/applications
- Go to
personal access tokens -> Generate new token, and give only the following permissions :- repo
- public_repo
- user:email
Put this in the <servers> section in .m2/settings.xml of your user home:
<server>
<id>github</id>
<password>YOUR_OAUTH_TOKEN_HERE</password>
</server>
SSH keys
It may well happen that while releasing your maven hangs asking for a github password. To prevent this under linux you can set up ssh-agent with the following procedure: https://help.github.com/articles/generating-ssh-keys/
I couldn't manage to have ssh-agent working in Windows, so for windows release.bat requires more manual entering of passwords during execution.
GPG
To allow signing artifacts, put this in the <profiles> section in .m2/settings.xml of your user home:
<profile>
<id>ossrh</id>
<activation>
<activeByDefault>true</activeByDefault>
</activation>
<properties>
<gpg.executable>gpg2</gpg.executable>
<gpg.passphrase>YOUR_GPG_PASSPHRASE</gpg.passphrase>
</properties>
</profile>
Deploy snapshots
Before attempting deployment, make sure you meet the Deploy prerequisites.
Snapshots are deployed on Sonatype: https://oss.sonatype.org/content/repositories/snapshots/eu/trentorise/opendata/commons/tod-super-pom
with this command:
mvn clean deploy
In Netbeans, you can also:
right click on the project -> Custom -> Deploy to Sonatype
Release
Before attempting release, make sure you meet the Deploy prerequisites.
So far we tried releasing from a Windows and a Linux environment. Since Windows, Maven and Git don't play well together, we made a release.bat file to ease the process. You can use the script for this or other tod projects.
Release with bash file
todo describe. For now you can refer to following paragraph, just use release instead of release.bat
Release with .bat file
To print help, just type the command:
release.bat
To release my-program with version 1.2.3 , from your project root run release.bat followed by the release tag and the branch where you want to push:
path\to\release.bat my-program-1.2.3 master
If something goes wrong along the way just run release.bat to see help on how to recover.
By default the release will generate website with josman and try to send it to GitHub gh-pages branch. To prevent such behaviour, add -nosite parameter to the bat.
Manual release workflow
TODO make this a proper bash script
To check website docs before releasing:
mvn josman:site -Dsite.snapshot=true
Ideal commands workflow:
mvn release:clean
mvn release:prepare
mvn release:perform
Workflow when having problems with git:
mvn -DpushChanges=false release:clean release:prepare
git push origin master
git push origin PUT_REPO_NAME-X.Y.Z
release:perform
To make website:
mvn josman:site
To send website to gh-pages branch:
mvn com.github.github:site-maven-plugin:site
Credits
- David Leoni - DISI, University of Trento - [email protected]
