[jira] [Updated] (UNOMI-1009) The 3.0 to 4.0 migration guide misses several breaking changes

["Serge Huber (Jira)" <ji...@apache.org>]

     [ https://issues.apache.org/jira/browse/UNOMI-1009?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Serge Huber updated UNOMI-1009:
-------------------------------
    Description: 
h3. Summary

The migration guide covers the main changes, such as API keys, cookies, passwords and REST roles. Several other changes can break existing installations or plugins and are not mentioned:
* Java API: changes to the scheduler, event, definitions and profile services, and to condition parameter default values.
* Plugins: some condition classes moved to a new plugin and package, and some artifacts and query builders were removed.
* Shell: 18 commands, such as profile-list, rule-list and segment-view, were replaced by unomi:crud.
* Stored data: document ids now start with the tenant id. This affects any script or dashboard that reads ids directly.
* REST: creating a profile with no itemId is now refused, and validation errors no longer include the detailed message.
* Configuration: GraphQL is enabled differently, and a health check option was renamed.
* Third-party servers: X-Unomi-Peer and the thirdparty configuration only apply in compatibility mode. In normal mode, protected events are controlled by tenant settings.
* The key file written by the migration names headers that do not exist. The public key goes in X-Unomi-Api-Key, and the private key is used with Basic authentication.

The goal of this ticket is that someone upgrading from 3.0 finds every breaking change in the guide.

h3. Ways to explore
* Add a "Breaking changes" section, grouped by audience: operators, integrators, plugin developers.
* Fix the text of the key file written by the migration.
* Use placeholders for keys and passwords in examples.

h3. How to test

Manual check: review the guide against the list above.

Automated tests and checks to add:
* A migration test that reads the key file written by the migration and checks that it names X-Unomi-Api-Key for the public key and Basic authentication for the private key.
* A test that runs the REST examples of the migration guide, at least the admin request with the tenant header, so the guide cannot drift from the code again.
* An API compatibility check in the build that compares the public Java API with the previous release, so future breaking changes are seen before a release and can be documented.

  was:
h3. Summary

The migration guide covers the main changes, such as API keys, cookies, passwords and REST roles. Several other changes can break existing installations or plugins and are not mentioned:
* Java API: changes to the scheduler, event, definitions and profile services, and to condition parameter default values.
* Plugins: some condition classes moved to a new plugin and package, and some artifacts and query builders were removed.
* Shell: 18 commands, such as profile-list, rule-list and segment-view, were replaced by unomi:crud.
* Stored data: document ids now start with the tenant id. This affects any script or dashboard that reads ids directly.
* REST: creating a profile with no itemId is now refused, and validation errors no longer include the detailed message.
* Configuration: GraphQL is enabled differently, and a health check option was renamed.
* Third-party servers: X-Unomi-Peer and the thirdparty configuration only apply in compatibility mode. In normal mode, protected events are controlled by tenant settings.
* The key file written by the migration names headers that do not exist. The public key goes in X-Unomi-Api-Key, and the private key is used with Basic authentication.

The goal of this ticket is that someone upgrading from 3.0 finds every breaking change in the guide.

h3. Ways to explore
* Add a "Breaking changes" section, grouped by audience: operators, integrators, plugin developers.
* Fix the text of the key file written by the migration.
* Use placeholders for keys and passwords in examples.

h3. How to test

Review the guide against the list above. Run the migration and check that the key file names the right headers.


> The 3.0 to 4.0 migration guide misses several breaking changes
> --------------------------------------------------------------
>
>                 Key: UNOMI-1009
>                 URL: https://issues.apache.org/jira/browse/UNOMI-1009
>             Project: Apache Unomi
>          Issue Type: Task
>            Reporter: Serge Huber
>            Priority: Major
>             Fix For: unomi-4.0.0
>
>
> h3. Summary
> The migration guide covers the main changes, such as API keys, cookies, passwords and REST roles. Several other changes can break existing installations or plugins and are not mentioned:
> * Java API: changes to the scheduler, event, definitions and profile services, and to condition parameter default values.
> * Plugins: some condition classes moved to a new plugin and package, and some artifacts and query builders were removed.
> * Shell: 18 commands, such as profile-list, rule-list and segment-view, were replaced by unomi:crud.
> * Stored data: document ids now start with the tenant id. This affects any script or dashboard that reads ids directly.
> * REST: creating a profile with no itemId is now refused, and validation errors no longer include the detailed message.
> * Configuration: GraphQL is enabled differently, and a health check option was renamed.
> * Third-party servers: X-Unomi-Peer and the thirdparty configuration only apply in compatibility mode. In normal mode, protected events are controlled by tenant settings.
> * The key file written by the migration names headers that do not exist. The public key goes in X-Unomi-Api-Key, and the private key is used with Basic authentication.
> The goal of this ticket is that someone upgrading from 3.0 finds every breaking change in the guide.
> h3. Ways to explore
> * Add a "Breaking changes" section, grouped by audience: operators, integrators, plugin developers.
> * Fix the text of the key file written by the migration.
> * Use placeholders for keys and passwords in examples.
> h3. How to test
> Manual check: review the guide against the list above.
> Automated tests and checks to add:
> * A migration test that reads the key file written by the migration and checks that it names X-Unomi-Api-Key for the public key and Basic authentication for the private key.
> * A test that runs the REST examples of the migration guide, at least the admin request with the tenant header, so the guide cannot drift from the code again.
> * An API compatibility check in the build that compares the public Java API with the previous release, so future breaking changes are seen before a release and can be documented.



--
This message was sent by Atlassian Jira
(v8.20.10#820010)