Implementing Upgrade Tracking: What It Is and Why It Matters
Before you write a single line of code or run the Repository Tool, the first step of the preparation phase is to establish your system of record. Systematic tracking is essential for a successful upgrade, providing a clear, real-time view of progress, issues, effort, and project-specific complexities.
This guide provides templates and best practices for setting up the core trackers that will guide you through the execution phase. A well-maintained set of trackers provides three key benefits:
- Real-time Visibility: Understand exactly where the project stands against the plan, allowing you to identify delays and manage stakeholder expectations.
- Knowledge Retention: Creates an invaluable audit trail of decisions made, problems solved, and customizations addressed, which is critical for future maintenance and subsequent upgrades.
- Improved Future Estimates: Capturing the actual effort spent on tasks provides a data-driven basis for more accurate future planning.
Table of Contents
The Customization & Risk Tracker
This is the most critical tracker you will maintain. It documents your project's unique fingerprint, capturing not just code customizations but also environmental or programmatic risks that can impact the upgrade. It should be a living document, reviewed and updated throughout the project.
Project Unique Attributes / Areas of Risk
Use this table to capture peculiarities of your project that aren't code customizations but still pose a risk or add complexity.
| Area | Description | Estimated Maintenance Effort (S/M/L/XL) | Estimated Remediation Effort (S/M/L/XL) | Risk (Low/Medium/ High/Critical) | Comments/Actions | Last Reviewed Date |
|---|---|---|---|---|---|---|
| CI/CD | Uses a custom Jenkins pipeline, not the standard Helm charts. | M | L | Medium | The custom deployment scripts may need significant updates for the new version. | 2026-03-26 |
| Programme | Shares a production data source with Use Case B. | S | S | High | Any changes to the shared source must be coordinated and tested with the Use Case B team. | 2026-03-26 |
| External Apps | The external 'Fraud Dashboard' uses our Search APIs directly. | L | L | Medium | API response changes in the new version could break the dashboard. Needs specific integration testing. | 2026-03-26 |
Customizations
Use this table to capture any way your solution deviates from standard Quantexa best practice, as per the Customizations documentation. This includes everything from overridden functions to workarounds and significant technical debt.
| Area (ETL/Apps/etc.) | Component | Description | Relevant Links (JIRA/Confluence) | Est. Maintenance Effort (S/M/L/XL) | Est. Remediation Effort (S/M/L/XL) | Risk (Low/Med/High/Critical) | Comments/Actions | Last Reviewed Date |
|---|---|---|---|---|---|---|---|---|
| ETL | Post-Processing | A custom Spark script runs after the main resolver to enrich entities from an external file. | [PROJ-1234] | M | L | Medium | This script uses an internal API that may change. It needs to be reviewed against the new version. | 2026-03-26 |
| Apps | Document Service | Custom bean override to change document sorting logic. | [PROJ-2468] | L | XL | High | This is a high-risk customization. The plan is to remove it and adopt the new out-of-the-box sorting feature. |
The Issue Tracker
This is your central log for all problems, questions, and unexpected behaviors encountered during the upgrade. It prevents issues from being forgotten and helps identify recurring patterns. For detailed guidance, see Issue Tracking Best Practices.
Ensure that any potential product bugs identified are fed back to Quantexa Support by raising a new post in Quantexa Platform Support on the Community.
The Effort Tracker
Tracking the actual effort spent is crucial for refining your project plan and improving future estimates.
At the end of each major stage or sprint, update a simple effort tracking table. This provides a clear comparison of planned vs. actual effort.
| Area / Major Task | Development Days Effort | Testing & Bug-fixing Days Effort | Total Days Elapsed for Acceptance | Comments |
|---|---|---|---|---|
| Repository Tool & Automated Migrations | 2 | 3 | 5 | Repository tool failed on two modules, requiring manual intervention. |
| Manual Migration: Document Service | 4 | 2 | 6 | More complex than estimated due to unforeseen impacts on custom User Interface (UI) viewers. |
| Manual Migration: ETL scripts | 2 | 1 | 3 | As expected. |
By establishing this system of tracking from day one, you create the visibility and data-driven foundation needed to successfully navigate the execution of your upgrade.
Quantexa Team
