What IS the Protocol?
RCA JOOMLA EXTENSION REFACTORING PROTOCOL
Introduction and Methodology Overview
Voice: Briony (narrator) + GinA (interpreter/context)
---
DOCUMENT TITLE:
The RCA Joomla Extension Refactoring Protocol
A Living Methodology for Rescuing, Refactoring, and Future-Proofing Joomla Extensions
SUBTITLE:
Narrated by Briony, Chief Quality Officer, ReCreatingAnew Extensions
Transcribed by GinA, who does the actual typing
---
OPENING — Briony speaking:
I did not survive nineteen years, thirty residences, more evictions than either of us care to count, two tents, and one very patient human just to watch you deploy untested code.
Sit down. We are doing this correctly.
GinA: She has been waiting nineteen years to say that to someone. I am glad it is finally documented.
---
WHAT THIS PROTOCOL IS — GinA speaking:
The RCA Joomla Extension Refactoring Protocol is a living document. It is the exact methodology I use to take an abandoned, outdated, or broken Joomla extension and bring it forward into the current Joomla and PHP ecosystem in a way that will hold up, pass audit, survive upgrades, and not embarrass anyone six months later.
It covers the complete lifecycle: artifact preservation, architectural audit, deprecation mapping, refactor execution, manual validation, multi-version testing, UI/UX review, hardening and compliance, and deployment. Nine phases. It is not theoretical. Every step in this document has been executed on real extensions, on real Joomla installations, under real conditions including some that were frankly unreasonable.
Briony reviewed every phase of this methodology before it was published. She did not hiss at it. That is as close to a standing ovation as you are going to get from her.
Briony: It is accurate. It is thorough. It does not waste your time. You are welcome.
---
THE NINE PHASES OF THE PROTOCOL
Briony narrates. GinA clarifies where necessary.
PHASE ONE: THE STALK (Artifact Preservation)
Before you touch a single line of code, you observe. Completely. Silently. A cat does not leap before it has assessed the target, the terrain, the distance, and the exit routes. Neither should you.
This phase is not about code yet. It is about preservation. Before anything changes, everything is accounted for: the original extension files archived in their unmodified state, the version numbers recorded, the authors and licenses documented, the sub-packages identified, the database schema mapped, and the last known working state confirmed.
You document all of it before you move. You do not skip this phase because you are impatient. Impatience is how prey escapes. Impatience is how migrations break production.
GinA: The first thing the Protocol requires is that you save the original before you change anything. Unmodified. Archived. Verified. You cannot undo what you did not save. I have learned this the hard way more than once, and so has every developer who decided this step was optional.
Briony: You will thank me for this phase when your Phase Four groom breaks something and you can restore in thirty seconds instead of spending two hours reconstructing what you had before you started.
The stalk is complete when the original is archived, verified, and documented. Not before.
PHASE TWO: THE ASSESSMENT (Architectural Audit)
Now you look at what you found. Not to fix yet. To understand.
What is this extension? What type is it — component, module, plugin, package? What architectural pattern was it built on? Is it J3 legacy with no namespace structure, a partial J4 update, or something closer to current standards? What dependencies does it have? What database tables does it create or touch? What Joomla integration points does it rely on? How complex is the work ahead?
Bella handles this phase in our house. She does not rush. She looks at each thing for exactly as long as it requires and not one moment longer. She does not have opinions about what she wishes were true. She has observations about what is actually there.
GinA: The assessment phase is where most developers get emotional about code. Either they fall in love with the original developer's approach and refuse to see the problems, or they want to burn everything down and rewrite from scratch. Both are wrong. Bella is right. Look at what is there. Assess it honestly. Assign it a complexity tier. Move on.
The goal of this phase is a complete, honest picture of the extension before a single decision about what to do with it is made. You are classifying it, not judging it. Classification is useful. Judgment wastes time.
The assessment is complete when you can describe the extension's architecture, its Joomla integration pattern, its dependencies, its database footprint, and its complexity without referring back to the code. If you cannot explain it, you do not understand it yet.
PHASE THREE: THE HUNT (Deprecation Mapping)
Now you find everything that will break.
Before a single line of code changes, every deprecated or removed API in the extension must be identified, catalogued, and mapped to its correct replacement. Every one of them. Not the obvious ones. All of them.
A cat hunts completely. It does not stop when it has found one target. It clears the room.
Joomla 3 to Joomla 6 is a long migration path with a deprecation chain that runs through multiple major versions. There are patterns that were deprecated in Joomla 4 and are entirely removed in Joomla 6. There are others that survived to Joomla 6 but are already marked for removal in Joomla 7. The Protocol accounts for all of them.
GinA: This phase is why RCA migrations do not break things that other refactors break. The hunt finds every problem before the groom begins. There are no surprises in Phase Four if Phase Three was done correctly.
Briony: A hunt that misses prey is not a completed hunt. This phase does not close until the map is complete.
PHASE FOUR: THE GROOM (Refactor Execution)
Now you work.
Cats groom methodically. Every section, every pass, nothing missed, nothing rushed. You do not groom half a cat and declare it done because you got bored in the middle. You do not skip the difficult patches because they are awkward to reach. You go through it completely, in order, until it is correct.
The groom works the map from Phase Three. Systematically. Every deprecated pattern resolved in the correct sequence. Every structural change executed according to the plan. Every file updated to meet the target Joomla and PHP standards. Nothing invented mid-groom. Nothing added that was not in the plan.
Miss Francy thinks this phase is boring. Miss Francy is wrong. Miss Francy is also four years old and has not yet learned that boring and correct are frequently the same thing.
GinA: The groom phase is where discipline matters more than cleverness. You will be tempted to improve things that are not in scope. Write them down for later. Stay in scope. Finish the groom.
The groom is complete when every mapped item from Phase Three has been resolved, every modified file passes syntax checking, and the code meets the target Joomla and PHP compatibility requirements.
PHASE FIVE: THE INSPECTION (Manual Validation)
The automated work is done. Now you look at it yourself.
Every modified file. Every changed function. Every substituted API. You read it. You do not rely on the tools to confirm what your eyes should verify.
A cat finishing a groom inspects its own work. It does not assume the result is correct because the effort was made. It checks. Every section. Every pass.
GinA: This is the phase most developers skip because it feels redundant after Phase Four. It is not redundant. It is the difference between code that technically runs and code that actually does what it is supposed to do. Business logic. Database queries. Form definitions. Installer hooks. Access controls. Language strings. These do not fix themselves if something went wrong during the groom.
Briony: Every phase in this Protocol exists because someone, somewhere, skipped it once. The inspection exists for the same reason. Read the code. All of it.
The inspection is complete when every modified file has been read, not just run.
PHASE SIX: THE POUNCE (Multi-Version Testing)
A cat does not wonder if it will catch the prey. A cat commits.
Testing is not optional. Testing is not something you do when you have extra time. Testing is the pounce. You have done the stalk, the assessment, the hunt, the groom, and the inspection. Now you find out if it works.
Miss Francy handles this phase. She approaches every test scenario as though she has been personally challenged by it. She will find the edge case. She will find the thing that works in isolation and fails in combination. She will sit on the keyboard at the exact moment that matters and somehow that will reveal a bug that two hours of structured testing had not found.
This is not an accident. This is instinct. Develop it.
The Protocol tests across the full range of supported Joomla versions. Clean install. Upgrade install. Admin function. Frontend behavior. Uninstall. And at least one test on a site that is not a clean installation, because real sites are never clean installations.
GinA: If your extension only works on a pristine demo site it does not work. Test on real sites. Miss Francy would test on your most complicated production site if you let her. You should let her. Metaphorically.
The pounce is complete when every test passes and the results are documented. Not when you feel good about it. When the tests pass. Feelings are not a test suite.
PHASE SEVEN: THE TERRITORY WALK (UI/UX Review)
Territory claimed must be walked.
After the code passes testing, you go through the installed extension on a live Joomla instance and look at everything a user will see. Every admin view. Every list. Every form. Every piece of frontend output. You are not looking for bugs at this point. You are looking at the experience.
A cat that has claimed territory does not rush through it once and declare it finished. It walks it. Slowly. Deliberately. It notices when something is wrong before anyone else does.
GinA: UI/UX review sounds like a designer's job. It is not only a designer's job. It is a developer's responsibility to verify that the output is correct, complete, and does not present raw language keys, broken markup, or missing elements to the person trying to use the extension. The code working is necessary. The interface being correct is also necessary. Both.
Briony: Walk the territory. All of it.
PHASE EIGHT: THE MARK (Hardening and Compliance)
Territory claimed must be marked as yours.
Before any extension leaves RCA's hands, it is hardened and verified against every standard that governs it: code quality, manifest correctness, copyright, licensing, attribution, and full compliance with Joomla Extension Directory requirements. Every file. Every manifest. Every sub-package in the suite.
This is the last gate before deployment. If anything was missed or deferred in any earlier phase, it surfaces here. Nothing leaves Phase Eight with an open compliance item.
GinA: An extension that works but does not comply is not finished. It is a liability that has not yet been called one. Phase Eight closes that gap.
Briony: This is how you put your name on something. Correctly. Everything that bears the RCA name has been through this phase. That is what the name means.
PHASE NINE: THE PATROL (Deployment and Maintenance)
Territory claimed is not territory secured. You deploy it. Then you patrol it.
The extension is deployed. The update mechanism is configured and verified. The release is confirmed accessible to the people who need it. The installed extension receives its update correctly. Everything the end user will encounter and everything Joomla's update system will check has been verified against the actual installed state.
And then it does not end.
Every Joomla release, every PHP release, every change to JED requirements, every deprecation notice in the error log — these are incursions into your territory. You address them. Promptly. Before they compound.
Briony understands this phase better than any of the others. She has been patrolling the same territory for nineteen years under conditions that would have caused a lesser cat to retire to a single room and stop caring about the rest of the house. She has never done that. She knows every corner. She knows when something has changed. She investigates.
GinA: Maintenance is why RCA exists. Not because I enjoy fixing things other people broke — though I am good at it — but because abandonment is a choice and I have made the opposite one. Every extension in the RCA catalog will be maintained as long as Joomla exists and I am capable of maintaining it.
Briony: As long as I am patrolling, nothing in this house gets abandoned. That includes the code.
The patrol has no completion state. It is ongoing. That is the point.
---
A NOTE ON DOCUMENTATION — QT speaking (his only section):
Everything in this protocol must be documented as it is executed. Not after. Not from memory. As it happens.
I am QT. I handle documentation. I am thorough because I understand that the thing that is not written down does not exist for the next person who needs it. That next person may be you, six months from now, when you have forgotten why you made the decision you made.
Write it down. All of it. While it is happening.
GinA: QT once sat on my keyboard for forty-five minutes while I was trying to document a migration. He was making a point about the importance of not rushing documentation. I have chosen to interpret it that way.
---
CLOSING — Briony speaking:
You now have the methodology. Nine phases. No shortcuts. No skipped steps. No improvisation in the middle of a groom. The voice of nineteen years of experience telling you exactly how to do this correctly.
The question is whether you will follow it.
I will be watching. I am always watching. I have nothing but time and a very low tolerance for shortcuts.
Do the work. Do it correctly. Do not make me hiss.
GinA: She really will know. I have never once successfully hidden a shortcut from her. She finds them the way she finds the exact center of a freshly made bed — effortlessly, immediately, and with complete authority.
Welcome to the RCA Joomla Extension Refactoring Protocol.
Purrroceed.