ReCreatingAnew Joomla Refactoring Protocol

Phase 0 — Classification (RCS)

Phase Zero is the gate before the nine phases begin. RCS means RCA Refactor Classification System. It exists because every extension looks manageable at a glance — and some of them are lying.

Before you preserve the original package or run your first audit pass, you answer structured intake questions and document an initial classification: how much work this really is, what kind of debt you are inheriting, and whether the risk is structural, logical, data-related, security-related, or bad enough that a rebuild assessment is the honest answer. No refactor work, no client commitment, and no pretending you already know the scope starts without that record on file.

GinA: The ones you are most confident about are the ones that surprise you. I have been surprised by “simple plugins” that silently stopped doing half their job in Joomla 4 because a removed global was wrapped in a conditional that failed quietly. No error. No warning. Just features that were not running while the site owner paid for them. Classification exists so that story gets found in intake — not on a production site in front of a customer.

GinA's Maxim #19: “Every extension looks manageable at a glance. Classification is the tool that tells you whether it actually is — before you're three hours in and discovering the database schema hasn't had a foreign key since 2011 and the authentication logic calls a Joomla global that was removed in J4. Classify first. Always. Especially when you think you already know what class it is. The ones you're most confident about are the ones that surprise you.”

What Phase Zero is for

• Replace “I think this is a quick update” with a documented scope call before time and money are committed
• Surface security, database, and silent-breakage risk early
• Set expectations for how deep the refactor will go — syntax and namespaces vs architecture vs business logic vs data vs rebuild
• Produce an initial classification that Phase One and Phase Two will confirm or correct with evidence

Bella: A proper audit at intake would have answered every question in forty-five minutes. The discovery at Phase 1 answered the same questions in three hours — after scope and pricing were already on the table. The information was always available. The structured process to extract it was not. That is the difference between classification existing and not existing.

GinA: Bella is telling you Phase Zero and Phase One are related but not interchangeable. Phase Zero is the honest guess with structure. Phase One is the inventory that proves or disproves the guess. If Phase One changes the classification, you re-scope then. That is the system working. That is not you failing.

What “done” means

You have a written classification on file, agreed scope, and a clear go to enter Phase One. If the audit proves the first call was wrong, you stop expanding work on the old assumption and reset expectations before Phase Two.

Briony: I do not care how simple it looked in the email. I care whether the classification is documented. Proceed when it is. Not before.

Phase 1 — Artifact Preservation

Nine phases. Nine lives of the refactor. Phase One is the one people try to skip because it feels like paperwork. It is not paperwork. It is the only thing standing between you and a refactor you cannot undo, explain, or defend when something breaks on a real site.

Before you change a single file, you preserve the artifact and record what you actually received: extension name, version, author, license, what is inside the package (components, modules, plugins), database table shapes if the installer owns schema, and whether this work is meant to be public or kept private. The unmodified package lives in your originals archive — the copy you never “just fix quickly” and never overwrite because you were sure you would remember.

GinA: I have skipped this step exactly once in a way that mattered. That was enough. You do not get a do-over on “what did the zip contain before we touched it?” You get a client email, a diff you do not trust, and you trying to reconstruct history from JED and hope. Read Phase One as non-negotiable. It is boring on purpose. Boring is cheaper than archaeology.

What Phase One is for

• Preserve the original installable package before any refactor work
• Record identity and lineage: name, version, author, license, sub-packages
• Document database-related structure the extension expects, if applicable
• Mark visibility: publishable work vs proprietary or internal work
• Establish the baseline Phase Zero classification will be confirmed against in Phase Two — not vibes, evidence

Bella: Nothing is touched until everything is recorded. You do not begin by changing things. You begin by knowing exactly what you have. Rushing past this phase is how you spend three days trying to remember what the original code looked like.

GinA: Bella is not being dramatic. She is being accurate. Senior Code Reviewer means she looks at what is there, not what you assumed was there. If she were satisfied with assumptions, I would fire her. I cannot fire her. She outranks me. Listen to her.

What “done” means

Phase One is complete when you could hand the preserved original and the written inventory to someone else and they could reconstruct the starting point without asking you what you deleted from memory. After that — and only after that — you are allowed to discover how bad Phase Two is going to be.

Briony: I do not care how confident you are. I care whether the work is correct. Phase One is correct when the record is correct. Proceed.

Phase 2 — Architectural Audit

Phase Two is the stalk. You have preserved the artifact. Now you observe the architecture without fixing it yet — extension type, MVC pattern (legacy flat structure, partial modern layout, or full PSR-4), complexity tier, dependencies, database tables, and the places this code touches Joomla in ways that will fight you later.

This phase is not exciting. It is essential. You map exit routes before you leap. You document what is actually there, not what the marketing page claimed or what you remember from the last time you opened the zip.

GinA: Phase Two is where Phase Zero gets confirmed or corrected. If you discover the “simple namespace update” is sitting on top of business logic that depends on behavior Joomla removed years ago, you do not push ahead and hope. You re-scope. I have watched developers treat a re-scope like a personal failure. It is not. It is the protocol doing its job.

What Phase Two is for

• Classify extension type and how it is structured on disk and in the manifest
• Identify MVC pattern and whether modern Joomla dependency injection and services registration exist
• Rate complexity and map dependencies (core, third-party, database, external services)
• Document integration points and likely failure modes before deprecation mapping begins
• Confirm or update Phase Zero classification with evidence from the preserved baseline

Briony: I have been in this house since 2009. I have watched every version of everything GinA has built. I do not concern myself with which Life the Protocol is on. I concern myself with whether the work is correct. When the audit is correct, you may proceed. When it is not, neither may you.

GinA: Briony stays in known territory on purpose. Your extension does not get that luxury. Phase Two is how you learn the terrain before you commit to a refactor path you cannot walk back from in one afternoon.

What “done” means

You can describe this extension’s architecture, its failure points, and its salvageable core without guessing. If you cannot explain it to another developer without opening the code every thirty seconds, the audit is not done.

Bella: Look at what is there. Not what you wish were there. When you can do that consistently, Phase Two is complete.

Phase 3 — Deprecation Mapping

Phase Three is mark your territory. You do not start rewriting yet. You map what must change: deprecated API calls, structural patterns that no longer match Joomla 4/5/6, manifest and namespace gaps, and removals that will break on the next major version if you pretend they are “fine for now.”

Scan first. List second. Fix in Phase Four. The map groups work by type — direct substitutions, structural refactors, architecture you must add, and patterns that are gone in current Joomla — so Phase Four is execution, not improvisation.

GinA's Maxim #16: “These phases are in this order for a reason. I didn't make them up sitting in a coffee shop. They're in this order because I did them in the WRONG order and paid for it. Trust the sequence. Don't skip. Don't reorder. Don't tell yourself Phase 3 doesn't apply to you because your extension is 'simple.' They all seem simple until they're not.”

GinA: Deprecation mapping feels like delay. It is the opposite. It is how you avoid doing the same substitution twice, missing a `use` statement on file fourteen, or discovering at install time that the manifest never declared a namespace path. The map is boring. Boring saves weekends.

What Phase Three is for

• Inventory deprecated Joomla and PHP patterns across the codebase (excluding vendor where appropriate)
• Assign each finding to a replacement strategy before anyone edits source
• Identify missing modern scaffolding (services provider, extension class, PSR-4 layout) as planned work, not surprises
• Flag blockers that need manual research — not guesses from memory
• Produce a refactor plan Phase Four executes in order

Bella: The UI exists for a reason. It is not a limitation. It is the correct tool for this operation. Use it.

GinA: That maxim was about the database UI. The principle applies here too. The right tool for mapping is a structured pass and a written list — not “I will fix things as I notice them” while you refactor. That is how you ship a half-migrated extension and call it done.

What “done” means

Every known deprecation and structural gap is documented with an intended fix or an explicit blocker. Phase Four does not start with “we will figure out Category B while we are in the files.”

Briony: Territory marked means boundaries known. Proceed to the groom when the map is complete. Not when you are tired of planning.

Phase 4 — Refactor Execution Order

Phase Four is the groom. You work the plan — systematically, in the order the protocol defines — not creatively in the middle because you saw something shiny.

Snapshot confirmation. Direct API substitutions with import audits. Structural changes. Architecture gaps filled. Removals and database access patterns updated. Version bumps and manifest updates across the whole package suite. Rebuild installable packages. Verify you did not break content or installer-owned data on the way through.

Miss Francy thinks this phase is boring. Miss Francy is wrong. Miss Francy is also three years old and has not yet learned that boring and correct are frequently the same thing.

GinA's Maxim #4: “J3 code that 'still works' in J5 is a ticking clock, not a win. Deprecated doesn't mean broken YET — it means broken SOON. And 'soon' in Joomla's release cycle is faster than you think. Fix it now while you're already in the code. Future-you will be grateful. Future-you's clients will be grateful. Future-you's 3am emergency calls will NOT happen.”

GinA: Phase Four is where discipline matters more than cleverness. You will see adjacent improvements that are not in scope. Write them down for later. Stay in the plan. Finish the groom. The extension does not need your side quest during a migration; it needs to land on supported APIs and a structure Joomla can actually load.

What Phase Four is for

• Execute the Phase Three map in sequence — no skipping families of changes
• Keep business logic intact while replacing deprecated integration patterns
• Align manifests, namespaces, and target platform declarations across the suite
• Bump versions and rebuild packages as a coherent release, not a pile of partial fixes
• Run verification appropriate to what changed (syntax, installer, content SQL if touched)

What “done” means

The codebase meets the target Joomla and PHP compatibility goals from the plan, packages rebuild cleanly, and you are not uncomfortable opening the diff. If you are uncomfortable and cannot articulate why, you are not done — you are in Phase Five’s territory early. Good. Stay there until it is resolved.

Briony: Half a groom is not a groom. Complete the pass or do not claim Phase Four.

Phase 5 — Manual Validation

Phase Five is the tick check. The code went out through your editor, your staging mindset, and every environment that was not production. Now it is back from the adventure, and it needs to be combed. Not glanced at. Combed. Down to the skin.

Read every modified file. Confirm business logic still means what it meant. Confirm queries, forms, installer hooks, permissions, and language strings still behave. Confirm you did not hardcode paths that only exist on your laptop. Run syntax validation on every PHP file you touched. If installer work touched articles or categories, validate content and assets the way the protocol requires — not “looks fine in the browser once.”

Miss Francy: I check everywhere. Not just where you think the ticks would be. Especially not just there. I have found things in the installer that nobody thought to look at because the installer "worked." It worked. It also had a tick. These are not mutually exclusive.

Miss Francy: This is my phase. I will find what you missed. I always do. The question is whether you want me to find it here, in Phase 5, before anything ships — or whether you would prefer I find it in production in front of a customer. I do not have a preference. I will find it either way.

GinA's Maxim #17: “READ. THE. FILE. I know you think you know what's in it because you just wrote it. Read it anyway. I cannot count the number of times a quick re-read caught a hardcoded path, a wrong class name, or a copy-paste leftover from the last extension. Your eyes will find things your brain glosses over. Read it.”

GinA: Phase Five is not automated tests replacing human judgment. It is human judgment backed by evidence. When you find something, you do not “mostly fix it.” You burn it, verify it is gone, and log it. Found is not the standard. Fixed and confirmed is the standard.

What Phase Five is for

• Manual review of all changed source, manifests, and language files
• Preserve ACL, workflows, and business rules the extension depended on
• Catch copy-paste and path errors automated scans miss
• Validate installer and content impact when SQL or schema work occurred
• Gate packaging: do not treat Phase Six as a substitute for reading the files

What “done” means

You have read the work, verified what matters for this extension, and fixed what you found — with syntax clean and no known “we will fix that later” items hiding in the diff.

Briony: Surface ticks belong here. Burrowed ticks belong in production. Choose where you want to work.

Phase 6 — Multi-Version Testing

Phase Six is the pounce. You have stalked, mapped, groomed, and combed. Now you find out if it actually works on Joomla the way real sites run it.

Test current Joomla first — the version you are certifying for must pass completely. Then smoke-test supported older majors where the product still claims compatibility. Clean install. Upgrade from the previous release. Admin UI. Frontend output. Uninstall. Repeat on a site that is not a pristine demo when you can, because pristine demos lie about what production feels like.

GinA: If your extension only works on a fresh demo with no template overrides, no caching weirdness, and no third-party plugins, it does not work. It works in a laboratory. Laboratories are not where your customers live.

What Phase Six is for

• Prove install and upgrade paths on supported Joomla versions
• Exercise admin and site interfaces after migration
• Confirm uninstall and reinstall behavior where applicable
• Catch version-specific routing, asset, and session issues automated review missed
• Document test results — not vibes, evidence

What “done” means

Required tests pass on the target Joomla version; smoke tests pass where you still support older majors; results are written down. Feelings are not a test suite. Passing tests are.

Miss Francy: I approach every scenario as though it personally insulted me. That is why I am good at this phase. You may borrow the attitude.

Briony: The pounce fails in the yard, not in the client’s house. Fail here on purpose until it passes.

Phase 7 — UI/UX Review

Phase Seven is the display check. The code compiles and the tests passed. That does not mean a human can use it without embarrassment.

On an installed instance, review admin toolbars, list views, and form views. Review frontend markup and module or plugin output. Confirm language strings resolve — no raw `COM_` keys staring at an administrator who already had a long day. Confirm Bootstrap-aligned output where the template expects it. Confirm the extension behaves like it belongs in Joomla 4/5/6, not like a J3 dialog wearing a hat.

Miss Francy: I am the UX tester. This is literally my job title. If you skip this phase I will still test it — I test everything, I cannot be stopped — but I will do it in a context where the results are embarrassing rather than useful. Your choice.

GinA: Broken language files are not a “minor polish item.” They are the admin interface telling your customer you did not finish. Raw keys are how you lose trust faster than a fatal error — because a fatal error at least looks like an accident. Raw keys look like you shipped anyway.

What Phase Seven is for

• Validate administrator experience on real list and edit screens
• Validate site output and layout integration
• Confirm translations and help text render as language, not constants
• Catch UX failures that tests and code review do not see
• Fix display issues before hardening and release, when they are cheap

What “done” means

A competent administrator can configure and use the extension without hitting untranslated strings, broken layouts, or controls that make no sense in context. If Miss Francy would sigh at it, you are not done.

Briony: I do not use the admin interface. I observe whether you looked like you cared when you built it. Phase Seven is where that shows.

Phase 8 — Hardening

Phase Eight is the tick collar. Before the code goes back out on its next adventure, you apply the preventive measures that make the next infestation harder. The collar does not guarantee zero ticks — nothing does. It makes attachment significantly harder and buys time to find what gets through anyway.

Hardening is not a substitute for Phase Five’s comb. It is preparation so the next comb is shorter. Remove debug and assistant cruft from source. Confirm manifests declare supported Joomla versions consistently across a package suite. Confirm author, license, and update metadata match what you intend to ship. Apply JED-oriented compliance for forked work vs original RCA work — different rules, same standard: ship something you would not be ashamed to list. Decide install defaults honestly: self-contained extensions should work when installed; integrations that need API keys first should not expose broken functionality to visitors on day one.

Phase Eight is the tick collar. Phase Five is still the comb. Do not confuse them.

GinA's Maxim #18: “Nobody installs a self-contained plugin planning to leave it disabled. Nobody. If they install it, they want it working. Shipping disabled-by-default is the equivalent of selling someone a lamp that's not plugged in and forgetting to mention the outlet. Add the installer script. It's 20 lines. There is no excuse.”

GinA: The corollary matters too. Nobody installs a payment gateway planning to expose it to customers before they enter a single API key. Know what you ship. Default accordingly. Hardening includes not creating support tickets through lazy defaults.

What Phase Eight is for

• Strip non-shippable comments and tooling artifacts from release source
• Align manifest schema, target platforms, and suite metadata
• Complete compliance checks appropriate to forked vs original extensions
• Document extension history and known risks for the next maintainer
• Set sane enable/disable behavior on install where the extension type requires it

What “done” means

The release candidate is structurally ready to ship: manifests honest, compliance addressed, defaults defensible, and nothing in the tree that screams “draft.”

Briony: Territory claimed is not territory secured. The collar goes on before the door opens.

Phase 9 — Update Server Deployment

Phase Nine is the handoff. You made it through eight lives of this refactor. Do not blow the ninth because you are tired and it is probably fine.

Every release that uses an update server must pass a non-negotiable verification pass: feed file reachable, feed content matches the extension identity in Joomla, version increments correctly, download URL points at the actual ZIP, checksums match bytes on disk, and a human can install the update on a test site without inventing a workaround. Confirm author display and client scope for plugins and modules. Celebrate after the checklist — not before.

GinA's Maxim #20: “You made it to Phase 9. Do NOT blow it now by skipping the verification steps because you're tired and it's probably fine. 'Probably fine' is how you end up on the phone with a frustrated client whose Joomla site is showing a 404 on the update download URL because you forgot to check HTTP 200. Check it. All of it. Then celebrate.”

Briony: You have reached Phase 9. You have used eight lives of this refactor. Use the ninth correctly. Check every step. Verify every URL. Confirm the author display. Do not celebrate until the checklist is complete. Celebrating early is how you end up with a v1.0.5 that ships the v1.0.4 ZIP because you forgot to verify the file on the server.

GinA: Phase Nine is where “the code is fine” meets “the update system is broken.” Those are different failures. Both are yours if you ship without checking. I have done the 404-on-download conversation. It is not a conversation you want twice in one quarter.

What Phase Nine is for

• Verify update feed accessibility and correct metadata
• Verify release ZIP exists, matches checksum, and installs as an upgrade
• Align version numbers across feed, manifest, and packaged files
• Confirm download paths and permissions on the live update infrastructure
• Close the release with evidence, not assumption

What “done” means

A site running the previous version can update to the new ZIP using the published feed, the checksum validates, and you can point to test evidence. Then — and only then — you are allowed to feel clever.

QT: Write down what you verified. The next release will not remember for you.

Briony: Every link that returns a 404 was a promise someone broke. Do not break promises on the last phase.