[commit: ghc] master: Add a note describing the protocol for adding a language extension (7861a22)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/7861a22561846eef9a6415a93d79e121dca9c05f/ghc

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

commit 7861a22561846eef9a6415a93d79e121dca9c05f
Author: Ben Gamari <bgamari.foss at gmail.com>
Date:   Wed Jan 6 20:00:16 2016 +0100

    Add a note describing the protocol for adding a language extension
    
    Reviewers: hvr, thomie, austin
    
    Reviewed By: austin
    
    Subscribers: duncan
    
    Differential Revision: https://phabricator.haskell.org/D1741
    
    GHC Trac Issues: #8176, #4437


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

7861a22561846eef9a6415a93d79e121dca9c05f
 compiler/main/DynFlags.hs       | 54 +++++++++++++++++++++++++++++++++++++++++
 testsuite/tests/driver/T4437.hs |  6 +++++
 testsuite/tests/driver/all.T    |  5 ++++
 3 files changed, 65 insertions(+)

diff --git a/compiler/main/DynFlags.hs b/compiler/main/DynFlags.hs
index d2b46c1..f8d759a 100644
--- a/compiler/main/DynFlags.hs
+++ b/compiler/main/DynFlags.hs
@@ -233,6 +233,59 @@ import qualified GHC.LanguageExtensions as LangExt
 -- have effect, and annotate it accordingly. For Flags use defFlag, defGhcFlag,
 -- defGhciFlag, and for FlagSpec use flagSpec or flagGhciSpec.
 
+-- Note [Adding a language extension]
+-- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--
+-- There are a few steps to adding (or removing) a language extension,
+--
+--  * Adding the extension to GHC.LanguageExtensions
+--
+--    The LangExt type in libraries/ghc-boot/GHC/LanguageExtensions.hs is
+--    the canonical list of language extensions known by GHC.
+--
+--  * Adding a flag to DynFlags.xFlags
+--
+--    This is fairly self-explanatory. The name should be concise, memorable,
+--    and consistent with any previous implementations of the similar idea in
+--    other Haskell compilers.
+--
+--  * Adding the flag to the documentation
+--
+--    This is the same as any other flag. See
+--    Note [Updating flag description in the User's Guide]
+--
+--  * Adding the flag to Cabal
+--
+--    The Cabal library has its own list of all language extensions supported
+--    by all major compilers. This is the list that user code being uploaded
+--    to Hackage is checked against to ensure language extension validity.
+--    Consequently, it is very important that this list remains up-to-date.
+--
+--    To this end, there is a testsuite test (testsuite/tests/driver/T4437.hs)
+--    whose job it is to ensure these GHC's extensions are consistent with
+--    Cabal.
+--
+--    The recommended workflow is,
+--
+--     1. Temporarily add your new language extension to the
+--        expectedGhcOnlyExtensions list in T4437 to ensure the test doesn't
+--        break while Cabal is updated.
+--
+--     2. After your GHC change is accepted, submit a Cabal pull request adding
+--        your new extension to Cabal's list (found in
+--        Cabal/Language/Haskell/Extension.hs).
+--
+--     3. After your Cabal change is accepted, let the GHC developers know so
+--        they can update the Cabal submodule and remove the extensions from
+--        expectedGhcOnlyExtensions.
+--
+--  * Adding the flag to the GHC Wiki
+--
+--    There is a change log tracking language extension additions and removals
+--    on the GHC wiki:  https://ghc.haskell.org/trac/ghc/wiki/LanguagePragmaHistory
+--
+--  See Trac #4437 and #8176.
+
 -- -----------------------------------------------------------------------------
 -- DynFlags
 
@@ -3103,6 +3156,7 @@ xFlags :: [FlagSpec LangExt.Extension]
 xFlags = [
 -- See Note [Updating flag description in the User's Guide]
 -- See Note [Supporting CLI completion]
+-- See Note [Adding a language extension]
 -- Please keep the list of flags below sorted alphabetically
   flagSpec "AllowAmbiguousTypes"              LangExt.AllowAmbiguousTypes,
   flagSpec "AlternativeLayoutRule"            LangExt.AlternativeLayoutRule,
diff --git a/testsuite/tests/driver/T4437.hs b/testsuite/tests/driver/T4437.hs
index f345ce6..5f14da1 100644
--- a/testsuite/tests/driver/T4437.hs
+++ b/testsuite/tests/driver/T4437.hs
@@ -1,3 +1,8 @@
+-- | A test for ensuring that GHC's supporting language extensions remains in
+-- sync with Cabal's own extension list.
+--
+-- If you have ended up here due to a test failure, please see
+-- Note [Adding a language extension] in compiler/main/DynFlags.hs.
 
 module Main (main) where
 
@@ -29,6 +34,7 @@ check title expected got
          showProblems "Unexpected flags" unexpected
          showProblems "Missing flags" missing
 
+-- See Note [Adding a language extension] in compiler/main/DynFlags.hs.
 expectedGhcOnlyExtensions :: [String]
 expectedGhcOnlyExtensions = ["RelaxedLayout",
                              "AlternativeLayoutRule",
diff --git a/testsuite/tests/driver/all.T b/testsuite/tests/driver/all.T
index 12522df..8493aa4 100644
--- a/testsuite/tests/driver/all.T
+++ b/testsuite/tests/driver/all.T
@@ -352,6 +352,11 @@ test('withRtsOpts', [ extra_clean(['withRtsOpts', 'withRtsOpts.exe',
 test('T3389', normal, compile_and_run, [''])
 test('T3364', normalise_fun(normalise_errmsg), run_command,
      ['$MAKE -s --no-print-directory T3364'])
+
+# T4437: A test to ensure that Cabal's language extension list remains
+# consistent with those known by GHC.
+#
+# See Note [Adding a language extension] in DynFlags.hs for details.
 test('T4437', only_ways(['normal']), compile_and_run, ['-package ghc'])
 
 test('werror', normal, compile_fail, [''])