Release 1.5.0 Notes (WIP)

[eeverman]

Using this discussion thread as a place to build up release notes for the pending 1.5.0

Release 1.5.0

This release jumps from 0.4.2 to 1.5.0, reflecting that AndHow has been in production long enough to be considered production ready, and there are API changes. This release removes deprecated methods, clarifies / subtly changes some behavior, and has general improvements and bug fixes. It's likely that minor application updates will be needed to upgrade from 0.4.x to 1.5.0, however, those changes are small and highlighted here.

Changes likely requiring application code changes

• Property builder validation methods beginning with mustXxx have all been renamed to be shorter and clearer in meaning. These new methods were available in 1.4.2, but 1.5.0 removes the older deprecated methods. For instance:

StrProp OLD_STYLE = StrProp.builder()
	.mustStartWithIgnoreCase("star").mustEndWith("ing").mustMatchRegex("star.+ing").build();

StrProp NEW_STYLE = StrProp.builder()
	.startsWithIgnoringCase("star").endsWith("ing").matches("star.+ing").build();

• Some AndHow initialization methods were removed (they were deprecated previously). In particular:

AndHow.findConfig().build();   // <-- This build() method has been removed
AndHow.instance(configuration);  // <-- This instance() method has been removed

These methods were replaced w/ new best practices. See Configuring AndHow and Testing for documentation and examples that would replace code potentially needing the removed methods.

• Deprecated methods generally have been removed. New usage patterns are well documented in the (User Manual)[http://andhowconfig.org] (Issue Remove all deprecated methods in the project #663).

Behavior Changes which may impact applications

• BolProps and FlagProps now throw an exception for unrecognized values (Issue BolProp and FlagProp should have explicit values for False #658).
  Prior to this release, BolProps and FlagProps had a list of true values (e.g. 'true', 'yes', 'on', 't', etc.) and considered all other non-empty values false. This was changed to prevent configuration errors where a value looks true, like 'truee', but is interpreted as false.
• FlagProps now act as flags only when loaded from command line (Issue FlagProp flag behavior should only apply to command line Loader #656)
  Prior to this release, any reference to the name of a FlagProp in any configuration source would set its value True, however, this behavior is only needed / desirable when used as a command line switch. To migrate, ensure that all non-command-line configuration for FlagProps fully specify the value as True or False (or an equivalent yes/no etc.)
• StdSysPropLoader & StdEnvVarLoader now trim String values (Issue StdSysPropLoader & StdEnvVarLoader should trim String values #654)
  If your application needs to preserve whitespace from these sources, wrap the complete value in double quotes. More details about whitespace handling is available.
• The Loader.load() method signature has changed and a few loader implementations which were not directly used were removed (Issue Loaders should use IoC instead of being constructed w source #679). This only affects users who have created custom loaders.

Internal changes / changes unlikely to affect users

• The ValueType.isParsable method was removed (Issue ValueType.isParsable should be removed #696). This would only affect user who have created custom ValueTypes.

Bug Fixes

• Calling setConfig() during initialization is now blocked (Issue AndHow should complain if setConfig(config) is called during initialization #718)

Other changes with zero or minimal impact to users of 0.4.2