@@ -8,6 +8,7 @@ First of all, thanks for taking the time to contribute! 🎉👍
88 - [ Commit messages] ( #commit-messages )
99 - [ Changelog] ( #changelog )
1010- [ Development] ( #development )
11+ - [ Configuration and environment variables] ( #configuration-and-environment-variables )
1112 - [ Documentation] ( #documentation )
1213- [ Naming] ( #naming )
1314 - [ Instances and repositories] ( #instances-and-repositories )
@@ -91,6 +92,40 @@ This content will be automatically deleted by the CI after merging.
9192
9293## Development
9394
95+ ### Configuration and environment variables
96+
97+ The choice between environment variables and configuration files should be made based on the nature of the data and how it will be used.
98+
99+ ** Use environment variables for:**
100+
101+ - Secrets: API keys, passwords, tokens, or any sensitive data that should not be committed to version control. Examples:
102+ - ` OTA_ENGINE_GITHUB_TOKEN ` : GitHub API token for creating issues and managing repositories
103+ - ` OTA_ENGINE_SMTP_PASSWORD ` : Password for SMTP server authentication
104+ - Debugging flags: Toggles for development features. Examples:
105+ - ` OTA_ENGINE_FETCHER_NO_HEADLESS ` : Disables headless mode in Puppeteer to show the browser window during fetching
106+ - Unix standards: System-level settings following Unix conventions. Examples:
107+ - ` HTTP_PROXY ` , ` HTTPS_PROXY ` , ` http_proxy ` , ` https_proxy ` : Proxy server configuration for HTTP/HTTPS requests
108+ - Runtime overrides: Container-specific or deployment-specific settings that vary between environments. Examples:
109+ - ` OTA_ENGINE_FETCHER_NO_SANDBOX ` : Disables Chrome sandbox (required in some Docker environments)
110+
111+ ** Use configuration files for:**
112+
113+ - Engine behavior: Core functionality settings that define how the application operates. Examples:
114+ - ` trackingSchedule ` : Cron expression defining when to track terms (e.g., ` "30 */12 * * *" ` for every 12 hours)
115+ - ` fetcher.language ` : Language code for Accept-Language header in HTTP requests
116+ - Service settings: External service endpoints and integration parameters. Examples:
117+ - ` versionsRepositoryURL ` : URL of the GitHub repository storing document versions
118+ - ` logger.smtp.host ` : SMTP server hostname for sending error notifications
119+ - Static infrastructure: Deployment-independent paths and identifiers. Examples:
120+ - ` recorder.versions.storage.git.path ` : File system path where Git repository for versions is stored
121+ - ` recorder.versions.storage.git.author ` : Git commit author name and email for automated commits
122+
123+ When uncertain whether to use an environment variable or a configuration file, consider:
124+
125+ - Does it contain sensitive information? → Environment variable
126+ - Should it be version-controlled and reviewed? → Configuration file
127+ - Is it a stable setting that defines application behavior? → Configuration file
128+
94129### Documentation
95130
96131#### Copywriting
0 commit comments