Maintainer Guidelines

thub# Merging pull requests

Pull requests should not be rebased (as this would rewrite git's history) but merged with the the latest master and merge as a none fast-forward merge into master. For example, to merge a pull request fix-xy from http://github.com/cboehme/metafacture-core the following git commands should be used:

# Bring master up-to-date:
git checkout master
git fetch
git rebase
# Fetch pull request:
git fetch http://github.com/cboehme/metafacture-core.git +fix-xy:cboehme-fix-xy
git checkout cboehme-fix-xy
# Merge master:
git merge master
# Run test cases, check commit, add fixup commits ...
# Merge into master
git checkout master
git merge --no-ff cboehme-fix-xy

The commit message of the merge command should follow this format:

Merge pull-request #PULLREQUEST-ID from cboehme/fix-xy

Quality checking by Sonarqube

The code is quality-checked by sonarqube. The result is uploaded to sonarcloud.io. For identifying the travis variable SONARCLOUD_TOKEN is used.

Releasing

We shall make releases quarterly. Approximate timetable is every Januar, April, July, October. We publish more often master-SNAPSHOT builds.

Releasing involves to first make and test the release candidate before actually make the release. Note that we provide a github release for manual download as well as a release on maven central to be consumed as a library.

It's good habit to use semantic versioning in release numbers A.B.C, i.e. increase A when it's a major release breaking backward compatibility; increase B when it got new features; increase C indicating bug-fixes. A suffix like rcN (where N is a number) indicates a release candidate (rc).

To upload to sonatype you need (as well for the release candidate as for the release) a gradle.properties in the root directory that looks like this:

signing.gnupg.executable=gpg  
signing.gnupg.useLegacyGpg=true  
signing.gnupg.homeDir=$e.g."~/.gnupg"  
signing.gnupg.keyName=$yourKeyName  
signing.gnupg.passphrase=$keysPassphrase
# depending on gradle plugin versions etc. you may need to use:
# signing.password=$keysPassphrase
# signing.keyId=$yourKeyName
# signing.secretKeyRingFile=$e.g."~/.gnupg/secring.gpg"
releaseRepositoryUrl=https://oss.sonatype.org/service/local/staging/deploy/maven2/  
releaseRepositoryUser=$yourSonatypeUsername  
releaseRepositoryPassword=$yourSonatypePassword 
snapshotRepositoryUrl=http://oss.sonatype.org/content/repositories/snapshots
snapshotRepositoryUser=$yourSonatypeUsername
snapshotRepositoryPassword=$yourSonatypePassword 

Publish master-SNAPSHOT builds

These are done more often, in irregular intervals. They are not considered stable and may break your application, so be caution when using them.

The process is equal to the making of a release candidate, but without making any tags:

1. build and upload the master-SNAPSHOT:

   git pull; git checkout master;
   

2. proceed as described in Release candidate - Upload to Sonatype

Release candidate

Release candidates should be tested by different people before releasing!

Prepare your release candidate

1. Make an rc-branch (necessary for gradle to pickup the proper name):

   git checkout -b A.B.C-rcN
   

(leave out the metafacture-core- to avoid later the git "error: src refspec ... matches more than one" when you push the annotated git tag for having a tag named the same as the branch is not possible.)

1. Optionally, you can now test the build locally by invoking a gradle target:

   ./gradlew assemble
   

Upload to Sonatype

1. Now you can build and upload the release candidate to sonatype (note that ./gradlew should inform you to make a "snapshot build". If the version doesn't end with -SNAPSHOT the artifacts will not be uploaded to sonatypes snapshot repository!):

   ./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishAllPublicationsToMavenRepository
   

2. Go to Sonatype's snapshot repository and type in the correct Version to see if it is already available there (can take some minutes). Example for 5.5.1-rc1-SNAPSHOT.

3. Make an annotated signed tag: (it's important to that after uploading to Sonatype's snapshot repository because otherwise the -SNAPSHOT will bot be appended to the release candidate thus will not land in snapshot repository)

   git tag -s metafacture-core-A.B.C-rcN
   

4. Push the annotated signed tag to github: git push origin tag metafacture-core-A.B.C-rcN

Publish to GithubPackages

1. Make an annotated signed tag if you haven't done that yet:

git tag -s metafacture-core-A.B.C-rcN

Push your properly named branch to GitHub. The -rc , part of the branch's name.Because there is fetch --no-tags in actions/checkout@v2 the -SNAPSHOT suffix will always be appended (in comparison to doing ./gradlew publishAllPublicationsToGitHubPackagesRepository locally, which will find the SCM tag). The publishing to GitHUb packages is triggered then. (if we don't want -SMAPSHOT we may want to remove the -SNAPHSOT in build.gradle:

if (grgit.branch.current().name.contains('-rc')) { ...
 return "${grgit.branch.current().name}-SNAPSHOT"
}

) Note that Packages is not the same as Releases.

Consume the SNAPSHOT

1. See e.g. Example for 5.5.1-rc1-SNAPSHOT how to configure the dependency
2. Configure your build system to use Sonatype's Snapshot Repository to be able to load the dependencies of the release candidate (or master-SNAPSHOT). For Maven update your pom.xml (after </dependencies>):

   <repositories>
       <repository>
           <id>oss.sonatype.org-snapshot</id>
           <url>https://oss.sonatype.org/content/repositories/snapshots</url>
           <releases>
                <enabled>false</enabled>
           </releases>
           <snapshots>
               <enabled>true</enabled>
           </snapshots>
       </repository>
   </repositories>

   For Gradle, add the snapshots repository:

   repositories {
       maven { url 'https://oss.sonatype.org/content/repositories/snapshots' }
   }

   For Leiningen, add this to your project.clj:

   :repositories [["snapshots" "https://oss.sonatype.org/content/repositories/snapshots"]]

   For sbt, add this to your build.sbt:

   resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
   

Making a release

It's going from your local git repo to Sonatype to Maven Central. Each station requires some manual actions so you can double check that everything is ok.

1. Make sure you have a signed tag locally:

   git show metafacture-core-A.B.C 
   

   If it doesn't exist yet, create it:

   git tag -s metafacture-core-A.B.C
   

2. When prompted, add a sensible commit message. For instance, something like:

   Release 5.7.0
   

3. Make sure you have that signed tag pushed to github:

   git ls-remote --tags origin
   

   If it is missing, push it with:

   git push origin  metafacture-core-A.B.C
   

4. Now the tag is available at github. You can manually choose to draft a new release on github. The *dist* files must be uploaded manually.

5. Make sure to have a clean git directory (otherwise only a SNAPSHOT will be build):

   git status
   

6. Let the release be build and uploaded (the SCM tag will be detected and the release be built):

   ./gradlew clean; ./gradlew publishToMavenLocal; ./gradlew publishAllPublicationsToMavenRepository
   

7. Finally, go to oss.sonatype.org , login, check the Staging Repositories and when it's finished, click on Close. If everything is good publish with clicking on Release - attention, because once published it can't be removed. The artifacts are uploaded to maven central (which may take some time). You can check that it's actually in the publishing pipeline by clicking on Views/Repositories->Releases, then type in the Path lookup field org/metafacture/ and click on version.

Release Metafacture-Fix

As long as we have two repos we should immediately also release metafacture-fix: Go update Metafacture-Fix and follow https://github.com/metafacture/metafacture-fix/wiki/Maintainer-Guidelines.