Instead of the environments struct, the default environment detection in ColdBox 5 will be like so:
This will look for an ENV var or Java System property of ENVIRONMENT and use that value as the environment name. If none is set, development will be used.
This is useful in situations like Docker containers where the container may ping itself at localhost, confusing the CGI lookup for environments.
Users can always go back to using the old environment structs.
You and I seem to have a different definition of incompatible. For me, keeping the environments struct around and not removing it (like datasources) means we are still compatible. Installing ColdBox 5 wouldn't change anything because it won't override a users config/ColdBox.cfc file (which is where this lives). It would just be for new templates coldbox create app. Heck, it doesn't even need to be ColdBox 5!
I'm not even sure we're talking about the same thing at all at this point then. I thought this ticket not to change how ColdBox internally functions. I didn't know you were just talking about the application templates! If that is the case, I'd say let's just make the core do this (like I thought we were talking about all along) instead of adding more boilerplate to the app templates. That way it can be controlled by convention instead of having the method boilerplate there. Just have it default back to the environment structs if the env var isn't present.
Another issue with that boilerplate is that it will essentially not be secure by default any longer. Our current app templates will default to development so long as you're on localhost, but if someone pushes that template into production without modifying the settings (which happens all too often) their production URL will default to the "production" environment which helps protect unscrupulous users. If we add that method boilerplate to our app templates, their app will continue using development settings if they push to prod without modifying it and don't have any env vars in use.
So, to your first point, adding new ColdBox functionality could be confusing — why isn't my environments set from the struct? Oh, a team member added an environment variable. Or, even harder to catch, our PaaS automatically sets an ENVIRONMENT key. For that reason I like the explicitness of the detectEnvironment function.
As for the second point, I see how that could be a problem. Laravel does this by defaulting to production but then shipping a .env with the key set to development. The only issue for us there is that commandbox-dotenv would need to be a devDependency in our application template. Not sure if that's sad or smart. There might be other ways we could do this — a production default but ship with development enabled. I think that would be good.
ColdBox made its first dollar bill on the convention-over-configuration shtick, so as long as it's well documented what the conventions are I don't personally see an issue. I mean you could make the same point about pretty much any convention in the framework that doesn't require an explicit configuration aspect. We've added built in support for reading environment variables out of the box in ColdBox so it feels like a pretty natural progression to introduce some basic conventions for using them. Maybe can break a tie here by chiming in
I agree on the genericness of the name and had thought it before. I'd suggest something like COLDBOX_ENVIRONMENT perhaps would help avoid a collision with other software on the same machine.
dotenv wouldn't need to be a dependency at all. So long as we fall back on the existing host-based lookup struct in the absense of an environment variable, we'd still keep the default behavior of hitting development on localhost or 127.0.0.1 in our app templates. Not that I'm opposed to dotenv though. I've actually wondered if it's handy enough to become core, but I really hate heading down that road or everything becomes core again...