For a normal commit: Just push to the master branch, wait about 10 minutes and check Travis (https://travis-ci.org/Internet2/grouper) for a successful build
For a numbered release:
- Tag the desired commit with string GROUPER_RELEASE_a.b.c (a, b, c are numbers)
- Check Travis (https://travis-ci.org/Internet2/grouper) in about 20 minutes to check for successful build and upload to Sonatype
- Log into Sonatype (https://oss.sonatype.org/) (as of Feb 2020 this is a shared password), find the current artifact set among the staging repositories
- Promote the directory from closed to release
- Confirm current version of artifacts appear in Sonatype releases (https://oss.sonatype.org/#nexus-search;quick~grouper-parent)
- wait a few hours, then confirm they were propagated to the Maven repositories (e.g. https://search.maven.org/artifact/edu.internet2.middleware.grouper/grouper-parent)
Grouper is configured against Travis CI to execute the full build on every commit. For tags matching a specific pattern of "GROUPER_RELEASE_a.b.c(rc#)" it will also build release artifacts using that version from the tag, and publish those artifacts to the Maven Sonatype repository. There is an Internet2/Grouper account in Travis connected to the Grouper Github repository, and you (?) should have access to view the Travis build status if you have developer access in Github (CR Feb/2020 not sure about this). .
Travis builds all grouper branches where there is a .travis.yml at the root of the repository, as long as the current branch is specified as an allowed branch in that file. This is a YAML configuration that tells Travis what version of Java should be available, which commands to use for the build lifecycle and which scripts to execute after a successful build. Before Grouper 2.5.0, the Travis setup included a post-build step to publish the Maven snapshot artifacts to the Sonatype snapshot repository. As of version 2.5.0, this no longer publishes snapshot artifacts, as they were of limited use. Instead, it simply does a `mvn package` phase of grouper-parent (repeated for the set of Java vendors and versions defined in the YAML file) to test for a successful build of all projects. If the Travis build status for the current branch changes from success->fail or fail->success, the committer should get an email reporting the status change.
For a pushed tag that matches GROUPER_RELEASE_n.n.n or GROUPER_RELEASE_n.n.n"rc"n, a second Travis job will be initiated. As with normal commits, the job will start with a maven "package" goal for all defined Java targets. If successful, the next step will be to execute the script travis/deploy-to-sonatype.sh, to rebuild the artifacts as release versions and publish them to our Sonatype staging repository. The script will parse out the dotted version out of the tag string, update the versions in the pom.xml, rebuild all the projects, generate source and javadoc artifacts, and then sign them with an included PGP key. Finally, the script will deploy all these artifacts and associated pgp signatures (*.asc files) to the Sonatype staging repository.
If successful, the artifacts will appear in a new folder in our Sonatype staging repository (https://oss.sonatype.org/), Currently (Feb 2020), there is a shared account to access this repository. A subfolder will appear with a name such as "eduinternet2middlewaregrouper-####". The status should be "closed", indicating that Travis was able to finalize its upload of the artifacts. In this state, the repository can be tested as a private repository, by adding it as a profile in maven settings.xml (see below), or it can be promoted to "release" which will publish it in the public repository. After being released, the artifacts will eventually be propagated to other Maven repository sites, such as https://search.maven.org/ and https://mvnrepository.com/.
Testing the staging repository before release
This step will not be needed often, but can be useful when verifying jar files before they are irrevocably published. For this, add to ~/.m2/settings.xml
Then, when running maven commands, include parameter `-P grouper-stage` to activate the profile. Maven downloads will then use this location as an additional download source.
Notes on encrypting values for Travis
Because Travis requires certain secrets for the Sonatype login and PGP encryption to be accessible via a Git repository, encrypted versions of the files can be stored and then decrypted as needed by the Travis jobs. If a value needs to be modified or added, There is a ruby-based script that can do the encryption. It can be installed in a custom Docker container as a one-off process, or installed directly on a Unix workstation. The following steps have been successful in getting a working Docker container for the travis client.
1) Install an improved RNG service on the host
sudo apt install rng-tools5
sudo rngd -r /dev/urandom
2) Set up a new API key in your Github account
- Go to https://github.com/settings/tokens
- Generate a personal access token (name "travis command line client", access read:org, repo:status, repo_deployment, user:email, write:repo_hook)
- Record the resulting API token, since it won't be repeated
If you try to execute `travis login` without setting up the api key, you will get an email detailing these same steps
3) Initialize the docker container
4) Log into the travis client
(result: Successfully logged in as <github-account>!)
5a) Encrypt a value
The result will go into .travis.yml, added to the section:
5b) OR encrypt a file
The resulting encrypted file can then be added to the Git repository (preferably the /travis/ subdirectory). The output will give helpful information on additional openssl job steps to be added to .travis.yml that will decrypt the file before it is needed.