# Contributor: Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org>
# Contributor: Eli Schwartz <eschwartz@archlinux.org>
# Contributor: bill-auger <bill-auger@programmer.net>
# Maintainer: Parabola Hackers <dev@lists.parabola.nu>

pkgname=icu-compat
pkgver=78
pkgrel=1
pkgdesc="International Components for Unicode library"
pkgdesc+=" (long-term compatibility meta-package)"
arch=(any)
url=https://www.parabola.nu
license=(CC0-1.0)

depends=(icu-compat-{75,76} 'icu>=78') # Arch jumped straight from 76 to 78

# Parabola TL;DR: How to update ################################################
#
# When Arch pushes out a new `icu=N` package that Parabola pulls in,
# Parabola must:
#
#  1. Add a new `libre/icu-compat-$((N-1))` package.  This should
#     generally be identical to the PKGBUILD of the old Arch
#     `icu=$((N-1))` package[^1], plus the following modifications:
#
#      - Adjust pkgname (be careful if source=() or other uses
#        $pkgname; probably add a `_pkgname=icu` for them to make easy
#        use of).
#
#      - Append to pkgrel='', pkgdesc='', and arch=() as we usually do
#        when forking something from Arch.
#
#      - Add an install-time dependency on the main 'icu' package: Stick this inside of package():
#
#            depends+=("icu>=$(( ${pkgver%%.*} + 1 ))") # Parabola: Depend on a newer actual "icu" package
#
#      - At the end of package(), `rm` all files except for the
#        numbered `/usr/lib/libicu*.so.{N}*` files and the
#        `/usr/share/license/${pkgname}` files.
#
#      - In rare instances, you may need to also grab a patch from
#        ALARM[^2] to get it to build on armv7h or something like
#        that.
#
#  2. Update the version numbers in `libre/icu-compat`'s pkgver='' and
#     depends=() to
#
#          pkgver=N
#          depends=(icu-compat-$((N-1)) 'icu>=$((N))')
#
#     You may have a few more older `icu-compat-$((N-M))` pakcages
#     listed too, use your best taste.
#
# [^1]: Git here: https://gitlab.archlinux.org/archlinux/packaging/packages/icu
# [^2]: Git here: https://github.com/archlinuxarm/PKGBUILDs/tree/master/core/icu
#
# Parabola rationale and discussion ############################################
#
# Many Parabola packages depends on 'icu', and its "soname" version
# changes frequently.  If we don't rebuild all of the Parabola
# icu-dependent replacement packages as soon as the new Arch Linux,
# Arch Linux 32, and Arch Linux ARM 'icu' packages are synchronized
# into the Parabola repositories, we have a problem.  The Parabola
# repo server synchronizes with the upstream repos un-attended; so
# this is a wonderful surprise each time.  We must hustle to make the
# system sane again.  We could watch the upstream testing and staging
# repos of each upstream, and start re-building everything in a
# Parabola staging repo; but that could result in discarded work, if
# those exact versions are not the ones which are eventually released
# into the main repos, to make no mention confusion/skew from Arch 32
# and Arch ARM having their own delays from upstream Arch.
#
# Without other steps, this would result in users having broken
# systems if they upgrade before all of their icu-using packages have
# been rebuilt.  Both Parabola and upstream Arch have started to
# address this by having packages depend on the specific icu soname
# version that they're built against.  This avoids users getting
# broken systems when they upgrade... by having pacman prevent them
# from upgrading until things are in-sync.
#
#  > That is: packages that link against icu should not just say
#  > `depends=(icu)`, but `depends=(icu libicui18n.so)`; or whichever
#  > .so name
#  >
#  >     readelf -d /path/to/compiled/ELF/file | grep libicu
#  >
#  > says it's linked against.
#
# Ideally, Parabola would have automated builds that rebuild things
# when this happens, and tooling that doesn't let new 'icu' packages
# into the repos until everything is shored-up.  We don't have tooling
# for that yet, but hopefully will in the future.
#
# In the mean-time, Parabola carries 'icu-compat-{N}' packages for
# recent `N` soname versions that are behind the main 'icu' package,
# containing just the `/usr/lib/libucu*.so.{N}*` files (and a license
# file).  This is similar to the `icu{N}` packages in the AUR and Arch
# 32, or the `electron{N}` packages in Arch.
#
# There's one more piece: When newly installing a package that depends
# on an old icu version, pacman will just figure it out and install
# the 'icu-compat-N' package, but when just upgrading the 'icu'
# package it won't figure out that it needs to install
# 'icu-compat-$(N-1)' to make the upgrade possible.  We solve this by
# having a 'icu-compat' meta-package that is empty but
# `depends=("icu>=$N" "icu-compat-$((N-1))")` (and perhaps a few more
# older N); this way if the user has `icu-compat` installed, pacman
# will just do the right thing, at the expense of:
#
#  - the user's install being ~30MiB larger.
#  - there will occasionally be left-over older `icu-comapt-M`
#    packages left-over that the user will have to notice in `pacman
#    -Qdt` and then manually uninstall.  But the user should be doing
#    that anyway.
#
# We don't say conflicts=() on very old icu-compat-N packages; this
# would be handy to have pacman automatically uninstall them (instead
# of leaving them for `pacman -Qdt`), but that would create
# disproportionate pain for users who have built their own packages
# that use icu, or have had to hold back a package for whatever
# reason.  And agian, checking `pacman -Qdt` is something they should
# be doing anyway.
#
# All this means that when Arch pushes out a new 'icu={N}' that Parabola
# pulls in, the only thing that Parabola devs must hustle to do is:
#
#  - Add `libre/icu-compat-{N-1}`
#  - Bump the versions in `libre/icu-compat`.
#
# See also: The commit message of
# abslibre.git#commit=7c37754b1c8a1a71f94932c484c4fd2299caa768
# (icu-parabola: convert to install in /usr/lib and not conflict with
# icu, Eli Schwartz, 2020-05-04), which is a patch contributed by a
# (then) upstream Arch developer.
