How things happen in GHC-land

#1

Several months ago the Haskell Foundation surveyed the community and articulated a set of medium-term goals for GHC. Among these priorities was a desire for more clarity about how GHC, as a large open-source project, is organised. In particular:

  • How do I know what is going on in GHC-land; for example, what releases are in progress, and what their schedule is?
  • How can I contribute to GHC?
  • How can I become a signed up member of the GHC Team?
  • How are decisions ultimately taken?

GHC is not my project, nor is it a project belonging to an elite few: it is our project, a shared endeavour of the whole Haskell community, with all its passion, expertise, and enthusiasm. We succeed through our shared efforts; we fail if (in perception or in reality) GHC somehow becomes isolated from the community it serves.

It should be easy to answer questions like those above. Thus motivated, we have created a new ghc-hq repository, whose landing page addresses these questions directly. As part of that same effort, we have completely refreshed the GHC Release Status page (linked from the landing page), which gives a regularly-updated snapshot of what is coming down the road.

This organisational structure is a work in progress not cast in stone, so we welcome discussion, perhaps on this Discourse thread.

Thanks!

Simon

45 Likes
#2

Thanks for the organisational transparency, this is really important! :heart:

3 Likes
#3

Very nice project!

#4

I think it’s really excellent to write down how the project is governed.

However, a bit of an organizational rant incoming…

It seems to me that the answer to questions like this is often on the GHC wiki, and this seems like a fine state of affairs given that the GHC team is very active in using it and keeping it up to date. Plus, once someone gets to the wiki, it’s much easier for them to discover other pages or e.g. search it.

So I wonder if:

  1. The information in the ghc-hq repository should just live in the GHC wiki
  2. We should spend some more effort on publicising the GHC wiki and making it obvious that information can be found there (in contrast, the ghc-hq repository is now “one more place” to look).
  3. (Maybe) We should spend some more effort tidying/structuring the GHC wiki so it is easier for newcomers to find e.g. contributing information

If anything, I would say that there are currently too many places that purport to say something about GHC:

  1. The README
  2. HACKING.md
  3. The wiki
  4. The GHC website
  5. (New) ghc-hq

If we expand the search to include other communiation channels we also have:

  1. The blog on the GHC website
  2. IRC/Matrix channels
  3. Multiple mailing lists: ghc-devs, glasgow-haskell-users (new to me, but linked from the README), possibly others?

To me this seems like an awful lot, and if I had to make a suggestion it would be to cut down on them, and definitely not introduce more places to look. For example, we could:

  • Move any content from HACKING.md that isn’t already there to the wiki, just link there from HACKING.md
  • Put the content from ghc-hq into the wiki or README
  • Retire the GHC blog (is it needed given other announcement channels?)
  • Potentially strip down the GHC website even more and just use it as a stable place for downloading binary distributions
  • Consolidate the mailing lists to a single one (in practice, are any other than ghc-devs in usage?)
11 Likes
#5

There’s also all the GHC-specific content on the Haskell wiki: if it’s still relevant, then that could also be brought across to the GHC wiki to be consolidated (and updated if necessary). The Haskell wiki can then be for just that: the Haskell language - syntax, semantics, etc.

#6

I think it would be useful to have separate places for GHC developers and GHC users. Or at least it should be very clear which pages are “official GHC information for users”, “official GHC information for developers”, and “developers’ musings”.

Also, I don’t think the GHC wiki is very discoverable. Gitlab search doesn’t work that well (searching for “heap” gives no wiki results). I sometimes resort to doing a text search on the title index and end up on pages that forward to other pages because the content has been moved (sometimes there are multiple links like that in a row).

3 Likes
#7

I think there’s a very important distinction between the ghc-hq repo and the GHC wiki: the ghc-hq repo is for discussing and documenting official GHC HQ structure and policies.

By its nature, the wiki is a bit of a free-for-all, full of out-of-date information and dead links, but also free for anyone to improve and containing valuable nuggets (if one can find them). In contrast, the ghc-hq repo is small (so it can be carefully tended) and changes via merge requests (so policy changes can be reviewed and merged only if there is consensus).

I’ve recently opened a couple of merge requests against the ghc-hq repo, and over time I would like to see more policies documented (e.g. I think we could do with something setting out the responsibilities of core library maintainers and release managers).

By all means we should cross-link the GHC wiki, ghc-hq repo and other information sources so people can easily find relevant content on one from another. But the wiki is simply not adequate for policy-making, because it is uncontrolled and there’s no way to be notified of changes or have them reviewed.

1 Like
#8

a) This is a concern for the maintainers of the documentation, not the users. As a user of this information, it’s still One More Place to look that I probably won’t find.
b) While I agree with your worries in principle, I doubt they would apply in reality. Are we really worried about someone sneaking in and changing the policy page of the wiki without permission? What would that gain them? People would notice pretty quickly if they tried to appeal to it. Similarly, all kinds of important information is on the wiki (e.g. the new release status page!) and gets updated without review or notification.

It would make sense to me if GHC devs wanted to move away from the wiki as a way of recording information, since it has some problems. My plea is just to try to not multiply information channels. If the wiki is inadequate, then move off the wiki, but don’t put just some information off the wiki.

Or, if you want to put it somewhere that is monitored and reviewed, how about in the GHC repository? That is an information channel that is definitely not going away, so doesn’t multiply things further.

3 Likes
#9

I think having this information available is fantastic. Indeed, it has inspired me to finish up a long running patch (for #23162: Make injectivity on closed type families more aggressive · Issues · Glasgow Haskell Compiler / GHC · GitLab), mostly due to the embarrassment of (quite reasonably) not appearing in the GHC Team listing.

As for location: I’m quite sympathetic to @michaelpj’s concerns about yet one more place to look. But I think that this may be a problem more in theory than in reality. Most readers will find documentation by Googling – not searching the wiki or the repo. If the wiki and the repo are cross-linked adequately, I’m not sure readers will really notice the difference. Maybe the problem is that readers will e.g. look at the URL to determine the legitimacy of the information and now has to add a new pattern to their good-list?

1 Like