mirror of
https://github.com/Alfresco/alfresco-sdk.git
synced 2026-09-09 18:03:59 +00:00
[ACS-12085] Release Process Documentation Update (#770)
This commit is contained in:
Somnath Deshmukh
@@ -177,16 +177,6 @@ To test new unreleased (unsupported) features, you can use the following snippet
|
||||
## For Developers that want to contribute to the SDK
|
||||
See the [Developers Wiki page](https://github.com/Alfresco/alfresco-sdk/wiki/Developer-Wiki).
|
||||
|
||||
## Publishing the release on Maven Central
|
||||
- Manually change the version from SNAPSHOT to final (eg. when releasing SDK 4.16.0, replacing all the occurrences of 4.16.0-SNAPSHOT with 4.16.0)
|
||||
## Releasing the SDK
|
||||
|
||||
- Commit and push changes to GitHub with the commit message [publish], then it will automatically publish your artifacts to maven central
|
||||
- Only GA versions is published to maven central, there is a check in the CI pipeline (called "check_version") to check if the version is non-GA or not, and if it's not, it will skip the "publish" step. Therefore, only "number.number.number" versions will be published to maven central, and any version with a suffix (eg. -Ax, -SNAPSHOT, -RC1, -beta-1) will not be published to maven central.
|
||||
|
||||
At this point, we need to manually proceed with the remaining steps:
|
||||
|
||||
1- Manually create a release tag on GitHub
|
||||
|
||||
2- Manually change the version from final to next SNAPSHOT (eg. replacing all the occurrences of 4.16.0-SNAPSHOT with 4.17.0 (in pom.xml, not in READMEs - if not needed)
|
||||
|
||||
3- Commit and push on GitHub
|
||||
See [docs/release-process.md](docs/release-process.md) for the current automated release process (Nexus, verified commits, tags, and Maven Central publishing).
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
# Alfresco SDK release process
|
||||
|
||||
This document describes how to release the Alfresco SDK using the automated CI pipeline introduced in [ACS-12085](https://hyland.atlassian.net/browse/ACS-12085).
|
||||
|
||||
Releases are performed on **`master`** via GitHub Actions. The pipeline uses [`maven-release-slim`](https://github.com/Alfresco/alfresco-build-tools) from Alfresco build-tools and a GitHub App installation token to create **verified** commits and tags.
|
||||
|
||||
## Version conventions
|
||||
|
||||
### Alpha versions (dot notation)
|
||||
|
||||
Alpha releases **must** use a dot between `A` and the alpha number:
|
||||
|
||||
| Correct | Incorrect |
|
||||
|---------|-----------|
|
||||
| `4.17.0-A.1` | `4.17.0-A1` |
|
||||
| `4.17.0-A.2` | `4.17.0-A2` |
|
||||
|
||||
Use this format in `RELEASE_VERSION`, Git tags, and Maven coordinates for all new alpha releases.
|
||||
|
||||
### Next development version (`-SNAPSHOT`)
|
||||
|
||||
`DEVELOPMENT_VERSION` **must** include the `-SNAPSHOT` suffix. This is the version written to all POMs after the release completes.
|
||||
|
||||
| Correct | Incorrect |
|
||||
|---------|-----------|
|
||||
| `4.17.0-A.3-SNAPSHOT` | `4.17.0-A.3` |
|
||||
| `4.18.0-SNAPSHOT` | `4.18.0` |
|
||||
|
||||
This applies to both alpha and GA release cycles.
|
||||
|
||||
## Overview
|
||||
|
||||
| Step | Trigger | CI job | Result |
|
||||
|------|---------|--------|--------|
|
||||
| Alpha / Nexus release | `[release]` in commit message | `release` | Deploy to Alfresco Nexus, Git tag, verified bot commits |
|
||||
| GA Maven Central publish | `[publish]` in commit message | `publish` | Publish to Maven Central (GA versions only) |
|
||||
|
||||
Alpha releases (for example `4.17.0-A.2`) are deployed to **Nexus only**. GA releases (for example `4.17.0`) can additionally be published to **Maven Central** using `[publish]`.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Merge your changes to **`master`** (or use a PR merged to `master`).
|
||||
- Ensure CI tests pass. Do not use `[skip tests]` on a release commit.
|
||||
- Confirm the repository has the `GH_APP_ENGINEERING_CONTRIB_CLIENT_ID` variable and `GH_APP_ENGINEERING_CONTRIB_PRIVATE_KEY` secret configured (DevOps).
|
||||
- Protected branches must allow verified commits from the engineering-contrib GitHub App.
|
||||
|
||||
## Configure release versions
|
||||
|
||||
Version numbers are **not** stored in `.github/workflows/ci.yml`. They live in [`.github/release-versions.yml`](../.github/release-versions.yml):
|
||||
|
||||
```yaml
|
||||
env:
|
||||
global:
|
||||
- RELEASE_VERSION=4.17.0-A.2
|
||||
- DEVELOPMENT_VERSION=4.17.0-A.3-SNAPSHOT
|
||||
```
|
||||
|
||||
| Variable | Purpose | Example (alpha) | Example (GA) |
|
||||
|----------|---------|-----------------|--------------|
|
||||
| `RELEASE_VERSION` | Version to release and tag | `4.17.0-A.2` | `4.17.0` |
|
||||
| `DEVELOPMENT_VERSION` | Next development version written to POMs after release (must end with `-SNAPSHOT`) | `4.17.0-A.3-SNAPSHOT` | `4.18.0-SNAPSHOT` |
|
||||
|
||||
Update both values in the **same commit** that triggers the release. The GitHub App bot does **not** modify this file; you must update it again before the next release.
|
||||
|
||||
> **Note:** Release versions are kept in `.github/release-versions.yml` (not in workflow files) so the GitHub App token does not require `workflows: write` permission.
|
||||
|
||||
## Alpha release (Nexus)
|
||||
|
||||
Example: release `4.17.0-A.3` when `master` is on `4.17.0-A.3-SNAPSHOT`.
|
||||
|
||||
1. Update [`.github/release-versions.yml`](../.github/release-versions.yml):
|
||||
|
||||
```yaml
|
||||
- RELEASE_VERSION=4.17.0-A.3
|
||||
- DEVELOPMENT_VERSION=4.17.0-A.4-SNAPSHOT
|
||||
```
|
||||
|
||||
2. Commit and push to **`master`** with `[release]` in the commit message, for example:
|
||||
|
||||
```text
|
||||
[release] Alfresco SDK 4.17.0-A.3 alpha
|
||||
```
|
||||
|
||||
3. Wait for the CI workflow to finish. The `release` job runs only when:
|
||||
- Tests succeed
|
||||
- The branch is `master`, `fix/**`, or `feature/**`
|
||||
- The commit message contains `[release]`
|
||||
- The commit message does **not** contain `[no release]`
|
||||
|
||||
### What happens automatically
|
||||
|
||||
When the `release` job succeeds, CI will:
|
||||
|
||||
1. Set all POM versions to `RELEASE_VERSION`
|
||||
2. Deploy artifacts to Alfresco Nexus
|
||||
3. Create a **verified** bot commit for the release version
|
||||
4. Create a Git tag named exactly `RELEASE_VERSION` (for example `4.17.0-A.3`)
|
||||
5. Set all POM versions to `DEVELOPMENT_VERSION`
|
||||
6. Create a **verified** bot commit for the next development version
|
||||
|
||||
You should **not** manually create Git tags or manually bump POM versions for the release and post-release commits; the pipeline handles that.
|
||||
|
||||
### After an alpha release
|
||||
|
||||
On `master` you should see:
|
||||
|
||||
- Git tag: `4.17.0-A.3` (plain version string from `RELEASE_VERSION`)
|
||||
- Two new **Verified** commits from the engineering-contrib bot
|
||||
- Root POM version: `4.17.0-A.4-SNAPSHOT`
|
||||
- Artifacts on Alfresco Nexus for `4.17.0-A.3`
|
||||
|
||||
## GA release and Maven Central
|
||||
|
||||
For a GA release (version matching `major.minor.patch` with no suffix):
|
||||
|
||||
1. Update [`.github/release-versions.yml`](../.github/release-versions.yml), for example:
|
||||
|
||||
```yaml
|
||||
- RELEASE_VERSION=4.17.0
|
||||
- DEVELOPMENT_VERSION=4.18.0-SNAPSHOT
|
||||
```
|
||||
|
||||
2. Push to **`master`** with both keywords in the **same** commit message:
|
||||
|
||||
```text
|
||||
[release][publish] Alfresco SDK 4.17.0
|
||||
```
|
||||
|
||||
To publish to Maven Central as part of the GA release, include `[publish]` in the **same** commit message as `[release]` so the workflow can publish the tagged `RELEASE_VERSION`.
|
||||
|
||||
A standalone `[publish]` commit (without `[release]`) will publish only if the POM version on that commit is already GA. After a release run, `master` is typically bumped to `DEVELOPMENT_VERSION` (`-SNAPSHOT`), so a later `[publish]` commit will be skipped by `check_version`.
|
||||
|
||||
The `check_version` job verifies the version matches `^\d+\.\d+\.\d+$` before Maven Central publish runs. Alpha, SNAPSHOT, RC, and other suffixed versions are skipped.
|
||||
|
||||
## Commit message keywords
|
||||
|
||||
| Keyword | Effect |
|
||||
|---------|--------|
|
||||
| `[release]` | Run the automated Nexus release |
|
||||
| `[publish]` | Attempt Maven Central publish (GA only) |
|
||||
| `[no release]` | Skip the release job even if `[release]` would otherwise match |
|
||||
| `[skip tests]` | Skip tests (do **not** use on release commits) |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Likely cause |
|
||||
|---------|----------------|
|
||||
| Release job skipped | No `[release]` in commit message, wrong branch, or tests failed/skipped |
|
||||
| App token step fails | GitHub App credentials not configured on the repository |
|
||||
| Verified commit rejected | Branch protection or App permissions |
|
||||
| Tag already exists | `RELEASE_VERSION` was released before |
|
||||
| Maven Central skipped | Non-GA version, or missing `[publish]` |
|
||||
|
||||
## Related files
|
||||
|
||||
- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — CI pipeline
|
||||
- [`.github/release-versions.yml`](../.github/release-versions.yml) — release version configuration
|
||||
- [Alfresco build-tools `maven-release-slim`](https://github.com/Alfresco/alfresco-build-tools)
|
||||
Reference in New Issue
Block a user