[GHC] #11767: Add @since annotations for base instances
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core | Version: 7.10.3 Libraries | Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: None/Unknown Unknown/Multiple | Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- 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. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * related: => #11768 @@ -7,1 +7,1 @@ - annotations. We'll need to work out some mechanism for this. + annotations. We'll need to work out some mechanism for this (see #11768). New description: 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). -- -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:1> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by RyanGlScott): * cc: RyanGlScott (added) -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:2> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by thomie): * keywords: => newcomer -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:3> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by seraphime): * owner: => seraphime -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:4> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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 -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:5> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (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 ? -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:6> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: #11768 | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by RyanGlScott): Wow, that script sounds very useful! Replying to [comment:6 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. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:7> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: patch Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Changes (by RyanGlScott): * status: new => patch * differential: => Phab:D2277 -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:8> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: patch Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Comment (by Iceland_jack): Replying to [comment:6 seraphime]:
I have already written a script [...]
Hm, have you tried running it on instances with existing `@since` and verifying the output? -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:9> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: patch Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Comment (by Ben Gamari <ben@…>): In [changeset:"a90085bd45239fffd65c01c24752a9bbcef346f1/ghc" a90085b/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="a90085bd45239fffd65c01c24752a9bbcef346f1" 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 }}} -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:10> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: seraphime Type: task | Status: patch Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Comment (by RyanGlScott): After Phab:D2277, all that remains is for someone to annotate derived instances with `@since` annotations. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:11> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.2.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Changes (by bgamari): * owner: seraphime => * status: patch => new -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:12> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Changes (by bgamari): * milestone: 8.2.1 => 8.4.1 Comment: It seems unlikely that this will happen for 8.2. Punting. -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:13> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: new Priority: normal | Milestone: 8.4.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Comment (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` -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:14> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: new Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 7.10.3 Resolution: | Keywords: newcomer 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: | -------------------------------------+------------------------------------- Comment (by Ben Gamari <ben@…>): In [changeset:"5c28ee88dd66617b0fd5dbe0d90142ce983a547e/ghc" 5c28ee8/ghc]: {{{ #!CommitTicketReference repository="ghc" revision="5c28ee88dd66617b0fd5dbe0d90142ce983a547e" 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 }}} -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:16> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
#11767: Add @since annotations for base instances -------------------------------------+------------------------------------- Reporter: bgamari | Owner: (none) Type: task | Status: closed Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 7.10.3 Resolution: fixed | Keywords: newcomer 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: | Phab:D4452 -------------------------------------+------------------------------------- Changes (by RyanGlScott): * status: new => closed * differential: Phab:D2277 => Phab:D2277, Phab:D4452 * resolution: => fixed -- Ticket URL: <http://ghc.haskell.org/trac/ghc/ticket/11767#comment:17> GHC <http://www.haskell.org/ghc/> The Glasgow Haskell Compiler
participants (1)
-
GHC