API-tracker to check compliance with package versioning policy---advice please?
Hello everyone, I'm interested in writing the API-tracker described here http://hackage.haskell.org/trac/summer-of-code/ticket/1565 Mr. Marlow suggested I discuss it on the mailing list first. If this is the wrong list, I'm sorry, and I'd appreciate knowing where to find the correct one. This email consists of two parts: a high-level description of how I'd like to write the API-tracker, and the problems I encountered once I tried to bring that down to the level of actually writing code. I'd appreciate advice and criticism on both.
From the package versioning policy here http://www.haskell.org/haskellwiki/Package_versioning_policy it seems like the most foolproof way to validate a revised module's version number would be to diff the types of each exported symbol.
There's a previous thread on this list by Laszlo Nagy suggesting that we query other services that might already have this information, but the replies seemed to be of the opinion that it would be better to have fewer dependencies. I assume if this is meant to validate submitted packages, read access to both before and after versions are guaranteed. What do people think of the overall strategy? Following the suggestion of using the existing introspection tools in GHC, I found the modInfoExports and modInfoLookupName functions. However, I'm having some trouble understanding the GHC API because http://www.haskell.org/ghc/docs/latest/html/libraries/ghc-6.12.1/GHC.html only provides type information and sometimes a few cryptic comments. The other thing I've been trying is reading the Haddock source, because it's basically solving the same problem, right? Unfortunately, both efforts are stalling because I lack the necessary background knowledge of how GHC handles types. Is there a more verbose, newbie-friendly documentation that will answer questions like, "Suppose I have a function foo :: String -> String. How does GHC represent the type of this function?" I think http://hackage.haskell.org/trac/ghc/wiki/Commentary has the information I need to answer that question, or at least to read the GHC API reference. Unfortunately---you guessed it!---I don't know enough to understand the commentary. If all else fails, I supposed I'll just go post my questions in [beginners] or [haskell-cafe], but I'd prefer not to bother people unncessarily. In any case, thanks for your attention. I welcome any advice. Yours, Damon Wang
On 03/22/10 23:43, Damon Wang wrote:
Hello everyone,
I'm interested in writing the API-tracker described here http://hackage.haskell.org/trac/summer-of-code/ticket/1565 Mr. Marlow suggested I discuss it on the mailing list first. If this is the wrong list, I'm sorry, and I'd appreciate knowing where to find the correct one.
Excellent! (you could also try libraries@haskell.org , which contains more people)
From the package versioning policy here http://www.haskell.org/haskellwiki/Package_versioning_policy it seems like the most foolproof way to validate a revised module's version number would be to diff the types of each exported symbol.
There's a previous thread on this list by Laszlo Nagy suggesting
Can you link to it in online archives?
has the information I need to answer that question, or at least to read the GHC API reference. Unfortunately---you guessed it!---I don't know enough to understand the commentary.
hmm, I had this issue a bit last year, working on Haddock! But I eventually got used to it, by trying to do things with it. I found it's important to also go read the GHC code itself. Often it contains comments that didn't make it into the generated Haddockumentation; sometimes reading a function's implementation is necessary to guess what it does. Maybe you could find another project that uses the GHC API on types, and try to understand it? (for example, Haddock's code breaks up some version of the types in order to display them in docs, although I suspect it may be a less-processed, closer-to-source-syntax version than you'd want for actually comparing two types with each other). etc... And the Commentary is pretty good once you know enough (and some of the pages are overviews of the compiler pipeline...) and for ghc-specific questions, glasgow-haskell-users@haskell.org (or cvs-ghc@haskell.org sometimes for technical GHC-internals is alright) also, just lurking and reading relevant mailing-lists where other people are trying to solve their own problems relating to GHC: sometimes this helps :-) -Isaac
| Is there a more verbose, newbie-friendly documentation that will answer | questions like, | "Suppose I have a function foo :: String -> String. How does GHC | represent the type of this function?" We don't have verbose newbie-friendly documentation, I'm afraid. But GHC is an open-source compiler, and one thing that people can very helpfully contribute is precisely this sort of documentation. After all, a typical sequence is - "I wish I knew X" - Much reading of code, and consultation of the mailing lists - "Now I know X (to some degree)" It would be great to add - Add documentation about X to the Commentary The commentary is a wiki:, so anyone can add to it. We're happy to review draft changes. Meanwhile, to your point, the code you need is in compiler/types/TypeRep, which contains tha (very small) data type that represents types. Simon
participants (3)
-
Damon Wang -
Isaac Dupree -
Simon Peyton-Jones