This section describes the branching, merging, and release strategy used for Cypht 2.x and later. The goal is to balance active development with stable and predictable releases.

1.2 Development Strategy

All new features are developed in the master branch.
All bug fixes are also implemented in the branch first.
Any fix that applies to the current stable version must be backported to the 2.x branch.
- Backporting should ideally be done at merge time or shortly after, to reduce divergence.

1.3 Maintenance Releases (`2.x.y`)

The 2.x branch is reserved for stability and fixes only.
Maintenance releases such as 2.2.1, 2.2.2, etc. are cut directly from the 2.x branch.
These releases must not include new features.

1.4 Minor Releases (`2.x.0`)

When a minor release is planned (for example 2.3.0):
- The entire master branch is merged into 2.x.
- The release is built from the 2.x branch.
- The corresponding Git tag (2.3.0) is created from 2.x.
After the release:
- Fixes applied to 2.x are released as 2.3.1, 2.3.2, etc.
- The master branch continues with ongoing development for future versions.

1.5 Major Releases (`3.x` and Beyond)

When development reaches a point that requires a major version bump (for example 3.0.0):
- The 3.x branch is created directly from master, including all features and fixes.
- Merging master into 2.x stops.
- The 2.x branch enters maintenance mode and continues to receive backported fixes if required.

1.6 Docker Images (Automated Builds)

Cypht uses automated GitHub workflows to build and publish Docker images, so users always have up-to-date container images available.

Daily Image

The Daily Image workflow (.github/workflows/Daily-Image.yml) runs on a schedule (cron) to build a fresh Docker image every day.
It checks out the latest master code and builds a Docker image even if there is no new Git tag or release.
This daily image provides a rolling build that includes the latest merged features and fixes.
The image is pushed to the configured container registry (Docker Hub)[https://hub.docker.com/r/cypht/cypht/] with a tag daily.

Release Image

The Release Image workflow (.github/workflows/Release-Image.yml) is triggered when a new release tag is created.
It builds a Docker image from the exact source code associated with the release tag.
The image is tagged with the release version (e.g., v2.3.0) and pushed to the container registry.

1.7 Branching Overview: ASCII Diagram

master ──●──●──●──●──●──●──●──────────────▶
           \        \              \
            \        \              └─ ongoing development
             \        \
2.x           ●──●──●──●──●──●──●────●──▶
               |   |        |    |
               |   |        |    └─ 2.3.2
               |   |        └─ 2.3.1
               |   └─ 2.3.0 (merge master → 2.x)
               └─ 2.2.x maintenance releases

3.x           └────────────────────●──●──▶
                                     |
                                     └─ 3.0.0 (branch created from master)

REF Strategy

1.8 Pre-release Check

Before creating any release (minor or maintenance), make sure to update Version Number. Set the correct upcoming version in lib/version.php. This file controls the upgrade notification system and must reflect the version being released.

Important: The version in lib/version.php must be updated before creating the Git tag, otherwise users will receive incorrect upgrade notifications pointing to the wrong version.

2. Cypht 1.4.x

Steps for 1.4.x:

Release a version of https://github.com/cypht-org/php-sieve-manager and use that in Cypht (done: https://github.com/cypht-org/php-sieve-manager/releases/tag/v1.0.0)
Run all tests and make sure all is well (done)
Create branch 1.4.x and make necessary commits in this new branch (done)
"stability": "dev", in composer.json even though it doesn't exist in https://getcomposer.org/doc/04-schema.md - changed minimum-stability to stable.
Release 1.4.0: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository (done: https://github.com/cypht-org/cypht/releases/tag/v1.4.0)
Update documentation to reflect that we now have 1.4.x and master. Ex.: https://github.com/cypht-org/cypht/blob/master/INSTALL (Note: this is more developer documentation than end-user one. We should have a getting started page for developers where we explain where to commit or base their MRs on.)

Important URLs for Cypht 1.4.0:

Should we continue to use?

3. Manually releasing a docker image

Until Docker tagging is automated, this is now you manually push a new version. In this example I am releasing v2.1.0

Make sure your account has permissions in the dockerhub cypht org.

Pull down the new tag in git

git pull git checkout v2.1.0

Build and push

make docker-push tag=2.1.0

Check that the tag was pushed: https://hub.docker.com/r/cypht/cypht/tags

Update the example production compose file:

git checkout master

Update docker/docker-compose.yml to say:

image: cypht/cypht:2.1.0

Create a PR for the change.

Smoke test it:

cd docker docker compose up

visit http://localhost

Updating readme in dockerhub

This is for the readme shown on the overview page here: https://hub.docker.com/r/cypht/cypht

Note: The readme is not tag specific. There is one readme for the whole dockerhub cypht/cypht repo. This is different then git where you can have a different readme for each branch. Plan accordingly.

Make the changes needed to docker/DOCKERHUB-README.md

Commit the changes in a PR.

Release the change:

make dockerhub-push-readme

Checking that YunoHost works

After tagging a new release on GitHub, the yunohost-bot (https://github.com/yunohost-bot) automatically creates a pull request to update the Cypht package in the YunoHost Apps Cypht repository.

Wait for the PR creation: The bot typically takes 1 or 2 days after the release to create the pull request. You can monitor for new PRs on the cypht_ynh pull requests page.

Wait for merging: Once the PR is created, it may be reviewed and merged by the YunoHost app maintainer. This can take additional time depending on their availability.

Once the pull request is merged and the package is updated in the YunoHost catalog:

Navigate to your YunoHost admin panel → Updates : to update the applications
Verify that the new Cypht version appears in the application list.
Upgrade Cypht on a test instance first, if available.

Proceed with the tests to make sure everything is working well.

Contribution Summary

if you need to summarize the key contributions and changes made between the releases in the Cypht repository, please visit: https://github.com/cypht-org/cypht/wiki/Contribution-Summary:-Changes-Between-versions

###

Release Process and Branching Strategy

Communication

1. Cypht 2.x and Later

1.1 Overview