Define Upgrade Scope
With your Upgrade Roadmap and Upgrade Approach defined, it's time to translate that high-level strategy into a detailed project scope. This is arguably the most critical step in the planning process, as a clearly defined and bounded scope is your best defense against unexpected effort and scope creep.
This process involves three key activities: understanding the generic changes in the new version, analyzing how those changes impact your specific solution, and formally documenting the boundaries of the project.
Step 1: Understand the Delta
Before you can assess the impact on your project, you must first understand what has changed in the Quantexa platform itself. This involves a thorough review of the official release documentation for every "hop" in your upgrade path.
Action: For each version upgrade you are performing (e.g., v2.5 -> v2.6), review the following resources:
- Release Notes: To understand new features, bug fixes, and deprecations.
- Migration Guides: These provide the technical, step-by-step instructions for migrating code and configuration.
Step 2: High-Level Impact Analysis
This step is about creating a "heat map" to identify which major areas of your solution will be most affected by the upgrade. This is not a detailed task list, but a high-level summary to help you plan testing focus and ensure you have the right skills available.
Action: Identify all impacted components.
Create a high-level list of all parts of your solution that will be touched by the upgrade, including core platform components and any external satellite systems.
| Component | Impact Level (High/Med/Low) | Summary of Changes / Impact Drivers |
|---|---|---|
| ETL | High | Multiple breaking changes requiring manual migration. Repository Tool handles some, but not all. |
| Mid-Tier (Apps) | High | Significant manual effort required for Document Service and other API response changes. |
| Scoring | Medium | Mostly handled by the Repository Tool, but some function signatures have changed, impacting customizations. |
| Graph Scripting | Low | No breaking changes identified; regression testing is sufficient. |
| External: Data Packs | High | Requires a separate, dedicated upgrade project from v1.3 to v1.4. |
Action: Review your existing customizations.
Your project's existing customization tracker is a critical input here. Review every customization to assess whether the upgrade will impact it, and use this information to inform the impact level in the table above.
Step 3: Formalize the Scope (In vs. Out)
Now you will create the definitive, low-level list of what is in and out of scope for the project.
Action: Explicitly document what is OUT of scope.
It is just as important to document what you are not doing. This prevents ambiguity and manages stakeholder expectations. Major functional migrations and the adoption of brand-new features should almost always be treated as separate projects.
| Out of Scope Item | Current Status | Reason for Exclusion / Future Plan |
|---|---|---|
| Major Migration: Search v1 -> v2 | Search v1 is in use. | It will be planned as a separate initiative in the next quarter. |
| New Feature: 'New Analytics Module' | Not in use. | The business has not yet defined requirements for this module. It will be implemented at a later time. |
Action: Document the specific IN scope migrations and tasks.
Finally, create the definitive master list of all work that constitutes the upgrade project. Each row in this table should represent a single, actionable migration or change identified from the release notes and your impact analysis.
| Class | Component | Migration / Change | Type | Notes | Repo-Tool Migration Name | Documentation Link |
|---|---|---|---|---|---|---|
| Breaking | Apps | Document Service response changes | Manual | No conversion of Long to datestring by the apps - needs to be done by the project in doc viewers. | n/a | [2.5.0 Migration Guide#DocService](https://docs.quantexa.com/release-notes-component/latest/release-notes/2.5.x/2.4.x-2.5.0-migration-guide.html#document-service-responses) |
| Deprecation | ETL | OldApiCall() removed from library | Manual | OldApiCall() must be replaced with NewApiCall(). Search repository for all instances. | n/a | [2.7.0 Release Notes#Deprecations](link) |
The result of this page is a detailed scope document, centered around your "Impacted Components" and "In Scope Tasks" tables. This forms the solid foundation required for the next stage: Estimate The Upgrade.
Quantexa Team
