deegree stability manifesto (draft)
The overall goal for deegree stability is to achieve the following goals:
- All interfaces should be compatible between minor versions, i.e. upgrading to a more recent minor version should be a drop-in replacement.
- Existing configurations work as they did before.
- Code written against the deegree API works as before.
1. deegree 3.x
For the deegree 3.x series, the aim is to provide a stable configuration format. The API is explicitly excluded from stability requirements. As stable interfaces come at a price, this decision was made to strike the right balance between stability and still permitting design changes on the evolving code base.
In general, a deegree 3.0 workspace should work without changes in deegree 3.1 or 3.2. However, a few incompatible changes could not be avoided as some design concepts had to be changed that affected the configuration file formats.
1.1. From deegree 3.0 to 3.1
1.1.1. PostGISFeatureStore/SQLFeatureStore
PostGISFeature store configurations (schema) have been replaced by the more generic SQLFeatureStore configurations (schema). Therefore, existing PostGISFeature store configurations need to be manually transformed into SQLFeatureStore configurations. Changes:
- SQLFeatureStore configs work for PostGIS, Oracle (and all other RDBMS with a deegree dialect implementation) alike
- Improved mapping capabilities (rich application schemas to relational models)
1.2. From deegree 3.1 to 3.2
1.2.1. SQLFeatureStore
Some incompatible changes have been applied to the SQLFeatureStore configuration format (old schema/new schema). Therefore, existing SQLFeatureStore store configurations need to be manually adapted.
2. deegree 4.x and beyond
Beginning with the deegree 4.x series, the aim is to provide fully stable configuration formats and API (between minor versions). Any changes in minor versions should be backward compatible, e.g. new configuration options or configuration file types may be added, but existing ones must not be removed.
2.1. Stability ensurance process
In order to achieve stability, a suitable process must be agreed upon:
- Any incompatible configuration format or API changes need to be reported to the TMC. The TMC decides whether the change in question is so vital that a new major version is required or if it has to be rejected.
- There should be sufficient test coverage to detect incompatible changes in the API and configuration formats.
- TODO: What belongs to the (public) API? Every public type and method?
- TODO: Introduce a new Annotation @Api to indicate that a type (public class or interface) or public method (static) is part of the deegree API
- TODO: Does stability apply to every code module and configuration file format?