Opened 21 months ago

Last modified 3 months ago

#11767 new task

Add @since annotations for base instances

Reported by: bgamari Owned by:
Priority: normal Milestone: 8.4.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
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 (14)

comment:1 Changed 21 months ago by bgamari

Description: modified (diff)

comment:2 Changed 20 months ago by RyanGlScott

Cc: RyanGlScott added

comment:3 Changed 19 months ago by thomie

Keywords: newcomer added

comment:4 Changed 19 months ago by seraphime

Owner: set to seraphime

comment:5 Changed 19 months 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 19 months 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 19 months 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 19 months ago by RyanGlScott

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

comment:9 in reply to:  6 Changed 19 months 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 19 months 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 19 months ago by RyanGlScott

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

comment:12 Changed 13 months ago by bgamari

Owner: seraphime deleted
Status: patchnew

comment:13 Changed 13 months ago by bgamari

Milestone: 8.2.18.4.1

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

comment:14 Changed 3 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

Note: See TracTickets for help on using tickets.