Merge pull request haskell#5113 from phadej/spdx-migration-messages

Add licenseIdMigrationMessages. Resolves haskell#5109.
zw3rk · Feb 6, 2018 · 94a7374 · 94a7374
2 parents b995380 + 797250a
commit 94a7374
Show file tree

Hide file tree

Showing 4 changed files with 92 additions and 3 deletions.
diff --git a/Cabal/Distribution/SPDX/License.hs b/Cabal/Distribution/SPDX/License.hs
@@ -53,5 +53,12 @@ instance Pretty License where
     pretty NONE        = Disp.text "NONE"
     pretty (License l) = pretty l
 
+-- |
+-- >>> eitherParsec "BSD-3-Clause AND MIT" :: Either String License
+-- Right (License (EAnd (ELicense (ELicenseId BSD_3_Clause) Nothing) (ELicense (ELicenseId MIT) Nothing)))
+--
+-- >>> eitherParsec "NONE" :: Either String License
+-- Right NONE
+--
 instance Parsec License where
     parsec = NONE <$ P.try (P.string "NONE") <|> License <$> parsec
diff --git a/Cabal/Distribution/SPDX/LicenseExpression.hs b/Cabal/Distribution/SPDX/LicenseExpression.hs
@@ -89,7 +89,7 @@ instance Parsec SimpleLicenseExpression where
                 l <- idstring
                 maybe (fail $ "Incorrect LicenseRef format:" ++ n) (return . ELicenseRef) $ mkLicenseRef (Just d) l
             | otherwise = do
-                l <- maybe (fail $ "Unknown SPDX license identifier: " ++ n) return $ mkLicenseId n
+                l <- maybe (fail $ "Unknown SPDX license identifier: '" ++  n ++ "' " ++ licenseIdMigrationMessage n) return $ mkLicenseId n
                 orLater <- isJust <$> P.optional (P.char '+')
                 if orLater
                 then return (ELicenseIdPlus l)

diff --git a/Cabal/Distribution/SPDX/LicenseId.hs b/Cabal/Distribution/SPDX/LicenseId.hs
@@ -7,6 +7,8 @@ module Distribution.SPDX.LicenseId (
     licenseName,
     licenseIsOsiApproved,
     mkLicenseId,
+    -- * Helpers
+    licenseIdMigrationMessage,
     ) where
 
 import Distribution.Compat.Prelude
@@ -360,14 +362,53 @@ instance Binary LicenseId
 instance Pretty LicenseId where
     pretty = Disp.text . licenseId
 
+-- |
+-- >>> eitherParsec "BSD-3-Clause" :: Either String LicenseId
+-- Right BSD_3_Clause
+--
+-- >>> eitherParsec "BSD3" :: Either String LicenseId
+-- Left "...Unknown SPDX license identifier: 'BSD3' Do you mean BSD-3-Clause?"
+--
 instance Parsec LicenseId where
     parsec = do
         n <- some $ P.satisfy $ \c -> isAsciiAlphaNum c || c == '-' || c == '.'
-        maybe (fail $ "Unknown SPDX license identifier: " ++ n) return $ mkLicenseId n
+        maybe (fail $ "Unknown SPDX license identifier: '" ++  n ++ "' " ++ licenseIdMigrationMessage n) return $ mkLicenseId n
 
 instance NFData LicenseId where
     rnf l = l `seq` ()
 
+-- | Help message for migrating from non-SDPX license identifiers.
+--
+-- Old 'License' is almost SDPX, except for 'BSD2', 'BSD3'. This function
+-- suggests SPDX variant:
+--
+-- >>> licenseIdMigrationMessage "BSD3"
+-- "Do you mean BSD-3-Clause?"
+--
+-- Also 'OtherLicense', 'AllRightsReserved', and 'PublicDomain' aren't
+-- valid SPDX identifiers
+--
+-- >>> traverse_ (print . licenseIdMigrationMessage) [ "OtherLicense", "AllRightsReserved", "PublicDomain" ]
+-- "SPDX license list contains plenty of licenses. See https://spdx.org/licenses/. Also they can be combined into complex expressions with AND and OR."
+-- "You can use NONE as a value of license field."
+-- "Public Domain is a complex matter. See https://wiki.spdx.org/view/Legal_Team/Decisions/Dealing_with_Public_Domain_within_SPDX_Files. Consider using a proper license."
+--
+-- For other common licenses their old license format coincides with the SPDX identifiers:
+--
+-- >>> traverse eitherParsec ["GPL-2.0", "GPL-3.0", "LGPL-2.1", "MIT", "ISC", "MPL-2.0", "Apache-2.0"] :: Either String [LicenseId]
+-- Right [GPL_2_0,GPL_3_0,LGPL_2_1,MIT,ISC,MPL_2_0,Apache_2_0]
+--
+licenseIdMigrationMessage :: String -> String
+licenseIdMigrationMessage = go where
+    go "BSD3"              = "Do you mean BSD-3-Clause?"
+    go "BSD2"              = "Do you mean BSD-2-Clause?"
+    go "AllRightsReserved" = "You can use NONE as a value of license field."
+    go "OtherLicense"      = "SPDX license list contains plenty of licenses. See https://spdx.org/licenses/. Also they can be combined into complex expressions with AND and OR."
+    go "PublicDomain"      = "Public Domain is a complex matter. See https://wiki.spdx.org/view/Legal_Team/Decisions/Dealing_with_Public_Domain_within_SPDX_Files. Consider using a proper license."
+
+    -- otherwise, we don't know
+    go _ = ""
+
 -------------------------------------------------------------------------------
 -- License Data
 -------------------------------------------------------------------------------

diff --git a/boot/SPDX.LicenseId.template.hs b/boot/SPDX.LicenseId.template.hs
@@ -6,6 +6,8 @@ module Distribution.SPDX.LicenseId (
     licenseName,
     licenseIsOsiApproved,
     mkLicenseId,
+    -- * Helpers
+    licenseIdMigrationMessage,
     ) where
 
 import Distribution.Compat.Prelude
@@ -33,14 +35,53 @@ instance Binary LicenseId
 instance Pretty LicenseId where
     pretty = Disp.text . licenseId
 
+-- |
+-- >>> eitherParsec "BSD-3-Clause" :: Either String LicenseId
+-- Right BSD_3_Clause
+--
+-- >>> eitherParsec "BSD3" :: Either String LicenseId
+-- Left "...Unknown SPDX license identifier: 'BSD3' Do you mean BSD-3-Clause?"
+--
 instance Parsec LicenseId where
     parsec = do
         n <- some $ P.satisfy $ \c -> isAsciiAlphaNum c || c == '-' || c == '.'
-        maybe (fail $ "Unknown SPDX license identifier: " ++ n) return $ mkLicenseId n
+        maybe (fail $ "Unknown SPDX license identifier: '" ++  n ++ "' " ++ licenseIdMigrationMessage n) return $ mkLicenseId n
 
 instance NFData LicenseId where
     rnf l = l `seq` ()
 
+-- | Help message for migrating from non-SDPX license identifiers.
+--
+-- Old 'License' is almost SDPX, except for 'BSD2', 'BSD3'. This function
+-- suggests SPDX variant:
+--
+-- >>> licenseIdMigrationMessage "BSD3"
+-- "Do you mean BSD-3-Clause?"
+--
+-- Also 'OtherLicense', 'AllRightsReserved', and 'PublicDomain' aren't
+-- valid SPDX identifiers
+--
+-- >>> traverse_ (print . licenseIdMigrationMessage) [ "OtherLicense", "AllRightsReserved", "PublicDomain" ]
+-- "SPDX license list contains plenty of licenses. See https://spdx.org/licenses/. Also they can be combined into complex expressions with AND and OR."
+-- "You can use NONE as a value of license field."
+-- "Public Domain is a complex matter. See https://wiki.spdx.org/view/Legal_Team/Decisions/Dealing_with_Public_Domain_within_SPDX_Files. Consider using a proper license."
+--
+-- For other common licenses their old license format coincides with the SPDX identifiers:
+--
+-- >>> traverse eitherParsec ["GPL-2.0", "GPL-3.0", "LGPL-2.1", "MIT", "ISC", "MPL-2.0", "Apache-2.0"] :: Either String [LicenseId]
+-- Right [GPL_2_0,GPL_3_0,LGPL_2_1,MIT,ISC,MPL_2_0,Apache_2_0]
+--
+licenseIdMigrationMessage :: String -> String
+licenseIdMigrationMessage = go where
+    go "BSD3"              = "Do you mean BSD-3-Clause?"
+    go "BSD2"              = "Do you mean BSD-2-Clause?"
+    go "AllRightsReserved" = "You can use NONE as a value of license field."
+    go "OtherLicense"      = "SPDX license list contains plenty of licenses. See https://spdx.org/licenses/. Also they can be combined into complex expressions with AND and OR."
+    go "PublicDomain"      = "Public Domain is a complex matter. See https://wiki.spdx.org/view/Legal_Team/Decisions/Dealing_with_Public_Domain_within_SPDX_Files. Consider using a proper license."
+
+    -- otherwise, we don't know
+    go _ = ""
+
 -------------------------------------------------------------------------------
 -- License Data
 -------------------------------------------------------------------------------