6.0.0-git
2024-03-19
Last Modified 2019-11-28 by Ralf Lang

Downstream Horde Development

Preface

There are multiple purposes which require you to create software releases independent from the Horde upstream infrastructure. You may want to develop a feature for an existing app and rollout to some canary customer. You may want to develop completely new horde apps or libraries from scratch for some internal purpose or involving compromises which need to be fixed before a public rollout. You may want to maintain a set of permanent downstream modifications in a git tree while following upstream developments.

Each of these may require you to handle horde metadata and create releases by yourself.

Note that large and long-lived downstream forks may be more difficult to finally include in upstream development than piecemeal pull requests. However, sometimes it makes sense to cut on upstream interaction delays and get something done. This is especially the case if a feature involves changes to several core libraries.

List of relevant metadata files and items

Application.php version info

A variable in the main application file (only apps, not for components app itself)

changelog.yml

A changelog in YAML format (all packages)

.horde.yml

See Developer Doc on .horde.yml format

CHANGES file

A plaintext CHANGES file (most packages)

PEAR package.xml

A pear package definition (all released H4/H5, all H4/H5 alpha, not for git-tools)

Older releases of the components tool will use the package.xml file even though information could be pulled from .horde.yml file.
Newer releases of the components tool will not strictly require a package.xml - however, omitting this file will not allow releasing for PEAR, pear dependeny graph etc.

composer.json

A composer manifesto (all recent packages)

Release Management Workflow

In Horde's release management workflow, releases are done from maintenance branches.
Each release has a git tag for its version. The maintenance branch is always ahead of the latest release tag. If the latest public release was 5.2.21, the maint. branch for the Framework 5.2 series would have metadata for version 5.2.22.

Releases have a stability (git/development, alpha, beta, rc, stable) and an API version.

The API version typically only changes with feature releases (5.1.x to 5.2.0) or major releases (5.x.y to 6.0.0).
Backward compatibility breaks always mean a new major version.

Downstream apps do not need to coordinate their releases with Horde but they should target a framework feature version.
The current framework feature version as of writing is 5.2 - hence any officially released horde app or library has a maint. branch called FRAMEWORK_5_2.
This is however not the application's or library's version. Librarys and apps must bump major version if they are released for a new major framework release (even though technically they might not change at all). This is not required for framework feature releases unless the library/app *has* new features.

A library or app which had its version 1.x in Horde 4 would go into version 2.0 with the release of horde 5. Your downstream app should use semantic versioning, bumping feature version (middle number) when new features or APIs are added, bumping bugfix (right, third) number when bugs are fixed, bumping major release (left, first) number when backwards compatibility is broken.

A developer would create feature branches or forks to build new features, then merge-request or manually rebase them into master.
Individual commits from master branch (like bug fixes) can be picked into the maint. branch.
The yaml changelog file accumulates change notes over time (see Maintaining the Changelog).

Once a release is due, the current version in the maint branch gets release and a new changelog for a next version is created. By default, the next version for a stable release is the next bugfix number while the next version for an unstable (alpha, beta, rc) release is an increased index (alpha1 released with a tag, alpha2 is in the branch).

The developer can tell the release tool that he wants to change maturity (alpha, beta, rc, stable) or that the next version should be a feature release.
However, you can also redesignate the current version before release to become a feature release rather than a bugfix release. This is done using additional switches for the "update" command.

Maintaining the Changelog

Changing the currently developed version before release

Bugfix releases (a.b.x -> a.b.y)

Feature Releases (a.x.c -> a.y.0)

snapshot pear tarballs

Private Composer Infrastructure

See https://github.com/maintaina-com/horde-satis.maintaina.com for an example.