GHC development flow

walking guide for new contributors

Takenobu T.

Rev. 2017-Feb-01

WIP

NOTE
- This is not an official document by the ghc development team.
- Please refer to the official documents in detail.
- This information is current as of Feb, 2017.

Overall relationshipDevelopment layers

Haskell packages

vectorparsecparallel

GHC compiler
GHC compiler+ Core Libraries

networklens...

Haskell Core Libraries

Compiler + Runtime systembase, array, process,...

Main ML : ghc-devs at haskell.org [1]Steering by GHC Committee [2]Main ML : libraries at haskell.org [3]Steering by Core Libraries Committee [4]Language Report

Haskell Language

GLUT

Haskell 98, Haskell 2010,
Haskell 2020
Main ML : haskell-prime at haskell.org [5]Steering by Haskell 2020 Committee [6]GHC compiler development flow

GHC compiler development flow (overview)
report the bug[8]fix the bug

add the feature[9]

report[10][11]

create andupdate pages

construct andmaintain infra

wiki
pages

infrastructure
tools

proposalcommitter[7]

code development[13]

release management [12][14]GHC compiler code development flowreport the bug

fix the bug

add the feature

proposalreport[8][10][11]

committerdirectcommitpatchflow

release management[9]

Report flow

create the ticket[8][15]ticketcode development[1]
Please consult ghc-devs ML if you worry.

Various ticket states of trac [15]ticketcreate a ticket
The ticket is waiting for someone to look at it and/or
discussion is underway on how to fix the issue.

Newacquire ownership(set “Owner” field”)

Assigned

Someone has said they are working on fixing the issue.

create a patch and request review(set “Differential Rev(s)” field”)

patchPatch

There is a patch to fix the issue that is awaiting review.

merge the patch to target branches

patchmasterMerge

A patch fixing the issue is present in the `master` branch and
we are considering backporting it to the stable branch.

resolved(set “Milestone” field”)

ClosedAs of the release listed in the "Milestone" field the bug isconsidered resolved.

Proposal flow
traditional process on trac [10]ghc-proposals process on github [11]write the proposal

write the proposal
wikipull request

create the ticket

discussionticket

discussion

revise proposal

update the ticket

request review bysteering committee

ticketwait for approval

wait for approval
ticketcreate the ticket
ticketcode development

Please refer to the documentation in details.

Patch flow
regular process [9]create the ticket
add a test case
fix the bug

Github PR process [9]create the ticket[15]
ticketadd a test case[16]

fix the bug[17]validation

validation
pull request
large patch

code review[18]

code review

small patch[23]

non-accepted[18]

update the ticket
ticketrelease management

Please refer to the documentation in details.

Document development flowVarious documents
Haskell wiki

Hackage documents

Haskell...
wiki.haskell.org

Trac wiki (GHC wiki)

hackage.haskell.org

The GHC users guideCore Libraries documents

GHC

...
ghc.haskell.org/trac/ghc/wiki[13]

about GHC’s implementation* how GHC works* how to modify it

downloads.haskell.org/~ghc/latest/docs/html/users_guide

[29]
[32]

downloads.haskell.org/~ghc/latest/docs/html/libraries

[31]
[32]

Document development of GHC
Haskell wiki

Hackage documents
haddock format
in source code

wiki markup

Haskell...

HTML

Trac wiki (GHC wiki)

HTMLThe GHC users guideCore Libraries documents.rst format

haddock format
in source code

Trac wiki markup

GHC

...
wiki

[13]

HTML

[28]
PDF

HTML
[29]
[32]

[30]

HTML
[31]
[32]

Trac wiki description flow [13]wiki

[13][24][27]register account[24]

log in[24]

create a page
page

[26][24][25]update a page
page

[24][25]

There are no formal process to discuss or review.
Please consult ghc-devs ML if you worry.
[1]

automated generation of HTML

Infrastructure tools

Tool relation
communication
discussion

ghc-devs ML[1]

information

Trac (wiki)[13]

code management

wiki

issue tracking,discussion and PR

issue tracking
and discussion

Github

Trac (ticket)[11]

code review[15]ticketPhabricator

code repository

performance regression

Git

Perf

[18]

[17]

[22]

phabricator cli

automated build

automated build

various builds

Arcanist

Harbormaster

Travis

GHC builder

[18]

[19]

[20]

[21]

ReferencesReferences[1]

ghc-devs -- GHC development discussion
https://mail.haskell.org/mailman/listinfo/ghc-devs[2]

The GHC Steering Committee
https://github.com/ghc-proposals/ghc-proposals/blob/master/steering-committee.rst[3]

Libraries -- Discussion about libraries for Haskell
https://mail.haskell.org/cgi-bin/mailman/listinfo/libraries[4]

Core Libraries Committee
https://wiki.haskell.org/Core_Libraries_Committee[5]

Haskell-prime -- Haskell' - A Haskell Standard Revision - discussion list
https://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-prime[6]

Welcome to Haskell'
https://prime.haskell.org[7]

The Glasgow Haskell Teamhttps://ghc.haskell.org/trac/ghc/wiki/TeamGHC[8]

Reporting bugs in GHC
https://ghc.haskell.org/trac/ghc/wiki/ReportABug[9]

How to contribute a patch to GHC
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/FixingBugs[10]

How to contribute a new feature to GHC
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/AddingFeaturesReferences[11]

GHC Proposals
https://github.com/ghc-proposals/ghc-proposals[12]

Release management and branches
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Releases[13]

Welcome to the GHC Developer Wiki
https://ghc.haskell.org/trac/ghc/wiki[14]

Developer’s Infrastructure
https://ghc.haskell.org/trac/ghc/wiki/Infrastructure[15]

The Bug Tracker
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/BugTracker[16]

Adding new test cases
https://ghc.haskell.org/trac/ghc/wiki/Building/RunningTests/Adding[17]

Using git with GHC
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git[18]

Using Phabricator for GHC development
https://ghc.haskell.org/trac/ghc/wiki/Phabricator[19]

Harbormaster: continuous integration & patch building for GHC
https://ghc.haskell.org/trac/ghc/wiki/Phabricator/Harbormaster[20] Travis
https://ghc.haskell.org/trac/ghc/wiki/Travis

References[21]

The GHC Builder
https://ghc.haskell.org/trac/ghc/wiki/Builder[22] perf
https://perf.haskell.org/ghc[23] Accept PRs on GitHub
https://github.com/ghc-proposals/ghc-proposals/pull/11

References[24] Notes on Trac Wiki formatting
https://ghc.haskell.org/trac/ghc/wiki/TracWikiMisc[25] WikiFormatting
https://ghc.haskell.org/trac/ghc/wiki/WikiFormatting[26] Steps to Add a New Wiki Page
https://ghc.haskell.org/trac/ghc/wiki/WikiNewPage[27] The Trac Wiki System
https://ghc.haskell.org/trac/ghc/wiki/TracWiki[28] source:ghc/docs/users_guide
https://ghc.haskell.org/trac/ghc/browser/ghc/docs/users_guide[29] Glasgow Haskell Compiler Users Guide
https://downloads.haskell.org/~ghc/latest/docs/html/users_guide[30] source:ghc/libraries
https://ghc.haskell.org/trac/ghc/browser/ghc/libraries[31]Haskell Hierarchical Libraries
https://downloads.haskell.org/~ghc/latest/docs/html/libraries[32] How to contribute a patch to GHC
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/FixingBugs

References
See also[33] Working on GHC
https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions[34] Resources for newcomers to GHC
https://ghc.haskell.org/trac/ghc/wiki/Newcomers[35] Haskell :: Reddit
https://www.reddit.com/r/haskell[36] IRC Channels
https://www.haskell.org/irc
http://ircbrowse.net/ghc