diff --git a/TUBCO_SETUP.md b/TUBCO_SETUP.md index ce7501f..059acb0 100644 --- a/TUBCO_SETUP.md +++ b/TUBCO_SETUP.md @@ -2,6 +2,9 @@ Use this runbook when you want to set up or rebuild the TUBCO customer deployment from scratch. +Maintenance policy reference: +- [docs/TUBCO_MAINTENANCE_POLICY.md](/Users/bostame/Documents/workdock-platform/docs/TUBCO_MAINTENANCE_POLICY.md) + This is the customer-specific path. Normal product work still happens on: - `develop` - `main` @@ -171,6 +174,13 @@ For TUBCO: - security updates - UI improvements +Important: +- keep TUBCO on the old TUBCO database schema +- do not solve customer drift by importing the newer product schema into TUBCO +- if a deployed TUBCO environment starts failing on unknown non-null columns, verify DB/schema alignment first +- for the full maintenance rules, use: + - [docs/TUBCO_MAINTENANCE_POLICY.md](/Users/bostame/Documents/workdock-platform/docs/TUBCO_MAINTENANCE_POLICY.md) + Do not deploy TUBCO from: - `develop` - `main` diff --git a/docs/TUBCO_MAINTENANCE_POLICY.md b/docs/TUBCO_MAINTENANCE_POLICY.md new file mode 100644 index 0000000..13ff08a --- /dev/null +++ b/docs/TUBCO_MAINTENANCE_POLICY.md @@ -0,0 +1,136 @@ +# TUBCO Maintenance Policy + +Use this document whenever we maintain the TUBCO customer line. + +This is the rulebook for TUBCO. It is intentionally stricter than normal product work. + +## Goal + +TUBCO stays on its own older customer baseline. + +That means: +- keep the older TUBCO application behavior +- keep the older TUBCO database schema +- only cherry-pick approved fixes +- do not quietly turn TUBCO into the newer product + +## Source of truth + +TUBCO delivery happens from: +- `release/tubco-v1` + +Normal product work happens on: +- `develop` +- `main` + +Do not deploy TUBCO from: +- `develop` +- `main` + +## Core maintenance rules + +For TUBCO, we may backport only: +- bug fixes +- security fixes +- carefully approved UX improvements +- required operational fixes for the customer environment + +For TUBCO, we do not backport by default: +- new product workflows +- new approval/account-rule systems +- schema expansions from the newer product +- general feature growth unless explicitly approved + +## Database rule + +TUBCO must use the old TUBCO schema. + +This is the most important rule. + +If the code stays old but the database is newer, old TUBCO flows can fail with database errors such as: +- missing values for newer non-null columns +- forms saving rows that the old code does not know how to populate + +If we see errors like: +- `null value in column ... violates not-null constraint` + +then first verify whether the TUBCO environment is still using the old schema. + +Do not solve this by default with: +- broad schema compatibility backports +- importing the newer product data model into TUBCO + +That would move TUBCO toward the new product instead of preserving the customer baseline. + +## LAN server rule + +TUBCO is hosted on our local LAN server. + +Before deploying any TUBCO fix, verify: +- the server is running `release/tubco-v1` +- the environment points to the intended old TUBCO database +- no newer product migrations were applied there by mistake + +If the LAN server is connected to a newer migrated database, code-only fixes may not be enough. + +In that case, the correct options are: +1. repoint TUBCO to the old TUBCO database +2. or restore the database to the old TUBCO schema + +## Safe TUBCO release workflow + +1. start from: + - `release/tubco-v1` +2. implement only the approved fix +3. keep the database model old unless there is explicit customer approval to change it +4. test the affected flow +5. deploy only to the LAN-hosted TUBCO environment +6. do not run newer product migrations on that environment + +## Cherry-pick rule + +When a fix exists on another branch: +- inspect the commit carefully +- cherry-pick only if it does not pull in newer product behavior or newer schema assumptions + +If a fix depends on the newer schema: +- stop +- rework it as a TUBCO-only fix +- or do not ship it + +## Operational checklist before deploying a TUBCO fix + +Check all of these: +- branch is `release/tubco-v1` +- worktree is clean +- fix is limited to the approved TUBCO scope +- no new-product migrations are included +- no new-product workflows are included +- LAN server target is the intended TUBCO environment +- database is the old TUBCO schema + +## Example warning signs + +Pause and verify immediately if you see: +- approval-related fields appearing in old TUBCO flows +- new account-rule behavior on TUBCO +- migration files copied from the product branch +- database errors mentioning columns unknown to the old branch + +Those usually indicate code/schema drift. + +## Decision rule + +If there is a conflict between: +- shipping a quick fix +- and keeping TUBCO on the old customer baseline + +choose the old customer baseline first. + +We only widen the TUBCO schema or behavior if that change is explicitly intended for TUBCO. + +## Related documents + +- [TUBCO_SETUP.md](/Users/bostame/Documents/workdock-platform/TUBCO_SETUP.md) +- [DEPLOYMENT.md](/Users/bostame/Documents/workdock-platform/DEPLOYMENT.md) +- [CONTRIBUTING.md](/Users/bostame/Documents/workdock-platform/CONTRIBUTING.md)