I have not found just one place which describes in detail the way in which project stages can be used.
I searched the following places to come up with the summary below:
It would be good if something like the following could be described:
Per default, any Swarm application will read the file project-stages.yml from the classpath. The location of this file can be overridden using the system property "swarm.project.stage.file". Which project stage is used is controlled by the system property "swarm.project.stage".
Project stage files contain default values in the first section (yaml document), followed by values per stage in subsequent sections, each of which should contain a unique value under "project : stage".
Values can be read using a swarm instance (e.g. in the main file). (please add more docs about this does: "Swarm swarm = new Swarm(false).withStageConfig(stageConfig);" )
Values can be read by reading the relevant system property, e.g. System.getProperty("some.integer.value");
Values can be injected via CDI, e.g.:
Values can be overridden at startup time by setting system properties using. e.g. "-Dsome.int.value=4" (and presumably by specifying a properties file using the -P command line argument?)
In this fashion, the default system configuration per environment can be set in project-stages.yml and if required be overridden without the need for additional build or deployment cycles (i.e. just a restart).
Note: Some of the existing docs are wrong, e.g. https://wildfly-swarm.gitbooks.io/wildfly-swarm-users-guide/content/configuration/project_stages.html which states "to use these stage properties you’d need to explicitly reference this file during Container bootstrap" => in fact the same page says "Auto detection picks up project-stages.yml from src/main/resources" whih conflicts with the word "explicitly".