release-procedure.txt

=============================================================================================================================================
=============================================================================================================================================
GedcomX Release Procedure: (The 'SETUP - required before releasing the project' section below must be completed to be able to release GedcomX)

1. IMPORTANT NOTE: We are currently maintaining two release lines/branches for gedcomx-java;
   a. WE ARE NO LONGER MAINTAINING OR PUBLISHING THE 2.x.x RELEASE LINE/v2.x.x branch.
   b. The 3.x.x release line/v3.x.x branch is for those projects still using Jackson 2/Spring Boot 3.
      i. To pull and track this branch locally use the following commands:
          1. git checkout -b v3.x.x origin/v3.x.x
          2. git branch --set-upstream-to=origin/v3.x.x v3.x.x (this command may not be required)
   c. The 4.x.x release line/master branch is for those projects using Jackson 3/Spring Boot 4 and higher.

2. Check changes into the master branch, build it, and then release it as specified in steps 6 through 8 below.
3. Switch to the v3.x.x branch
      i. git checkout v3.x.x
4. Cherry-pick the desired change(s) since the last release from the master branch to the v3.x.x branch
      i. git cherry-pick <commitId>
5. Build and release the 3.x.x branch as specified in steps 6 through 8 below.


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

    ************************************************************************************************************************************************
    ********************* NOTE:  MAKE SURE YOU ARE USING Java 17 for the 3.x.x release line, Java 17 for the 4.x.x release line ********************
    ************************************************************************************************************************************************

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

    ************************************************************************************************************************************************
    ********************* NOTE:  MAKE SURE YOU ARE USING Java 17 for the 3.x.x release line, Java 17 for the 4.x.x release line ********************
    ************************************************************************************************************************************************

    Example:
        export THIS_RELEASE_VERSION=3.59.0; \
        export NEXT_SNAPSHOT_VERSION=3.60.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)


8. 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 published
        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. The new components could possibly be on maven central within 10 minutes, probably within 2 hours, but it could be longer.
        Updates to search.maven.org can take longer.
            See:
                https://central.sonatype.com/search?q=gedcomx
                https://repo1.maven.org/maven2/org/gedcomx/


        If you try to use the artifact before it is available in 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 account login at the Central Repository.

      A.  Follow the instructions at https://central.sonatype.org/register/central-portal/ to create an account.
          You can use any email address, 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
          We haven't done this since OSSRH was retired; we will figure it out when we need to add another user.

      C. Add your sonatype user token to your local maven settings.xml by following the instructions at
          https://central.sonatype.org/publish/generate-portal-token/ to generate a user token and add it to your settings.xml file.

            - 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 (OSSRH has been retired; this has instructions for migrating)

https://central.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.

        General public repository group at sonatype that contains snapshots and releases
            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.
              https://search.maven.org/search?q=gedcomx
              https://repo1.maven.org/maven2/org/gedcomx
              https://repo.maven.apache.org/maven2/org/gedcomx


        - FamilySearch artifactory repository.  You must be vpn'ed in to access this.
              https://familysearch.jfrog.io/ui/packages/gav:%2F%2Forg.gedcomx:gedcomx-model?name=gedcomx-model&type=packages


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 minutes to 2 hours so far.