Skip to content

Tech: How to make a new JSON java release

Jump to bottom
Sean Leary edited this page Mar 3, 2024 · 31 revisions

JSON-Java releases are only for the purpose of checkpointing code changes for the public Maven repository. New releases do not require a fixed cadence. As long as the repository is relatively active, about every 4-6 months seems reasonable. Urgent fixes may require more frequent releases, but minor fixes and new features can wait. When you decide to release a new version, here are the steps to follow:

  • Decide on a commit checkpoint. Usually, this will be the latest commit.

  • Decide on a release label. We do not use semantic versioning for several reasons. Historical Maven releases have been by date, and changing the release label format could cause misordering in the Maven repository. The project is in maintenance mode - no design or major API changes are being accepted, so there is no need for major/minor or other release sequences. Instead, we use a simple date format: YYYYMMDD, which is the date of the release.

  • Create a pre-release branch and make these changes:

  • Update README.md "Click here" tag for the latest release. Note that it won't be accessible until the release is completed. The actual visible release number will be updated then as well (you don't change the tag image, it is remote).

  • Update Release.md with the release number and title.

  • Update the pom.xml with your release version and push to remote repository: <version>20201115</version>

  • Make a PR and immediately merge the branch to master.

  • On GitHub, navigate to Releases > Draft a new release. Choose a tag > (enter your release number) > Click Create new tag. Under Target, choose the master branch. For the title, use the release number. In the description, include a table in reverse chronological order of links to merged pull requests and 1-line descriptions. The top of the list should contain the latest pull request, and the bottom should contain the first pull request after the last release.

For more information about GitHub releases, see https://help.github.com/articles/creating-releases/

We also publish new releases to the Maven repository. The Maven JSON-Java project is hosted by Sonatype and published to the Maven Central repository.

First One time task to be done by the person responsible for Maven releases

  • Start here: https://central.sonatype.org/pages/ossrh-guide.html
  • Create an account to open a Jira case. This account will be the same one you will use to deploy new releases to Maven Central.
  • When claiming the org.json namespace, mention the current owner by sonatype username in the JIRA ticket, and send the owner an email with the ticket number. After the previous owner approves, they will handover the project.

Second One time task to be done by the person responsible for Maven releases Or when starting out with a new laptop

For an update on recently deprecated key servers, see https://central.sonatype.org/publish/requirements/gpg/#distributing-your-public-key

Create and upload gpg keys GitHub and a key server from the bash shell.

# create a new key, using name, comment, email, and passphrase
gpg --gen-key  
# look for the 'sec' line
gpg --list-secret-keys --keyid-format long 
# may not need this
git config user.signingkey (your secret key)
# get your public key
gpg --armor --export (your secret key pub string)
# In GitHub, click your profile pic, select settings > ssh & gpg keys, add the entire public key including framing
# Get your public key hash (I think)
gpg --list-keys
# may not need this - these files seem not to found here anymore - make sure your permissions are good 
chmod 400 /(directory)/.gnupg/gpg.conf
chmod 600 /(directory)/.gnupg
# recently keys.gnupg.net seems to have been deprecated, specify a different one
# $ gpg --keyserver keys.gnupg.net --send-keys (output from list-keys)
$ gpg --keyserver keyserver.ubuntu.com --send-keys (pub key string from list-keys)
gpg: sending key (key) to hkp://keyserver.ubuntu.com

Third One time task to be done by the person responsible for Maven releases Or when starting out with a new laptop

On your local machine, open a bash shell.

Create ~/m2/settings.xml with these contents:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <servers>
    <server>
      <id>ossrh</id>
      <username>yourSonatypeUsername</username>
      <password>yourSonatypePassword</password>
    </server>
  </servers>
</settings>

cd to the JSON-Java local repository

IMPORTANT Make sure you are using Java 8. On a mac with jenv, execute something like: jenv global 1.8

git checkout master
git pull
git status # to confirm no local changes
mvn clean deploy -Dgpg.passphrase="(your gpg passphrase)"

On a Windows PC you will be prompted for the passphrase again in a popup window. Enter it again.

Perform the Maven Release

Navigate to https://oss.sonatype.org and login. To bring up your project, click the Staging Repositories tab to view your repo. Select your project when it appears, it may take a few minutes. Look for The release button will be at top of the page, mid left. It may take a few minutes for it to activate. Just wait and click when you can. If prompted for a description, just enter the release number.

If successful, your project will be deployed to maven central

You may have to wait minutes, hours, or days for the deploy to publish. When it does, you can click the tag in Readme, or the Just the Jar button, to confirm your new release.

Search for group: org.json artifact: json

Update the JavaDocs

Someday this will be added to one of the pipelines. Until recently, the API never changed so this was not an urgent issue. But ongoing opt-in changes for the ParserConfiguration classes have resulted in a need to update at least every release. Go to this page and follow the instructions. Note that it can take up to an hour for the changes to be published:

https://github.com/stleary/JSON-java/wiki/Tech:-How-to-update-the-JavaDocs

Reference: https://github.com/BGehrels/JSON-java

Clone this wiki locally