[commit: ghc] master: Rewrite HACKING and convert to markdown. (d925639)

Austin Seipp mad.one at gmail.com
Mon Mar 4 07:25:49 CET 2013 

Repository : http://darcs.haskell.org/ghc.git/

On branch  : master

http://hackage.haskell.org/trac/ghc/changeset/d925639aed8ed29b97712b6aec8c25f0b1d5c352

>---------------------------------------------------------------

commit d925639aed8ed29b97712b6aec8c25f0b1d5c352
Author: Austin Seipp <aseipp at pobox.com>
Date:   Mon Mar 4 00:24:31 2013 -0600

    Rewrite HACKING and convert to markdown.
    
    Signed-off-by: Austin Seipp <aseipp at pobox.com>

>---------------------------------------------------------------

 HACKING    |  63 --------------------------
 HACKING.md | 149 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 149 insertions(+), 63 deletions(-)

diff --git a/HACKING b/HACKING
deleted file mode 100644
index 8ceff18..0000000
--- a/HACKING
+++ /dev/null
@@ -1,63 +0,0 @@
-Getting started with hacking on GHC
------------------------------------
-
-So you've decided to hack on GHC, congratulations!  We hope you have a
-rewarding experience.  This file will point you in the direction of
-information to help you get started right away.
-
-
-The GHC Developer's Wiki
-------------------------
-
-  The home for GHC Developers, with information on accessing the
-  latest sources, the bug tracker, and documentation on the
-  code:
-  
-  http://hackage.haskell.org/trac/ghc
-  
-  In particular, the wiki contains the following pages of interest to
-  new hackers:
-  
-  Quick Start for developers
-
-     http://hackage.haskell.org/trac/ghc/wiki/Building/Hacking
-
-     This section on the wiki will get you up and running with a
-     serviceable build tree in no time.
-
-     Don't skip this!  By default, GHC builds with all optimizations
-     and profiling; most hackers will want a quicker build, so creating
-     a mk/build.mk file and knowing how to rebuild only parts of GHC is
-     very important.
-
-     This is part of the "Building GHC" section of the wiki, which
-     has more detailed information on GHC's build system should you
-     need it.
-
-
-  Coding conventions
-
-     http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions
-
-     This wiki page explains the ground rules for code that is intended
-     to go into the mainline compiler source.
-  
-  
-  The GHC Commentary
-  
-     http://hackage.haskell.org/trac/ghc/wiki/Commentary
-
-     Notes on the internals and architecture of GHC.
-     
-
-Mailing lists
--------------
-
-   Ask on glasgow-haskell-users at haskell.org if you have difficulties.
-   If you're working with the current darcs sources of GHC, then
-   cvs-ghc at haskell.org might be a more appropriate (developers hang
-   out here).  See http://www.haskell.org/mailman/listinfo for
-   subscription.
-
-
-Happy Hacking!  --The GHC Team
diff --git a/HACKING.md b/HACKING.md
new file mode 100644
index 0000000..c886697
--- /dev/null
+++ b/HACKING.md
@@ -0,0 +1,149 @@
+Contributing to the Glasgow Haskell Compiler
+============================================
+
+So you've decided to hack on GHC, congratulations! We hope you have a
+rewarding experience. This file will point you in the direction of
+information to help you get started right away.
+
+The GHC Developer's Wiki
+========================
+
+The home for GHC hackers is our Trac instance, located here:
+
+<http://hackage.haskell.org/trac/ghc>
+
+From here, you can file bugs (or look them up,) use the wiki, view the
+`git` history, among other things. Of particular note is the building
+page, which has the high level overview of the build process and how
+to get the source:
+
+<http://hackage.haskell.org/trac/ghc/wiki/Building>
+
+Contributing patches to GHC in a hurry
+======================================
+
+Make sure your system has the necessary tools to compile GHC. You can
+find an overview here:
+
+<http://hackage.haskell.org/trac/ghc/wiki/Building/Preparation>
+
+Next, clone the repository and all the associated libraries:
+
+```
+$ git clone http://darcs.haskell.org/ghc.git/
+$ cd ghc
+$ ./sync-all --testsuite get
+```
+
+First copy `mk/build.mk.sample` to `mk/build.mk` and ensure it has
+your preferred build settings. (You probably want to at least set
+`BuildFlavour` to `quick`):
+
+```
+$ cp mk/build.mk.sample mk/build.mk
+$ ... double-check mk/build.mk ...
+```
+
+Now build. If you have multiple cores, **you should always use them to
+speed up compilation**:
+
+```
+$ ./boot
+$ ./configure
+$ make -jN # <N> is the number of cores you have.
+```
+
+You can use the `./inplace/bin/ghc-stage2` binary to play with the
+newly built compiler.
+
+Now, hack on your copy and rebuild (with `make`) as necessary.
+
+Then start by making your commits however you want. When you're done, you
+can use `git format-patch` to create a series of `.patch` files you
+can give to us. In this example, we'll assume I'm on a `bugfix` branch
+and want to submit my patches:
+
+```
+$ git branch
+* bugfix
+  master
+$ git format-patch master -o patches
+...
+$
+```
+
+Now create a trac ticket:
+
+<http://hackage.haskell.org/trac/ghc/newticket?type=bug>
+
+And attach the files in your `patches/` directory. Set the status from
+*new* to *patch* and we'll review it as soon as we can!
+
+Useful links:
+=============
+
+An overview of things like using git, the release process, filing bugs
+and more can be located here:
+
+<http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions>
+
+You can find our coding conventions for the compiler and RTS here:
+
+<http://hackage.haskell.org/trac/ghc/wiki/Commentary/CodingStyle>
+<http://hackage.haskell.org/trac/ghc/wiki/Commentary/Rts/Conventions>
+
+A high level overview of the bug tracker:
+
+<http://hackage.haskell.org/trac/ghc/wiki/WorkingConventions/BugTracker>
+
+If you're going to contribute regularly, **learning how to use the
+build system is important** and will save you lots of time. You should
+read over this page carefully:
+
+<http://hackage.haskell.org/trac/ghc/wiki/Building/Using>
+
+How to communicate with us
+==========================
+
+GHC is a big project, so you'll surely need help. Luckily, we can
+provide plenty through a variety of means!
+
+## IRC
+
+If you're an IRC user, be sure to drop by the official `#ghc` channel
+on [freenode](http://freenode.org). Many (but not all) of the
+developers and committers are actively there during a variety of
+hours.
+
+## Mailing lists
+
+In the event IRC does not work or if you'd like a bigger audience, GHC
+has several mailing lists for this purpose. The most important one is
+[ghc-devs](http://www.haskell.org/pipermail/ghc-devs/), which is where
+the developers actively hang out and discuss incoming changes and
+problems.
+
+There is no strict standard about where you post patches - either in
+`ghc-devs` or in the bug tracker. Ideally, please put it in the bug
+tracker with test cases or relevant information in a ticket, and set
+the ticket status to `patch`. By doing this, we'll see the patch
+quickly and be able to review. This will also ensure it doesn't get
+lost. But if the change is small and self contained, feel free to
+attach it to your email, and send it to `ghc-devs`.
+
+Furthermore, if you're a developer (or want to become one!) you're
+undoubtly also interested in the other mailing lists:
+
+ * [glasgow-haskell-users](http://www.haskell.org/mailman/listinfo/glasgow-haskell-users)
+   is where developers/users meet.
+ * [ghc-tickets](http://www.haskell.org/mailman/listinfo/ghc-tickets)
+   for email from Trac.
+ * [ghc-builds](http://www.haskell.org/mailman/listinfo/ghc-builds)
+   for nightly build emails.
+ * [ghc-commits](http://www.haskell.org/mailman/listinfo/ghc-commits)
+   for commit messages when someone pushes to the repository.
+
+El fin
+======
+
+Happy Hacking!  -- The GHC Team

More information about the ghc-commits mailing list