From 6d86e60b9616253235f69fe3984e4565d3a710f5 Mon Sep 17 00:00:00 2001 From: acalcutt Date: Sun, 16 Mar 2025 22:37:44 -0400 Subject: [PATCH] Update PUBLISHING.md --- PUBLISHING.md | 125 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 102 insertions(+), 23 deletions(-) diff --git a/PUBLISHING.md b/PUBLISHING.md index df21ab3..6c25f77 100644 --- a/PUBLISHING.md +++ b/PUBLISHING.md @@ -1,33 +1,112 @@ -# Publishing new version with github workflow +# Publishing a New Version -1.) Change the version number in package.json. Run the following command in the package root directory, replacing with one of the semantic versioning release types (prerelease, prepatch, preminor, premajor, patch, minor, major): -npm version --preid pre --no-git-tag-version +This document outlines the process for publishing new versions of this project. We use a GitHub workflow for automated releases, but also provide manual steps for specific situations. ---preid specifies which suffix to use in the release such as pre, next, beta, rc, etc. +## Automated Publishing via GitHub Workflow (Recommended) -prepatch, preminor, and premajor start a new series of pre-releases while bumping the patch, minor, or major version. E.g. premajor with --preid pre would do a prerelease for a new major using the -pre suffix (i.e. it would be a new major with -pre.0) +This is the preferred method for publishing new versions. It automates the entire process, including version bumping, tagging, building, and publishing. We primarily use the "pre" pre-release identifier. -You can use prerelease to bump the version for a new pre-release version. E.g. you could run npm version prerelease --preid pre --no-git-tag-version to go from -pre.0 to -pre.1. +1. **Prepare the Release:** -For regular versions, you can use patch, minor, or major. E.g. npm version major --no-git-tag-version. + * **Choose the Version Increment:** Determine the appropriate semantic versioning increment (prerelease, prepatch, preminor, premajor, patch, minor, major). Refer to [Semantic Versioning](https://semver.org/) for guidance. -2.) Update the changelog, which can be found in CHANGELOG.md. The heading must match ## exactly, or it will not be picked up. For example, for version 5.0.0: -```## 5.0.0``` + * **Update `package.json`:** Use the `npm version` command to bump the version number. This command also supports creating pre-release versions using the `--preid pre` flag. -3.) Commit and push the changes. + ```bash + # Example: Increment to a new patch version + npm version patch --no-git-tag-version -4.) Run the 'Build, Test, Release' github workflow. The workflow will create a NPM, Docker, and Github release and Tag. + # Example: Increment to a new minor version + npm version minor --no-git-tag-version -# Publishing new version manually + # Example: Increment to a new major version + npm version major --no-git-tag-version -- Update version in `package.json` -- `git tag vx.x.x` -- `git push --tags` -- `docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl:latest -t maptiler/tileserver-gl:[version] .` -- `docker push maptiler/tileserver-gl --all-tags` -- `npm publish --access public` or `node publish.js` -- `node publish.js --no-publish` -- `cd light` -- `docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl-light:latest -t maptiler/tileserver-gl-light:[version] .` -- `docker push maptiler/tileserver-gl-light --all-tags` -- `npm publish --access public` + # Example: Create a pre-release (e.g., -pre.0) version + npm version prepatch --preid pre --no-git-tag-version + # OR + npm version preminor --preid pre --no-git-tag-version + # OR + npm version premajor --preid pre --no-git-tag-version + + # Example: Increment an existing pre-release version (e.g., -pre.0 to -pre.1) + npm version prerelease --preid pre --no-git-tag-version + ``` + + * `--no-git-tag-version`: This prevents `npm version` from automatically creating a git tag, as the GitHub workflow will handle this later. + * `--preid pre`: Specifies that "pre" is the pre-release identifier. + + * **Update the Changelog (`CHANGELOG.md`):** Add a new section for the release. The heading *must* exactly match the format `## `, where `` is the full version number from `package.json`. Describe the changes included in the release. + + ```markdown + ## 1.2.3 + * Added new feature X. + ``` + +2. **Commit and Push:** Commit the changes to `package.json` and `CHANGELOG.md` to a branch. Create a pull request (PR) for review. If you are an administrator, you may push directly, but a PR is generally recommended for code review. + +3. **Run the GitHub Workflow:** Once the PR is merged (or changes pushed directly), trigger the "Build, Test, Release" GitHub workflow. This workflow is responsible for: + + * Building the project. + * Running tests. + * Creating an NPM package. + * Building and pushing Docker images. + * Creating a GitHub Release. + * Creating a Git tag for the release. + +## Manual Publishing (For Special Cases) + +Use the following steps *only* when the automated workflow is not suitable (e.g., for debugging, specific environment needs). + +1. **Update Version in `package.json`:** Modify the `version` field in `package.json` to the desired version number. + +2. **Create and Push Git Tag:** + + ```bash + git tag vX.X.X # Replace X.X.X with the version number + git push origin --tags + ``` + +3. **NPM Publish Options (Choose ONE):** + + * **Option A: Publish only the full `tileserver-gl` version:** + + ```bash + npm publish --access public + ``` + + * **Option B: Build and Publish both `tileserver-gl` and `tileserver-gl-light` using `publish.js`:** + + ```bash + # This script builds the light version and publishes both tileserver-gl and tileserver-gl-light to NPM. + node publish.js + ``` + + * **Option C: Build only the `tileserver-gl-light` version (no publish):** + + ```bash + # This script ONLY builds the light version (e.g., for local testing or Docker image creation) without publishing. + node publish.js --no-publish + ``` + +4. **Build and Push Docker Images:** + + ```bash + # Build the main image + docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl:latest -t maptiler/tileserver-gl:X.X.X . # Replace X.X.X + docker push maptiler/tileserver-gl --all-tags + + # Build the light image + cd light + docker buildx build --platform linux/amd64 -t maptiler/tileserver-gl-light:latest -t maptiler/tileserver-gl-light:X.X.X . # Replace X.X.X + docker push maptiler/tileserver-gl-light --all-tags + cd .. # Return to the project root + ``` + * Make sure you are logged into the docker registry before pushing. `docker login` + +**Important Considerations for Manual Publishing:** + +* **Consistency:** Ensure the version number in `package.json`, the Git tag, and the Docker image tags are identical. +* **Credentials:** Verify that you have the necessary permissions to push Docker images and publish to NPM. +* **Cleanliness:** Before building Docker images, ensure your working directory is clean to avoid including unwanted files in the image. +* **Error Handling:** Manually publishing is more prone to errors. Double-check each step to avoid issues.