Resolution: Won't Do
The way to pass configuration between scanners and scanner-engine is to use key/value strings. Also, this concept "leaks" into end user experience:
- Scanner CLI use a Java properties file + -Dkey=value on command line
- Maven support <properties> in pom.xml + -Dkey=value on command line
- Gradle support properties block + -Dkey=value on command line
- MSBuild support adding entries in SonarQube.Analysis.xml + /d:key=value on command line
Some properties are known to accept multi-values. The syntax is to separate values with a comma. There is no escape mechanism, so it prevents any value to contain a comma. Note that it really depends on the consumer: if the consumer expects a multi-value property, then value is split on comma. But if consumer expects a single value, then no split attempt is made, and so the value can contain a comma.
Syntax for modules is:
- complexity/size of properties (especially when there are many levels). This makes investigating harder, was a source of numerous bugs (but under control now) and also a bit costly to process (but not that important)
- a property declared in a parent module is inherited in children modules. There is no way to declare a property only for a module, and prevent it to be inherited. On the other side, there is no way to declare a property to be inherited but not "applied" to the current module.
- it is difficult for a user to apply a property to a specific module from the command line - at least with maven, it's impossible.
The file is read with ISO-8859-1 encoding. This makes it difficult to use it in non european languages (sonar.projectName, sonar.projectDescription, ...)
Backslash is used to escape some characters. It means that to properly pass Windows file paths, users have to double the backslash.
Multiline syntax is not user friendly, especially when using multi-value properties
There are 2 independent problems to solve:
- the technical protocol between scanners and scanner-engine
- the format of the configuration file for the SonarQube Scanner for CLI
The only real issue is the support of multi-value properties when the value contains a comma. Other concerns are minor (even inheritance) and the complexity is now under control. It has also proven to help evolving.
Starting from SonarQube 6.5 we could support a new syntax to pass multi-value properties. We could for example support comma escaping.
The problem is that this is a breaking change.
would have to be changed to:
It is also a bit ugly to have \ only escaping comma. Maybe it would be simpler/more robust to adopt an established syntax, for example JSON string array:
It is unlikely to have existing multi-value properties following this syntax. So backward compatibility could be easy to achieve.
We should not break backward compatibility. So the current format of sonar-project.property can't be changed. We can:
- introduce a new format in a new filename (e.g. sonar-project.json)
- keep the same name, but ask users to add a header to unlock new syntax (e.g. #format 2)
New format should:
- be encoded in UTF-8
- don't require to escape backslashes (Windows paths)
- have a simple support of multi-value properties, possibly with comma inside values, and spanning multiple lines
- simplify multi-module configuration
Example of using JSON:
- JSON doesn't support comments. We could pre-process the file to support comments.
- Is it really more user friendly than property file?
Example of using an "updated" property file:
- The JSON Array syntax would need to escape backslash twice (once for property decoding, once for JSON decoding)
- Same ugly multiline syntax