This document should draw from the mailing list, FAQ wiki, MNGFAQ jira project (on codehaus), existing site documentation, project source code, and any IRC conversations necessary.
It should include:
- How can I tell which profiles are in effect during a build?
- What are the different types of profile? Where is each defined?
- Which areas of a POM can be customized by each type of profile? Why?
- settings-defined and profiles.xml-defined only modify properties, repositories, and pluginRepositories. This is necessary to preserve the portability of the pom as much as possible, since these two locations are not installed/deployed to the repository system.
- How can a profile be triggered? How does this vary according to the type of profile being used?
- Profiles are not inherited, but their effects are, because they are applied to the POM before it's used for inheritance. This means a parent POM will have its profiles triggered and applied before it is used to calculate the inherited values for the current POM. Please include this in the documentation as well.
There's probably more, but I can't think of it off the top of my head. We need to make this another one of those definitive documents for POM configuration.