HHostingByteSoftware
Ctrl K
ComunidadGuías…

RELEASE.md

Rama develop · réplica de lectura del repositorio original.

Archivo original ↗Preguntar a KiBot
# Release procedure

This document is the checkpoint for a Convertigo release. Open a tracking issue
from the **Release** issue template (`.github/ISSUE_TEMPLATE/release.md`),
attach it to the milestone of the version and tick the items as they are done.

Branches: `hotfix` carries the next patch or minor release (`X.Y.Z`), `develop`
the next major one. At release time `master` is fast-forwarded to `hotfix` and
the release is tagged there. Scripts for the manual steps live in `release/`.

Two steps block the ones after them:

1. the `convertigo-X.Y.Z.war` asset must be attached to the GitHub release
   before the Docker official image pull request is opened, otherwise the
   Docker Library bot fails to build the image (the WAR download returns 404);
2. the official image `convertigo:X.Y.Z` must be available on Docker Hub
   before the Helm chart and the Docker docs are updated, since both reference it.

## 1. Before the release

### Tickets
- Every issue of the milestone is closed and labelled `tested`, `wontfix` or
  `invalid`; this search must return nothing:
  `is:closed is:issue milestone:X.Y.Z -label:tested -label:wontfix -label:invalid`.
- Each `tested` issue carries a comment `Tested OK with <build id>` naming the
  CI build it was verified on (`engine.GetStatus` reports the build id, for
  example `27160-hotfix-8.4.4-beta`). Issues needing a manual Studio check
  carry test notes in English.
- Issues deliberately excluded from the release (for example a reverted fix)
  are labelled `wontfix` and do not appear in the changelog.

### Changelog
- `CHANGELOG.md` has a `## X.Y.Z` section, generated with
  `./gradlew makeChangelog` then rewritten by hand: `[Category]` prefix,
  `Fixed,` for bug fixes, wording readable by a user, ascending ticket number
  inside each category, no leftover `*` marker.

### Documentation (`convertigo-doc`)
- The generated part (`reference-manual/convertigo-objects/**`, `images/beans/**`)
  is pushed to the `hotfix` branch of `convertigo-doc` by the CI build of
  `hotfix` (only `master`, `hotfix` and `develop` generate documentation).
- The hand-written part covers the user-facing changes of the milestone
  (Docker, engine properties, Administration Console, Studio, guides).
- `.circleci/doc-flow.sh audit` (run by hand in a `convertigo-doc` checkout)
  reports `master` as an ancestor of `hotfix`, with no manual difference
  between them other than the release content.

### Common resources (`convertigo-common-resources`)
- The maintained `X.Y.x` branch exists and its `gradle/build.gradle` uses the
  latest released `X.Y` Gradle plugin. A shared maintenance branch must not use
  a `-SNAPSHOT` plugin because already released Studios also download it.
- Review the Gradle wrapper, required Java version, CI action/plugin versions
  and every file imported by the root JSON manifests according to that
  repository's `MAINTENANCE.md`.
- Check that the raw GitHub URLs used by Studio return the root JSON manifests
  and all their imports from `X.Y.x`. Keep exact `X.Y.Z` compatibility branches
  only for Studio versions released before the maintenance-branch convention.

### Docker
- `docker/README.md` documents every environment variable and mount of the
  image. It is the source of both the Docker Hub description (published by the
  CI build of the `latest` image) and the Docker official docs (see below).
- `./gradlew checkDockerDocsOfficial` passes against a sibling `../docker-docs`
  checkout.

### Build
- The last CI pipeline of `hotfix` is green (engine, Studio, Docker, qualification jobs).
- `ext.convertigoVersion` in `build.gradle` equals the version to release and
  `ext.convertigoTag` is still `'beta'` (the release script clears it).

## 2. Release

- Run `release/tag-release.sh X.Y.Z` from a clean `hotfix` checkout. It switches
  `build.gradle` to release mode (`convertigoTag = ''`), regenerates the
  versioned files (`generateEclipseConfigurationWithManifest`,
  `generateDockerfile`), commits `Official Convertigo X.Y.Z release!`,
  fast-forwards `master`, pushes `master` and the `X.Y.Z` tag to `origin` and
  `upstream`. The tag pipeline builds the artifacts, publishes the
  `convertigo/convertigo` image and creates a GitHub release draft
  (pre-release unless the tag is a plain `X.Y.Z`); the `master` pipeline
  publishes the `latest` image and its Docker Hub description.
- Once the tag pipeline has published `com.convertigo:gradle-plugin:X.Y.Z`,
  update the `convertigo-common-resources` `X.Y.x` branch to that stable plugin
  version and verify its raw GitHub resources again.
- Start the next beta: `release/start-next.sh X.Y.Z+1` on `hotfix` sets the
  next version with `convertigoTag = 'beta'`, regenerates the versioned files
  and commits `Starting Convertigo X.Y.Z+1 beta!`; push `hotfix`.
- Edit the release draft: reuse the previous release text, update the version
  in the file names, the counts of new features / improvements / bug fixes from
  the changelog section and the changelog link
  (`https://github.com/convertigo/convertigo/blob/X.Y.Z/CHANGELOG.md`, a
  relative link does not resolve from the releases page). Check that
  `convertigo-X.Y.Z.war` is attached, then publish.
- Publish the documentation: in a `convertigo-doc` checkout run
  `.circleci/doc-flow.sh release-minor` (or `release-major`). It fast-forwards
  `master` to `hotfix` and records the release point in `develop`; the `master`
  build publishes `latest` and `X.Y.x` and invalidates the CloudFront cache.

## 3. Docker official image

Requires the WAR attached to the published GitHub release.

- Run `release/official-image-pr.sh X.Y.Z` from this repository with a
  sibling `../docker-official-images` checkout (fork of
  `docker-library/official-images`, `upstream` remote set). The script checks
  the WAR is downloadable, syncs the fork with upstream, updates
  `library/convertigo` (`GitCommit` of the tag, `Tags: X.Y.Z, X.Y, latest`) on a
  `convertigo-X.Y.Z` branch, pushes it and opens the pull request.
- Wait for the Docker Library review and the build of `convertigo:X.Y.Z` on
  Docker Hub (https://hub.docker.com/_/convertigo, tags tab).

## 4. After the official image is available

- Docker docs: run `release/docker-docs-pr.sh X.Y.Z` with a sibling
  `../docker-docs` checkout (fork of `docker-library/docs`, `upstream` remote
  set). The script syncs the fork, runs `./gradlew updateDockerDocsOfficial`,
  commits `convertigo/content.md` on a `convertigo-<date>` branch, pushes it and
  opens the pull request. The docs do not depend on the image: `--force` opens
  the pull request while the official image one is still under review.
- Helm chart (`convertigo-helm`): its branches follow this repository. Chart
  changes for `X.Y.Z` are made on `hotfix`, those for the next major on
  `develop`, and `master` is the published chart (the GitHub Action publishes on
  every push to `master` only). On `hotfix`, set `version` and `appVersion` to
  `X.Y.Z` in `stable/convertigo/Chart.yaml` and update the README if needed;
  merge `hotfix` into `master` and push `master`. The action publishes the chart
  to ECR Public, the S3 repository and the AWS Marketplace ECR; check
  https://artifacthub.io/packages/helm/convertigo/convertigo afterwards. Then
  merge `master` into `develop`.
- Links to the Helm repository written during the release cycle point to its
  `hotfix` branch (for example `tree/hotfix/examples/...` in `convertigo-doc`
  and in the chart README): switch them to `master` once the chart is
  published.
- Check the Docker Hub description of `convertigo/convertigo` matches `docker/README.md`.
- Check https://doc.convertigo.com lists the new version in the version selector.
- Merge `hotfix` into `develop` for a minor release (once the work in progress
  on `develop` allows it), close the milestone and the tracking issue.

## Scheduled rebuild of the released Docker images

The Docker Official Image is rebuilt by Docker whenever its base image changes;
`convertigo/convertigo` gets the same treatment from the `docker_rebuild`
workflow of `.circleci/config.yml`, run from `master` by a CircleCI scheduled
pipeline.

- Trigger (CircleCI > Project Settings > Triggers > scheduled): branch
  `master`, daily, pipeline parameter `docker_rebuild = true`. Add
  `docker_rebuild_force = true` on a second, monthly trigger to refresh the OS
  packages even when nothing else changed.
- The job reads the released version from `build.gradle` on `master`, then
  compares the digest of the Dockerfile base image and the last commit touching
  `docker/` with the `org.opencontainers.image.base.digest` and
  `org.opencontainers.image.revision` labels of `convertigo/convertigo:X.Y.Z`.
  When both match it stops in a few seconds; otherwise it rebuilds
  `docker/default` (amd64 + arm64) and `docker/aks` from `master` and pushes
  `X.Y.Z`, `latest`, `X.Y.Z-aks` and `latest-aks`. The WAR is the signed asset of
  the GitHub release, so only the system, JDK and entrypoint layers change.
- A Docker-only fix is therefore delivered by committing it on `master` (then
  merging `master` into `hotfix`): the next scheduled run republishes the images.
- Only the current release is covered; older maintenance versions are not rebuilt.