[
https://issues.apache.org/jira/browse/UNOMI-1009?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18123485#comment-18123485
]
Serge Huber commented on UNOMI-1009:
------------------------------------
The decisions on related tickets add settings that people upgrading from 3.0
need to know about. The guide should cover them, with a safe example for each:
* UNOMI-1001: third-party servers in compatibility mode (provider keys, allowed
IP addresses and event types, trusted reverse proxies, the example key being
refused).
* UNOMI-1005: the list of website origins that may send cookies, and the
same-site setup.
* UNOMI-1007: the health check environment variables.
* UNOMI-1008: the tenant used by admin requests without a header, and how to
work in the "system" tenant.
* UNOMI-1012: compatibility mode for Unomi 2 and Unomi 3 clients.
The documentation is written as part of each ticket; this guide links to it and
checks that nothing is missing.
> 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)
