Add release processes to Developer Docs (#3195)

Co-authored-by: Chris Galvan <[email protected]>

.github/workflows/gh-pages-mdbook.yml

@@ -20,6 +20,8 @@ jobs:
       - name: Install Dependencies
         shell: bash
         run: sudo apt-get install -y libwayland-dev libxkbcommon-dev # Required for winit
+      - name: Install mdbook-alerts
+        run: cargo install mdbook-alerts
       - name: Build
         working-directory: docs/mdbook
         shell: bash

docs/mdbook/src/SUMMARY.md

@@ -4,14 +4,18 @@
 
 - [Platforms](./platforms.md)
 
+- [Release Policy](./release-policy.md)
+
 - [Android](./android/README.md)
   - [Tests](./android/android-tests.md)
   - [Documentation](./android/android-documentation.md)
   - [Benchmark](./android/benchmark.md)
+  - [Release](android/release.md)
 
 - [iOS](./ios/README.md)
   - [Tests](ios/ios-tests.md)
   - [Documentation](ios/ios-documentation.md)
+  - [Release](ios/release.md)
 
 - [Design](./design/README.md)
   - [Ten Thousand Foot View](design/ten-thousand-foot-view.md)

docs/mdbook/src/android/release.md

@@ -0,0 +1,38 @@
+# Release MapLibre Android
+
+We make MapLibre Android releases as a downloadable asset on [GitHub](https://github.com/maplibre/maplibre-native/releases?q=android&expanded=true) as well as to [Maven Central](https://central.sonatype.com/artifact/org.maplibre.gl/android-sdk/versions). Specifically we make use of a Sonatype OSSHR repository provided by Maven Central.
+
+Also see the current [release policy](../release-policy.md).
+
+## Making a release
+
+To make an Android release, do the following:
+
+1. Prepare a PR.
+
+    - Update [`CHANGELOG.md`](https://github.com/maplibre/maplibre-native/blob/main/platform/android/CHANGELOG.md) in a PR, see for example [this PR](https://github.com/maplibre/maplibre-native/pull/3194). The changelog should contain links to all relevant PRs for Android since the last release. You can use the script below with a [GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `public_repo` scope. You will need to filter out PRs that do not relate to Android and categorize PRs as features or bugfixes.
+        ```
+        GITHUB_ACCESS_TOKEN=... node scripts/generate-changelog.mjs android
+        ```
+        The heading in the changelog must match `## <VERSION>` exactly, or it will not be picked up. For example, for version 9.6.0:
+        ```md
+        ## 9.6.0
+        ```
+
+    - Update `android/MapLibreAndroid/gradle.properties` with the new version.
+
+2. Once the pull request updating the changelog is merged, tag the commit:
+
+    - Create a tag locally, with for example:
+      ```
+      git tag -a android-v9.6.0 -m "Release android-v9.6.0"
+      ```
+    - You need write access to push the tag, use for example:
+      ```
+      git push --atomic origin main android-v9.6.0
+      ```
+
+3. Once the tag is pushed, you can run the [`android-release.yml`](https://github.com/maplibre/maplibre-native/blob/main/.github/workflows/android-release.yml) workflow.
+
+    - Open the [android-release](https://github.com/maplibre/maplibre-native/actions/workflows/android-release.yml) workflow page.
+    - Press *Run workflow* and select the tag you pushed.

docs/mdbook/src/ios/release.md

@@ -0,0 +1,33 @@
+# Release MapLibre iOS
+
+We make iOS releases to GitHub (a downloadable XCFramework), the [Swift Package Index](https://swiftpackageindex.com/maplibre/maplibre-gl-native-distribution) and [CocoaPods](https://cocoapods.org/). Everyone with write access to the repository is able to make releases using the instructions below.
+
+Also see the current [release policy](../release-policy.md).
+
+## Making a release
+
+1. Prepare a PR, see [this PR](https://github.com/maplibre/maplibre-native/pull/3193) as an example.
+
+    - Update the [changelog](https://github.com/maplibre/maplibre-native/blob/main/platform/ios/CHANGELOG.md). The changelog should contain links to all relevant PRs for iOS since the last release. You can use the script below with a [GitHub access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with the `public_repo` scope. You will need to filter out PRs that do not relate to iOS.
+      ```
+      GITHUB_ACCESS_TOKEN=... node scripts/generate-changelog.mjs ios
+      ```
+      The heading in the changelog must match `## <VERSION>` exactly, or it will not be picked up. For example, for version 6.0.0:
+      ```md
+      ## 6.0.0
+      ```
+    - Update the `VERSION` file in `platform/ios/VERSION` with the version to be released. We use [semantic versioning](https://semver.org/), so any breaking changes require a major version bump. Use a minor version bump when functionality has been added in a backward compatible manner, and a patch version bump when the release contains only backward compatible bug fixes.
+
+2. Once the PR is merged the `ios-ci.yml` workflow will detect that the `VERSION` file is changed, and a release will be made automatically.
+
+## Pre-release
+
+Run the `ios-ci` workflow. You can use the [GitHub CLI](https://cli.github.com/manual/gh_workflow_run):
+
+```
+gh workflow run ios-ci.yml -f release=pre --ref main
+```
+
+Or run the workflow from the Actions tab on GitHub.
+
+The items under the `## main` heading in `platform/ios/CHANGELOG.md` will be used as changelog for the pre-release. 

docs/mdbook/src/release-policy.md

@@ -0,0 +1,22 @@
+# Release Policy
+
+> [!NOTE]  
+> The following release policiy applies specifically to MapLibre **Android** and MapLibre **iOS**.
+
+- We use [semantic versioning](https://semver.org/). Breaking changes will always result in a major release.
+- Despite having extensive tests in place, as a FOSS project we have limited QA testing capabilities. When major changes took place we may opt to put out a pre-release to let the community help with testing.
+- In principle the `main` branch should always be in a releasable state.
+- The release process is automated and documented (see [Release MapLibre iOS](./ios/release.md) and [Release MapLibre Android](./android/release.md)). Anyone with write access should be able to push out a release.
+- There is no fixed release cadence, but you are welcome to request a release on any of the communication channels.
+- We do not have long-term support (LTS) releases.
+- If you need a feature or a bugfix ported to and old version of MapLibre, you need to do the backporting yourself (see steps below). 
+
+## Backporting
+
+We understand that MapLibre is used in large mission critical applications where updating to the latest version is not always immediately possible. We do not have the capacity to offer LTS releases, but we do want to facilitate backporting.
+
+1. Create an issue and request that a branch is created from the release you want to target. Also mention the feature or bugfix you want to backport.
+2. Once the branch is created, make a PR that includes the feature or bugfix and that targets this branch. Also update the relevant changelog.
+3. When the PR is approved and merged, a release is attempted. If the release workflow significantly changed and the release fails, you may need to help to backport changes to the release workflow as well.
+
+The branch names for older versions follow a pattern as follows: `platform-x.x.x` (e.g. [`android-10.x.x`](https://github.com/maplibre/maplibre-native/tree/android-10.x.x) for the MapLibre Native Android 10.x.x release series). These branches have some minimal branch protection (a pull request is required to push changes to them).