Document Environment and the default differences between Prod/Dev (#2090)

* Document Environment and the default differences between Production/Development

* Clarify that Environment is set by devenv up and deploy-to-nixos

* Link to Guide when referring to guide

Author: unhammer

IHP/Environment.hs

@@ -1,4 +1,17 @@
 module IHP.Environment where
 import IHP.Prelude
 
+-- | The 'Environment' type is used to switch between development and production configurations.
+--
+-- When running 'devenv up', this will be set to 'Development', while 'deploy-to-nixos' will set it to 'Production'.
+-- You can also manually set it with 'option Development' or 'option Production' in your Config.hs, or via the 'IHP_ENV' environment variable.
+--
+-- You can check the current environment using 'isDevelopment', 'isProduction', or 'isEnvironment' if you want to change behaviour based on the environment.
+-- IHP by default implements the following differences:
+--
+-- - Static file caching: In 'Development', browser cache is disabled (max-age=0). In 'Production', max-age is forever, with asset hashes for invalidation. See 'initStaticApp'.
+-- - Logger: In 'Development', logging uses the default format. In 'Production', it uses an Apache-style logger and higher log level. See 'ihpDefaultConfig'.
+-- - Background workers: In 'Development', a development job worker server is started automatically. In 'Production', you need to manually start a separate RunJobs process. See the [chapter on Jobs in the Guide](https://ihp.digitallyinduced.com/Guide/jobs.html#development-vs-production) for details.
+-- - Database connections: The pool idle time is by default shorter in 'Development'. See 'ihpDefaultConfig'.
+-- - Error pages: In 'Development', error pages may contain backtraces and details about the code, with links to the IDE. In 'Production', error pages do not contain implementation information.
 data Environment = Development | Production deriving (Eq, Show)

IHP/FrameworkConfig.hs

@@ -456,13 +456,17 @@ isEnvironment environment = ?context.frameworkConfig.environment == environment
 -- | Returns 'True'  when the application is running in Development mode
 --
 -- Development mode means that the Development option is configured in Config/Config.hs
+--
+-- See 'Environment' for documentation on the default differences.
 isDevelopment :: (?context :: context, ConfigProvider context) => Bool
 isDevelopment = isEnvironment Development
 {-# INLINABLE isDevelopment #-}
 
 -- | Returns 'True' when the application is running in Production mode
 --
 -- Production mode means that the Production option is configured in Config/Config.hs
+--
+-- See 'Environment' for documentation on the default differences.
 isProduction :: (?context :: context, ConfigProvider context) => Bool
 isProduction = isEnvironment Production
 {-# INLINABLE isProduction #-}