Release Process

Prerequisites

Because the version number is present in a few places in the sources (schema, example data, example metadata), some additional steps are required when creating a release tag. The steps are roughly these:

1. create a branch
2. update version numbers to the release version
3. create and push the release tag
4. update version numbers back to the dev version
5. merge the branch

Updating the version numbers in the example data and example metadata currently require Python and additional Python packages. These dependencies are managed with Poetry. Before going through the steps to create a release, you need to have Poetry and the example dependencies installed. After installing Poetry, you can change into the scripts directory and poetry install to install the example dependencies.

Create a release branch

In order to make these release-related changes, create a branch in your repository clone. Note that all the examples below use ${R1} as the target release version (the one being created), ${R0} as the current dev version, and ${R2} as the next dev version. You'll want to use the appropriate version numbers for the release you're working toward.

Set the R0, R1, and R2 variables. For example:

R0=0.5.0-dev    # current dev version
R1=1.0.0-beta.1 # target release version
R2=1.0.0-dev    # next dev version

Check out a new release branch (this assumes you have named the canonical remote ogc):

git fetch ogc
git checkout -b release-v${R1} ogc/main

Update the version in schema.json

Update the version numbers in format-specs/schema.json to reflect the target release.

# mac flavor sed
sed -i '' "s/\"const\": \"${R0}\"/\"const\": \"${R1}\"/" format-specs/schema.json

Update the version in geoparquet.md

Update the version numbers in format-specs/geoparquet.md to reflect the target release.

# mac flavor sed
sed -i '' "s/version ${R0}/version ${R1}/" format-specs/geoparquet.md

Update the example and extracted metadata

To propagate the version change to the example data and metadata, run the following:

pushd scripts
poetry run python generate_example.py
poetry run python update_example_schemas.py
popd

⚠️ Check through the repo to find any other version numbers that might need changing (e.g. in examples/example_metadata_point.json). Update these to match the release version. After #232 is addressed, this step should go away.

Create a release pull request

Review and commit the version changes:

git add format-specs examples
git commit -m "Updates for the ${R1} release"

Push the release branch changes.

git push ogc release-v${R1}

Create a pull request for the release branch, but do not merge it yet. Review the changes and make sure the CI jobs for the branch succeed.

Tag

After the CI jobs for the release pull request pass, tag the release (before merging the release branch):

# tag the latest from ogc/release-v${R1}
git tag -a v${R1} -m "${R1}"

# push the tag
git push ogc v${R1}

Monitor jobs and publish the draft GitHub release

Pushing the tag will trigger a Release workflow that will create a draft GitHub release from the tag. Wait for the Release workflow jobs to complete and then visit the draft release. Edit the draft and update the changelog with any additional notes and click the "Publish Release" button.

Update version numbers back to the dev version

Back on the release branch (git checkout release-v${R1}), edit the version numbers in the schema.json and geoparquet.md files:

# mac flavor sed
sed -i '' "s/\"const\": \"${R1}\"/\"const\": \"${R2}\"/" format-specs/schema.json
sed -i '' "s/version ${R1}/version ${R2}/" format-specs/geoparquet.md

Propagate this change to the examples data and metadata:

pushd scripts
poetry run python generate_example.py
poetry run python update_example_schemas.py
popd

⚠️ Check through the repo to find any other version numbers that might need changing (e.g. in examples/example_metadata_point.json). Update these to match the dev version. After #232 is addressed, this step should go away.

Commit and push these changes:

git add format-specs examples
git commit -m "Develop on ${R2}"
git push ogc release-v${R1}

Merge the release branch and update the website

Give the pull request for the release branch a final review, and merge it into main.

Update the geoparquet.org website by running the Publish Website workflow for the website repository. Find the "Run workflow" drop-down, choose the main branch, and click the "Run workflow" button. This will update the website with the latest GeoParquet release.