release-procedure.txt

=============================================================================================================================================
=============================================================================================================================================
Procedure:  (required setup must be completed first)

1. Make sure the project builds and you have checked in all of your changes.


2. mvn -B -Prelease clean release:clean release:prepare -Dtag=$THIS_RELEASE_VERSION -DreleaseVersion=$THIS_RELEASE_VERSION -DdevelopmentVersion=$NEXT_SNAPSHOT_VERSION release:perform

    Example:
        export THIS_RELEASE_VERSION=2.113.0; \
        export NEXT_SNAPSHOT_VERSION=2.114.0-SNAPSHOT; \
        mvn -B -Prelease clean release:clean release:prepare -Dtag=$THIS_RELEASE_VERSION -DreleaseVersion=$THIS_RELEASE_VERSION -DdevelopmentVersion=$NEXT_SNAPSHOT_VERSION release:perform;


        -B            Run in non-interactive (batch) mode  This means that the Release Plugin will obtain the required parameters from system
                        properties (set on the command line) or from a properties file (release.properties - which is created in release:prepare).
        -P release    Activate the "release" profile (Comma-delimited list of profiles to activate)
        clean             Clean the files and directories generated by Maven during its build
        release:clean     Clean up after a release preparation.   (makes sure you have a clean project to be released)
        release:prepare   Prepare for a release in SCM.  (Requires a Maven project to be executed, Executes as an aggregator plugin, creates release.properties)
              -D  Define a system property
                  -Dtag=$RELEASE_VERSION                        The SCM tag to use.
                  -DreleaseVersion=$RELEASE_VERSION             Default version to use when preparing a release or a branch.
                  -DdevelopmentVersion=$NEXT_SNAPSHOT_VERSION   Default version to use for new local working copy.
        release:perform   Perform a release from SCM.   (Checkout from SCM URL, Run predefined Maven goals to release project i.e deploy site-deploy)


3. Optional   If you now run 'git status' it may tell you that "Your branch is ahead of 'origin/master' by 2 commits". However your changes should actually
              be pushed to the master repository.  You can verify that at  https://github.com/FamilySearch/gedcomx-java/commits/master

        The maven release plugin runs 'git push git@github.com:FamilySearch/gedcomx-java.git refs/heads/master:refs/heads/master', but for some reason the
        local git tools show that local changes still need to be pushed to master.  You can fix this by running 'git fetch' or 'git pull' or even 'git push'
             See https://stackoverflow.com/questions/7365415/pull-only-repos-git-status-saying-the-branch-is-ahead-of-origin-master-why
                 https://stackoverflow.com/questions/2432579/git-your-branch-is-ahead-by-x-commits
        If you figure out why the maven release plugin leaves things looking like this let us know.



NOTES:  After you release you will have artifacts in your local repository with the new version, but that does not mean they have been sync'ed
        to maven central. You may delete these from your local .m2 repository if you wish.  If they are not on maven central anyone trying to
        use those versions, including FamilySearch build servers, will fail. When you successfully released, your components were published to
        maven central, possibly within 10 minutes, probably within 2 hours, but could be longer.  Updates to search.maven.org can take longer.
                See   http://central.maven.org/maven2/org/gedcomx/
                      https://search.maven.org/search?q=gedcomx

        If you try to use the artifact before it is available at maven central you will need to wait an additional 15 minutes before it will be
        available on the FamilySearch artifactory repository.  The FamilySearch artifactory repository keeps a 15 minute cache (or at least
        nexus did) before retrying to download from maven central again.  You may be able to work around this using mvn -U ...

        To see what would be changed, you could run:      mvn release:prepare -DdryRun=true
            run mvn release:clean to clean up afterwards

=============================================================================================================================================
=============================================================================================================================================
SETUP - required before releasing the project


1. Setting up an account to publish to the Central Repository. You will need to create a Sonatype Jira account login at the Central Repository.

      A.  Go to https://issues.sonatype.org/secure/Signup!default.jspa
              You can use any email but it may make it easier if you use name@familysearch.org

      B.  Get your sonatype username added as a member of the org.gedcomx group
              Talk to someone who has done it.  https://issues.sonatype.org/browse/OSSRH-45141

      C. Add your ossrh user token to your local maven settings.xml

            - Go to https://oss.sonatype.org/ and Log in in the top right
            - Select Profile in the top right drop down
            - Select User Token (instead of Summary) in the tab drop down
            - Click Access User Token (type your password again)
            - Cut and past the settings to the <servers> section of your Maven settings.xml - change "${server}" to "ossrh"
                The final should look something like this:
                        ...
                        <servers>
                          <server>
                            <id>ossrh</id>
                            <username>aHxB6UYz</username>
                            <password>x+zKbntg+XvbBqTuCPJuJEnq54vlGt/Fs1ohY2ABqQb3k</password>
                          </server>
                        </servers>
                        ...



2. Obtain and export the PGP_SECRET_KEYFILE for signing the jar files

    export PGP_SECRET_KEYFILE=~/.ssh/gedcomx/gedcomx-pgp-key.asc


=============================================================================================================================================
=============================================================================================================================================
Documentation from Sonatype


https://central.sonatype.org/pages/ossrh-guide.html

https://oss.sonatype.org/


Accessing Repositories

    The following repositories allow you to access your components in OSSRH directly. Users will simply get your components directly via the
    Central Repository, but for committers and other collaborators on your project this list might be useful.

        Repository URL for snapshot deployment and download access  (gedcomx does not publish snapshot builds)
            https://oss.sonatype.org/content/repositories/snapshots/
            https://oss.sonatype.org/content/repositories/snapshots/org/gedcomx/

        Repository URL for release deployment, no download access!  (THIS DOES NOT SEEM TO WORK?)
            https://oss.sonatype.org/service/local/staging/deploy/maven2/
            https://oss.sonatype.org/service/local/staging/deploy/maven2/org/gedcomx/

        General public repository group at sonatype that contains snapshots and releases
            https://oss.sonatype.org/content/groups/public/
            https://oss.sonatype.org/content/groups/public/org/gedcomx


        - Repository URL for staged/released artifacts at Sonatype, this repository is synced to the Maven Central Repository.
          You may look here to verify the project has been successfully staged/released at Sonatype (see notes below)
              https://oss.sonatype.org/content/repositories/releases/
              https://oss.sonatype.org/content/repositories/releases/org/gedcomx


        - Maven Central repository.  When its here then FamilySearch's artifactory will be able to pull it.
              http://central.maven.org/maven2/org/gedcomx/
              https://search.maven.org/search?q=gedcomx         search.maven.org can take longer to appear


        - FamilySearch artifactory repository.  You must be vpn'ed in to access this.
              https://familysearch.jfrog.io/familysearch/fs-maven-dev-virtual
              http://nexus.a.fsglobal.net/content/groups/dev/org/gedcomx


NOTES:  After Central Sync is activated, your future promotion will be synced automatically. The sync process runs roughly every 2 hours.
          See https://stackoverflow.com/questions/23235892/how-long-does-sonatype-staging-take-to-sync-my-artifacts-with-maven-central?rq=1
        Upon release, your component will be published to Central: this typically occurs within 10 minutes, though updates to search can take up to two hours.
          See https://central.sonatype.org/pages/ossrh-guide.html#releasing-to-central
        My conclusion is somewhere between 10 minutes and 2 hours to get to maven central.  I've seen it be from about 30 mins to 2 hours so far.