Apt repository versioning and layout

[Atry]

Currently we have hhvm and hhvm-nightly named differently. However, they are not actually independent. We cannot install both:

If you installed hhvm from the APT repository, then the attempt to install hhvm-nightly would fail

sudo dpkg --install hhvm-nightly_2022.05.22-1~focal_amd64.deb 

dpkg: regarding hhvm-nightly_2022.05.22-1~focal_amd64.deb containing hhvm-nightly:
 hhvm-nightly conflicts with hhvm
  hhvm (version 4.159.0-1~focal) is present and installed.

dpkg: error processing archive hhvm-nightly_2022.05.22-1~focal_amd64.deb (--install):
 conflicting packages - not installing hhvm-nightly
Errors were encountered while processing:
 hhvm-nightly_2022.05.22-1~focal_amd64.deb

[Atry]

Since we are now creating the Apt repository for universal deb packages, now we have a chance to revisit the convention for package names, versions and suites.

Goals & Non-goals

Goals

• The users should be able to update deb packages in one command.
• The users should be able to specify one of the following strategies to upgrade deb packages
  • Only upgrade HHVM for security update and non-breaking changes
  • Upgrade HHVM to the latest nightly version
  • Upgrade HHVM to the latest release version
  • Upgrade HHVM to the latest LTS version
• The users should be able to change the upgrading strategy. For example, a release version user should be able to upgrade to a nightly version when the user needs a new feature, and then switch back to a release version once we publish the next release.
• Existing distribution-specific deb package users should be able to upgrade to universal packages.
• A deb package should be able to be built from any commit, not only those tagged commits.
• Version comparison between any deb packages should make sense.

Non-goals

• Installing multiple HHVM versions on the same machine from Apt repository.
  • Deb packages are system packages. There should be one and only one package installed. Use Nix or Docker for isolated project-specific package versions.

Versioning And Layout

In brief, the package name should be always hhvm, while the version of a hhvm package might be either a dev version or a release version, and each version could belongs to one or more suites.

Deb Package Name

All deb packages should be named hhvm, no matter if it is built nightly or released biweekly. The unified package name allows upgrading between different suites.

Deb Package Version

The deb package versions are different from the versions printed by hhvm --version. Instead, they are adjusted to meet the algorithm described in https://manpages.debian.org/wheezy/dpkg-dev/deb-version.5.en.html

The version is always determined from version.h in the code base, not from parameters passed to the build.

If the HHVM_VERSION_SUFFIX is defined as "-dev" in the code base, the deb package version should be major.minor.patch~dev%Y%m%d%H%M%S, where %Y%m%d%H%M%S is the commit time. For example: 4.199.0~dev20221231235959.

If the HHVM_VERSION_SUFFIX is defined as "" in the code base, the deb package version should be major.minor.patch. For example: 4.199.0.

Note that we choose tilde instead of hyphen, so that dpkg would consider a dev suffixed version as a smaller version than unsuffixed version, according to its sorting algorithm. We also choose commit time instead of nightly date to support version comparison between arbitrary commits.

Apt Repository Suite

The universal deb package built from HHVM-x.y.z tag will have an unsuffixed version x.y.z. The deb package will be uploaded to the following suites:

• release
• release-x.y

If x.y is a LTS version, the deb package will be also uploaded to the following suite:

• lts-release

The universal deb package built from night-YYYY.MM.DD tag will have a suffixed version. The deb package will be uploaded to the following suite:

• nightly

The universal deb package built from other commits will not be uploaded to the Apt repository.

[Atry]

According to a private conversation with @fredemmott, the reason why the package names are different is to support installing both hhvm and hhvm-nightly on the same machine.

Unfortunately the ability to install both hhvm and hhvm-nightly from deb packages is not super helpful because:

1. We never actually supported that ability due to the file path conflict.
2. Now we have package formats other than deb, including Docker or Nix, to support that ability.

[Atry]

Note that the versioning in RPM 4.10.0 or higher also supports tilde: https://rpm.org/ticket/56