Opened 3 years ago

Closed 6 months ago

#11767 closed task (fixed)

Add @since annotations for base instances

Reported by: bgamari Owned by:
Priority: normal Milestone: 8.6.1
Component: Core Libraries Version: 7.10.3
Keywords: newcomer Cc: ekmett, RyanGlScott
Operating System: Unknown/Multiple Architecture: Unknown/Multiple
Type of failure: None/Unknown Test Case:
Blocked By: Blocking:
Related Tickets: #11768 Differential Rev(s): Phab:D2277, Phab:D4452
Wiki Page:

Description (last modified by bgamari)

Up until now we haven't been adding @since annotations for instances that we add to base (see Phab:D2051 for the discussion that spurred this ticket). We should try to get better coverage here.

Unfortunately, we currently have no way to place Haddock comments on derived instances, which limits our ability consistently add these annotations. We'll need to work out some mechanism for this (see #11768).

Change History (17)

comment:1 Changed 3 years ago by bgamari

Description: modified (diff)

comment:2 Changed 3 years ago by RyanGlScott

Cc: RyanGlScott added

comment:3 Changed 2 years ago by thomie

Keywords: newcomer added

comment:4 Changed 2 years ago by seraphime

Owner: set to seraphime

comment:5 Changed 2 years ago by RyanGlScott

Thanks for taking on this task, seraphime!

Figuring out the GHC versions when instances were introduced can be pretty tiring sometimes (since it involves a lot of git archeology). I recommend looking at the source of base-orphans, since it categorizes all of the new instances added to GHC (dating back to GHC 7.0) by the #if MIN_VERSION_base(x,y,z) blocks they fall under. For example, here are all of the new instances introduced in base-4.4 (GHC 7.2): https://github.com/haskell-compat/base-orphans/blob/cd918aef4915c5cc4051bb74a689d14ed1d2e233/src/Data/Orphans.hs#L86-L118

comment:6 Changed 2 years ago by seraphime

I have already written a script that seeks out the first commit in the git history where the instance appears, compares its timestamp to stamps which correspond to version bumps ( I found those by reading the commit history ). Comparison in the script is done on a single file, so files containing the same instance declaration will not disturb each other.

However, I couldn't find any indications about the release dates of versions before 2.01. Should the annotation specify something like "<= 2.01" or there is some way to find out their respective release dates ?

For instances I cannot check in the link you gave, can I trust the logs ?

comment:7 in reply to:  6 Changed 2 years ago by RyanGlScott

Wow, that script sounds very useful!

Replying to seraphime:

However, I couldn't find any indications about the release dates of versions before 2.01. Should the annotation specify something like "<= 2.01" or there is some way to find out their respective release dates ?

I'm not sure, but to be perfectly honest, I don't think anyone actually uses base <= 2.01, so I'd be OK with simply not giving @since annotations to things that are that old.

For instances I cannot check in the link you gave, can I trust the logs ?

The base-orphans link is merely a suggestion. If your script works well for you, by all means feel free to use that exclusively. But if you do need another cross-reference, base-orphans is regularly tested against multiple GHC versions, so it should be pretty accurate.

comment:8 Changed 2 years ago by RyanGlScott

Differential Rev(s): Phab:D2277
Status: newpatch

comment:9 in reply to:  6 Changed 2 years ago by Iceland_jack

Replying to seraphime:

I have already written a script [...]

Hm, have you tried running it on instances with existing @since and verifying the output?

comment:10 Changed 2 years ago by Ben Gamari <ben@…>

In a90085b/ghc:

Add @since annotations to base instances

Add @since annotations to instances in `base`.

Test Plan:
 * ./validate  # some commets shouldn't break the build
 * review the annotations for absurdities.

Reviewers: ekmett, goldfire, RyanGlScott, austin, hvr, bgamari

Reviewed By: RyanGlScott, hvr, bgamari

Subscribers: thomie

Differential Revision: https://phabricator.haskell.org/D2277

GHC Trac Issues: #11767

comment:11 Changed 2 years ago by RyanGlScott

After Phab:D2277, all that remains is for someone to annotate derived instances with @since annotations.

comment:12 Changed 2 years ago by bgamari

Owner: seraphime deleted
Status: patchnew

comment:13 Changed 2 years ago by bgamari

Milestone: 8.2.18.4.1

It seems unlikely that this will happen for 8.2. Punting.

comment:14 Changed 14 months ago by siddhanathan

As far as I can tell, there is no such thing as base 2.01

There is base 2.0, and there is base 2.1; the oldest version of base is 1.0

Easy check: git log -L 2,2:base.cabal

comment:15 Changed 10 months ago by bgamari

Milestone: 8.4.18.6.1

This ticket won't be resolved in 8.4; remilestoning for 8.6. Do holler if you are affected by this or would otherwise like to work on it.

comment:16 Changed 9 months ago by Ben Gamari <ben@…>

In 5c28ee8/ghc:

Add @since annotations for derived instances in base

Test Plan: ./validate

Reviewers: hvr, goldfire, bgamari, RyanGlScott

Reviewed By: RyanGlScott

Subscribers: rwbarton, thomie, carter

GHC Trac Issues: #11767

Differential Revision: https://phabricator.haskell.org/D4452

comment:17 Changed 6 months ago by RyanGlScott

Differential Rev(s): Phab:D2277Phab:D2277, Phab:D4452
Resolution: fixed
Status: newclosed
Note: See TracTickets for help on using tickets.