Status
Current state: Under Discussion
Discussion thread: https://lists.apache.org/thread/ckb3tqnjf0h66rd0mlpfblpvkrvp3wq6
JIRA:
-
SOLR-17111Getting issue details...
STATUS
Released: <Solr Version>
Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast). Confluence supports inline comments that can also be used.
Motivation
System properties and environment variable names have been ad-hoc in Solr with no fixed syntax or structure. E.g we have both metricsEnabled
, enable.packages
and solr.clustering.enabled
. Want to set a standard, both for environment variables and system properties.
Public Interfaces
Configuration of Solr will be affected. Anywhere users configure Solr with environment variable or system property will need to change.
Proposed Changes
Some simple syntax rules are introduced
- Environment variables will follow the
SOLR_CATEGORY_FOO_BAR
naming (SOLR_ prefix, uppercase, underscores) - System properties will follow the
solr.category.foo.bar
naming (solr. prefix, lowercase, dots, no camelCase) - Both system property and environment variable always supported (already enforced by EnvUtils)
Furtuermore, we propose to strucure all vars/props in a hierarchy with at least a top-category and perhaps sub categories. Some examples
- Instead of
enable.packages
→solr.packages.enabled
/ SOLR_PACKAGES_ENABLED. - Instead of
enable.update.log
, →solr.index.updatelog.enabled
/SOLR_INDEX_UPDATELOG_ENABLED
There is a working wiki document at System property naming structure where we can collaborate on nailing down the new naming for all props, please contribute.
Implementation
We can implement an aliasing feature in EnvUtils so both old and new property will work with only a central configuration, and no need to double System.getProperty calls everywhere.
The renaming will then happen in a series of JIRAs, one per feature (e.g. highlighting or packages)
The new rules should be documented in dev-docs/ to be official.
Consider having a central registry of all properties in use? Probably not needed as we can analyze all java calls to EnvUtils.getProperty()
Compatibility, Deprecation, and Migration Plan
- All current sys.props will still work throughout 9.x, as an alias, with deprecation warning printed to logs
- New sys.prop names will be introduced in a series of PRs (one per top-category?, see JIRA)
- Cut over all sysProp reading to the new EnvUtils class, so that class can handle the old/new aliasing in one place (new property file?)
- In 10.0 (or even 11.0 if we want longer transition period), remove the aliases
Test Plan
The centralized aliasing logic will have own tests.
Each property that is cut over to new naming should consider adding test of both old and new property.
Rejected Alternatives
- Status Quo
- Randomly changing properties without a plan