Fwd: Release policies

Gershom B gershomb at gmail.com
Wed Dec 13 23:19:37 UTC 2017 

Mathieu:

I think the points about better tooling for documenting the correct
claims in the release process are well taken. Updating the release
notes manually leaves way too much room for error.

However, I think you are incorrect that GHC 8.2.1 and 8.2.2 did not
have cabal-install 1.24 support. They did. it works with them. I used
it! The fact that the cabal files for builtin libraries use Cabal-2
syntax does not cause a problem.

I think elsewhere Mikhail has corrected your timeline a bit. The
general point is that Cabal-the-library and ghc releases do tend to be
in tandem. But it is also the case that this happens because they are
often developed in a coupled fashion. This in not really different
than other builtin libs to GHC. They are necessarily coupled to
changes in the compiler, and so end up being released together. Our
process for making sure they are actually uploaded is absolutely
error-prone as is the process for documenting what occurs in release
notes. But I don't think we can simply by fiat decouple this stuff --
rather, this needs to occur on a technical level first, before other
policies can really even be considered.

Onto the concrete ideas:

> * GHC should never under any circumstance ship with an unreleased version
> of any independently maintained dependency. Cabal is one such dependency.
> This should hold true for anything else. We could just add that policy to
> the Release Policy.

Yes, this is a good policy. Sometimes in the drive for a release, GHC
will run ahead of a dependencies' upload by a bit. (Iirc this happened
at one point in the past for bytestring, but this was some years ago).
It is always better to hold things by a few days to get the dependency
released first.

> * Stronger still, GHC should not switch to a new major release of a
> dependency at any time during feature freeze ahead of a release. E.g. if
> Cabal-3.0.0 ships before feature freeze for GHC-9.6, then maybe it's fair
> game to include in GHC. But not if Cabal-3.0.0 hasn't shipped yet.

I don't think this works, in terms of coupled dependencies. If/when
Cabal-3 is developed it will almost certainly be in tandem with GHC
support.

> * GHC does have control over reinstallable packages (like text and
> bytestring): GHC need not ship with the latest versions of these, if indeed
> they introduce breaking changes that would contravene the 3-release policy.

Right, but this won't occur, because those libs are already under the
control of the libraries committee and abide by the policy.

> * Because there are far fewer consumers of metadata than consumers of say
> base, I think shorter lead time is reasonable. At the other extreme, it
> could even be just the few months during feature freeze.

Right. There's not a sufficient quantity of metadata-consuming
downstream tooling to motivate a long lead. And furthermore, the
examples I can think of -- tracking dependencies for notifications or
graphs -- have no need of pulling this data out of ghc-builtin
libraries anyway, as they're for exploring the _userland_ portion of
the package world regardless. (The other key example -- stack -- can
also choose to ignore the metadata of builtin libs without harm).

The general motivation of making a "feature freeze" more of a "freeze
all the moving parts, really" I do agree with. Having a real freeze is
part of a better release process, and it should allow all the
downstream consumers of everything more time to really catch up. This
is just one instance of that need.

> Finally, a question for discussion:
>
> * Hackage allows revising the metadata of an uploaded package even without
> changing the version number. This happens routinely on Hackage today by the
> Hackage trustees. Should this be permitted for packages whose release is
> completely tied to that of GHC itself (like integer-gmp)?

It is rare that this is needed, but the ability just served us well --
editing integer-gmp to remove the new syntax was very useful, as it
let us fix up old stack nightlies. Like all revisions, these should be
made with some care and thought, but since we've just seen why it was
helpful, I'd hate to now say we can't do it again if some other
unforseen circumstance crops up.

Regards,
Gershom

> Hi Simon,
>
> feedback from downstream consumers of Cabal metadata (e.g. build tool
> authors) will be particularly useful for the discussion here. Here are my
> thoughts as a bystander.
>
> It's worth trying to identify what problems came up during the integer-gmp
> incident in Trac #14558:
>
> * GHC 8.2.1 shipped with integer-gmp-1.0.1.0 but the release notes said
> otherwise.
> * GHC 8.2.1 shipped with Cabal-2.0.0.2, but specifically claimed in the
> release notes that cabal-install-1.24 (and by implication any other build
> tool based on Cabal-the-library version 1.24) was supported: "GHC 8.2 only
> works with cabal-install version 1.24 or later. Please upgrade if you have
> an older version of cabal-install."
> * GHC 8.2.2 also claimed Cabal-1.24 support.
> * GHC 8.2.1 was released in July 2017 with Cabal-2.0.0.2, a brand new major
> release with breaking changes to the metadata format, without much lead
> time for downstream tooling authors (like Stack) to adapt.
> * But actually if we look at their respective release notes, GHC 8.2.1 was
> relased in July 2017, even though the Cabal website claims that
> Cabal-2.0.0.2 was released in August 2017 (see
> https://www.haskell.org/cabal/download.html). So it looks like GHC didn't
> just not give enough lead time about an upstream dependency it shipped
> with, it shipped with an unreleased version of Cabal!
> * Libraries that ship with GHC are usually also uploaded to Hackage, to
> make the documentation easily accessible, but integer-gmp-1.0.1.0 was not
> uploaded to Hackage until 4 months after the release.
> * The metadata for integer-gmp-1.0.1.0 as uploaded to Hackage differed from
> the metadata that was actually in the source tarball of GHC-8.2.1 and
> GHC-8.2.2.
> * The metadata for integer-gmp-1.0.1.0 as uploaded to Hackage included
> Cabal-2.0 specific syntactic sugar, making the metadata unreadable using
> any tooling that did not link against the Cabal-2.0.0.2 library (or any
> later version).
> * It so happened that one particular version of one particular downstream
> build tool, Stack, had a bug, compounding the bad effects of the previous
> point. But a new release has now been made, and in any case that's not a
> problem for GHC to solve. So let's keep that out of the discussion here.
>
> So I suggest we discuss ways to eliminate or reduce the likelihood of any
> of the above problems from occurring again. Here are some ideas:
>
> * GHC should never under any circumstance ship with an unreleased version
> of any independently maintained dependency. Cabal is one such dependency.
> This should hold true for anything else. We could just add that policy to
> the Release Policy.
> * Stronger still, GHC should not switch to a new major release of a
> dependency at any time during feature freeze ahead of a release. E.g. if
> Cabal-3.0.0 ships before feature freeze for GHC-9.6, then maybe it's fair
> game to include in GHC. But not if Cabal-3.0.0 hasn't shipped yet.
> * The 3-release backwards compat rule should apply in all circumstances.
> That means major version bumps of any library GHC ships with, including
> base, should not imply any breaking change in the API's of any such library.
> * GHC does have control over reinstallable packages (like text and
> bytestring): GHC need not ship with the latest versions of these, if indeed
> they introduce breaking changes that would contravene the 3-release policy.
> * Note: today, users are effectively tied to whatever version of the
> packages ships with GHC (i.e. the "reinstallable" bit is problematic today
> for various technical reasons). That's why a breaking change in bytestring
> is technically a breaking change in GHC.
> * The current release policy covers API stability, but what about metadata?
> In the extreme, we could say a 3-release policy applies to metadata too.
> Meaning, all metadata shipping with GHC now and in the next 2 releases
> should be parseable by today's version of Cabal and downstream tooling. Is
> such a long lead time necessary? That's for build tool authors to say, and
> a point to negotiate with GHC devs.
> * Because there are far fewer consumers of metadata than consumers of say
> base, I think shorter lead time is reasonable. At the other extreme, it
> could even be just the few months during feature freeze.
> * The release notes bugs mentioned above and the lack of consistent upload
> to Hackage are a symptom of lack of release automation, I suspect. That's
> how to fix it, but we could also spell out in the Release Policy that GHC
> libraries should all be on Hackage from the day of release.
>
> Finally, a question for discussion:
>
> * Hackage allows revising the metadata of an uploaded package even without
> changing the version number. This happens routinely on Hackage today by the
> Hackage trustees. Should this be permitted for packages whose release is
> completely tied to that of GHC itself (like integer-gmp)?
>
> Best,
>
> Mathieu
>
>
> On 13 December 2017 at 17:43, Simon Peyton Jones via ghc-devs <
> ghc-devs at haskell.org> wrote:
>
>> Dear GHC devops group
>>
>> The conversation on Trac #14558
>> <https://ghc.haskell.org/trac/ghc/ticket/14558> suggests that we might
>> want to consider reviewing GHC’s release policies
>> <https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Releases>.
>> This email is to invite your input.
>>
>> The broad questions is this. We want GHC to serve the needs of all its
>> users, including downstream tooling that uses GHC.  What release policies
>> will best support that goal?  For example,  we already ensure that GHC 8.4
>> can be compiled with 8.2 and 8.0.  This imposes a slight tax on GHC
>> development, but it means that users don't need to upgrade quite as often.
>>  (If the tempo of releases increases, we might want to increase the window.)
>>
>> Trac #14558 suggests that we might want to ensure the metadata on GHC’s
>> built-in libraries is parsable with older Cabals.  One possibility would be
>> this:
>>
>>    - Ensure that the Cabal metadata of non-reinstallable packages (e.g.
>>    integer-gmp) shipped with GHC be parsable by the Cabal versions shipped
>>    with the last two major GHC releases [i.e. have a sufficiently old
>>    cabal-version field].  That is, in general a new Cabal specification will
>>    need to be shipped with two GHC releases before GHC will use start using
>>    its features in non-reinstallable packages.
>>    - Upholding this policy won't always be possible. There may be cases
>>    (as is the case Hadrian for GHC 8.4) where the benefit of quickly
>>    introducing incompatible syntax outweighs the need for compatibility. In
>>    this (hopefully rare) case we would explicitly advertise the
>>    incompatibility in the release documentation, and give as much notice as
>>    possible to users to allow downstream tools to adapt.
>>    - For reinstallable packages, of which GHC is simply a client (like
>>    text or bytestring), we can’t reasonably enforce such a policy, because GHC
>>    devs have no control over what the maintainers of external core libraries
>>    put in their Cabal files.
>>
>> This is just a proposal.  The narrow questions are these:
>>
>>    - Would this be sufficient to deal with the concerns raised in #14558?
>>    - Is it necessary, ow would anything simpler be sufficient?
>>    - What costs would the policy impose on GHC development?
>>    - There may be matters of detail: e.g. is two releases the right grace
>>    period. Would one do?
>>
>> Both the broad question and the narrow ones are appropriate for the Devops
>> group.
>>
>> Thanks!
>>
>> Simon
>>
>> _______________________________________________
>> ghc-devs mailing list
>> ghc-devs at haskell.org
>> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>>
>>
> -------------- next part --------------
> An HTML attachment was scrubbed...
> URL: <http://mail.haskell.org/pipermail/ghc-devs/attachments/20171213/3c54ee2e/attachment.html>
>
> ------------------------------
>
> Subject: Digest Footer
>
> _______________________________________________
> ghc-devs mailing list
> ghc-devs at haskell.org
> http://mail.haskell.org/cgi-bin/mailman/listinfo/ghc-devs
>
>
> ------------------------------
>
> End of ghc-devs Digest, Vol 172, Issue 15
> *****************************************

More information about the ghc-devs mailing list