IronPort-PHdr: =?us-ascii?q?9a23=3AIkZ1Rh9IiUCvPv9uRHGN80YQeigqvan1NQcJ65?=
               =?us-ascii?q?0hzohDabmn44+7bByN//hphU6TG5jd6rdEhuvavqTqVHYPp5qM4zgZaJIZcR?=
               =?us-ascii?q?gDhI0NmhA4RtafABj5K+Xndyx8A95DW19513S8K05UHsnle1TI+Du56ngPGU?=
               =?us-ascii?q?a3LhJ7c8LyHIOalMGrz6a38pzXbR9PgW+/Zqh/NBXwsh/QuckKqY5lMKAwzB?=
               =?us-ascii?q?TSvnJSIaJdwiV1JgHbhA7ys+G3+pMr6CFMo7Qh+spHBL39ZLg9RKdEAS4ONm?=
               =?us-ascii?q?k04Ij0r0CGQ1fUoHQbVWoSn1xDBA2ctkPAU5z8szX3uq9G4AfBYZeka7cyVH?=
               =?us-ascii?q?zi9apvQQ6yzjoBNns5/WDbh8h6gbhU5h6s9VR5xMbPbYeZOeAbHOuVdM4GRW?=
               =?us-ascii?q?dHQsdaVjBQSoK6YYwVCuMdPOFe54DjrloKpBG6CEGiHuTqgjNPg3b32+U93Y?=
               =?us-ascii?q?FDWUnE2xctB9JIr27Vo9XpHKIVS+a0yqbT0TzZNbVd3nHg68mAcxwsp+2NQa?=
               =?us-ascii?q?MladDYmixNX0vOilSdr5CgPivAjLxc9TjGqbA6DKTz0D1vsQx6rzmxy915kI?=
               =?us-ascii?q?TNj5NPjE3C9GB5zYc5KNmyRVR0J9KpQ/4y/2mXMZV7RsQ6TiRmoiE/n/cEvo?=
               =?us-ascii?q?W2ZChM144myB7DQ/mAaY6J5B34SO+Le3FzgzR4e/js4nT6uVjl0eD6WsSuhR?=
               =?us-ascii?q?xIqTFIitmKqWoM2BzPws2AUP18+Ei6xT+VjUbY7adZIgpn8MiTY45kybk2mJ?=
               =?us-ascii?q?0JtE3FFSKjg0T6gpidcUA88/Sp4eDqO++0nJKXOo5qhw27CZwAwZDgU8I/NA?=
               =?us-ascii?q?VGH3KW/e2tjvv++0y8QLhLgvAymKTDv9bWKJZToKnxGAJT3os5jnT3Rz67zN?=
               =?us-ascii?q?QVm2UGJ1NZaVqGiYbuIVTHPPH/C7+2nV2tlD5hw/2OMKfmB93BKX3KkbGper?=
               =?us-ascii?q?gYiQYUyg0owMhfoY1OC74BPNr2XVX3tdrXFQMwKVbyyOGhFdY8noISVGSTA7?=
               =?us-ascii?q?OIZabbsFuG/OUqcIzuLMcevDfwLeRg5ua71ydo3w9AO/PzhN1LMyPwBPltLk?=
               =?us-ascii?q?SHbGC5mNoFGHZQ+Bc4TanqhVyOXDpZamy9Ga4xtVRZQMqrC5nOQoe1jfmPxi?=
               =?us-ascii?q?C+S9dUYXtLElDKDm3peIWYc/ILciSTJMB6jjUeD/6qTMk81lv90W2yg6oiNe?=
               =?us-ascii?q?fS9iAC4Njh08N4/+2Vigsz+jxoJ8GayWeMSW5vgmoSHXk92+ZiogYurzXLmb?=
               =?us-ascii?q?g9iPteG9tJ4vpPWQpvLp/QwdtxDNXqUx7AdNOEEQz0eNitDDAvQ950+OcgOB?=
               =?us-ascii?q?oiSfOliB2LnzCnB7YEzfqWAp1x8q/d03X1LctnxDDK2ftpiV5uWcZJOWC848?=
               =?us-ascii?q?w3vwHOG47ElVmYnKe2ZOwd2iDK7mKK0WuJuglRTgdxVazPWX1XaFHRqJz14U?=
               =?us-ascii?q?bLTrnmDrpCUEMJ0cmZNq5DccHkl31DTfbnfcvEOie/xzz2ChGPybeBKoHtfi?=
               =?us-ascii?q?RV3SnQDlQFjxFG/XuCMltbZG/pqGbfATpyUFP3Nhm0oK8u9TXhFBZyk1rZJ1?=
               =?us-ascii?q?ds3Le05BMP0OaRT/oChPQZviZkqzh1EFu51d/MBJyMqlkEHu0UbNUj7VNAzW?=
               =?us-ascii?q?+cuRZ6O8nqLad5i0YeNRttvkzuyz1yDZ9GkM4lt28j1lA0IqXezVALJFb6ld?=
               =?us-ascii?q?jgf6baLGX/5kXlc6nNxlTXy8qb4I8K4fU87kr55USnShFk/HJg3N1YlXCb49?=
               =?us-ascii?q?+ZaWhaGYK0WUEx+R9gorjcaSRo/ILY20pnNqysuyPD0dYkXbZ3+lObZ95adZ?=
               =?us-ascii?q?i8OkryHskdXZX8LeUrnx22dEtBMrwJsqEzOMyier2N36v5ZL88zgLjtnxO5c?=
               =?us-ascii?q?VG6mzJ7zB1ELaa2pEfxfCe0RCbXi2mylym9N30y9gdNGMiW1GnwC2hP7Z/I6?=
               =?us-ascii?q?h7fIIFE2CreZXlw9JkgZ/rVGVE/UT5QVgBntKqK0Kf?=
References: <20200723020053.jq6lnwl7k23htouz@vento15post8>
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:68.0) Gecko/20100101
            Thunderbird/68.10.0
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Language: en-GB
Content-Transfer-Encoding: 8bit
Message-ID:  <8fffc89a-7a03-051d-9dfd-264a94af6f32@morningstar2.co.uk>
Date:         Thu, 23 Jul 2020 10:19:24 +0100
Reply-To:     Mailing list for the LaTeX3 project
              <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
Sender:       Mailing list for the LaTeX3 project <LATEX-L@LISTSERV.UNI-HEIDELBERG.DE>
From:         Joseph Wright <joseph.wright@MORNINGSTAR2.CO.UK>
Subject: Re: Guidelines on the new hook management
To:           LATEX-L@LISTSERV.UNI-HEIDELBERG.DE
In-Reply-To:  <20200723020053.jq6lnwl7k23htouz@vento15post8>
Precedence: list
Envelope-To: <rainer.schoepf@gmx.net>
Status: R

On 23/07/2020 03:00, Henri Menke wrote:
> Dear list,
> 
> Inspired by issue #900 on the PGF/TikZ repo [1], I'd like to kick off
> the discussion on how to correctly integrate the new hook management
> system into existing LaTeX package codebases.
> 
> In a naïve adaptation, two code branches would be maintained, with and
> without the new hook management.  This is quite tedious for maintainers,
> especially when trying to integrate this properly into existing CI.
> 
> For me as PGF/TikZ maintainer it is also of paramount importance to
> avoid anything similar to the oberdiek-split and iftex-merge
> clusterfucks.  Back then I had to fix the CI every other day without any
> guidance whatsoever from upstream, which was a massive sink of my time.
> 
> Obviously there has to be some transition at some point.  Hence I'm
> asking how to properly integrate and coordinate the migration this time.
> 
> Kind regards,
> Henri
> 
> [1] https://github.com/pgf-tikz/pgf/issues/900

Hello Henri,

First, an paragraph aside about the oberdiek split and iftex merge 
changes. Both of those were mainly issues in TeX Live packaging, which 
is separate from the case here, which is about the macro layer. As such, 
the impact of the earlier changes was mainly felt by package authors 
using CI set-ups. There are a couple of ways of setting up a CI: you can 
have a frozen set of packages (libraries) available, or you can update 
to see 'what your users get'. Like me, you've gone for the latter: there 
are advantages to both, but updating does leave you at the mercy of 
third-party changes. One could I guess set up parallel tests to 'focus 
in' on where the issues come from, but that is likely overkill here. 
(The number of packages to track is sufficiently small to know where 
things come from.)

On the matter in hand, all that is needed is to test for the new 
mechanism being available, and to use it when it is. That is potentially 
as simple as

     \@ifundefined{AddToHook}
       {
          % Old code
       }
       {\AddToHook{...}{...}}

if you are using LaTeX, or for code that must work format-neutral

     \long\def\@firstoftwo#1#2{#1}
     \long\def\@secondoftwo#1#2{#2}
     \ifx\AddToHook\undefined
       \expandafter\@firstoftwo
     \else
       \expandafter\@secondoftwo
     \fi
       {
         % Old code
       }
       {\AddToHook{...}{...}}

(I'll cover the possible targets for \AddToHook in a separate email, as 
it goes with the tex4ht mail in this thread). I've used the \@firstoftwo 
approach here as I'm allowing for the 'old code' containing unbalanced 
conditionals.

One might of course define the hook 'payload' in a macro and do 
something like

     \protected\def\my@hook@payload{...}
     \@ifundefined{AddToHook}
       {
         \g@addto@macro\document{\my@hook@payload}%
       }
       {\AddToHook{begindocument/end}{\my@hook@payload}}

I've already adjusted beamer in light of the above need, see 
https://github.com/josephwright/beamer/commit/877c44cc5fd32ef0736fbe66f88a53995c8e1850: 
beamer used to mess with \document, not with \shipout.

Joseph