SQL schema numbering described

[robbiejackson]

Clarification regarding how Joomla processes the SQL update files in particular.

[qodo-code-review]

ⓘ You are approaching your monthly quota for Qodo. Upgrade your plan

Review Summary by Qodo

Document SQL schema numbering and update processing behavior

📝 Documentation

Walkthroughs

Description

• Clarified SQL install/update/uninstall descriptions with improved wording
• Added comprehensive "SQL Schema Numbering" section explaining Joomla's version tracking
• Documented how Joomla processes SQL updates during initial install and upgrades
• Included detailed example showing version progression and schema table updates

Diagram

flowchart LR
  A["Extension Install"] --> B{"SQL files exist?"}
  B -->|No| C["No #__schemas record"]
  B -->|Yes| D["Store highest filename in #__schemas"]
  E["Extension Update"] --> F["Read current version from #__schemas"]
  F --> G["Order update files numerically"]
  G --> H["Execute files after current version"]
  H --> I["Update #__schemas with latest version"]

Loading

File Changes

1. docs/building-extensions/install-update/installation/manifest.md 📝 Documentation +105/-15

Expanded SQL schema numbering documentation with detailed examples

• Improved clarity of Install/Update/Uninstall descriptions with better formatting and wording
• Added new "SQL Schema Numbering" subsection explaining Joomla's dual version tracking system
• Documented initial install behavior where highest numbered SQL file is recorded without execution
• Added "Installing an update" subsection detailing how Joomla processes SQL updates based on schema
 version
• Included comprehensive example showing version progression across multiple installation scenarios
• Clarified distinction between manifest <version> tag and SQL schema version in #__schemas
 table

docs/building-extensions/install-update/installation/manifest.md

---

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

1. Schema example not numeric ✓ Resolved 🐞 Bug ≡ Correctness

Description

The new section says Joomla orders update filenames “numerically”, but the example uses an
alphanumeric filename ("1.0.3a.sql") and claims it becomes the highest schema version, which is
internally inconsistent and can mislead authors into unsafe naming patterns.

Code

docs/building-extensions/install-update/installation/manifest.md[R363-379]

+If there are some SQL update files, then Joomla orders them in numerically increasing order.
+It takes the highest value filename and stores the filename (without the sql extension) in the 
+extension's record in the `#__schemas` table.
+
+Note that on first install of an extension none of the SQL update files are run;
+Joomla just notes the name of the latest update file. 
+
+For example, if there are the following SQL update files present:
+
+```
+1.0.1.sql
+1.0.2.sql
+1.0.3a.sql
+```
+
+then Joomla will order these in numerical order (ie the order they're listed above),
+and will enter "1.0.3a" as the `version_id` within this extension's record in the `#__schemas` table.

Evidence

The doc asserts numeric ordering while demonstrating/endorsing a non-numeric (letter-suffixed)
schema filename and treating it as the latest version. Elsewhere in the repo, SQL update file naming
examples stick to numeric/date formats, increasing the likelihood this example is misleading rather
than a supported convention.

docs/building-extensions/install-update/installation/manifest.md[363-379]
docs/general-concepts/guided-tours/create-whatsnewtour.md[92-99]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The schema ordering explanation says filenames are ordered numerically, but the example uses `1.0.3a.sql` and claims it will be considered the highest version. This contradicts the described rule and may cause developers to choose filenames that won’t sort/compare as they expect.
### Issue Context
This is a documentation contract for extension developers; the example should match the stated ordering rule and reflect the recommended filename format used elsewhere in the docs.
### Fix Focus Areas
- docs/building-extensions/install-update/installation/manifest.md[363-379]
### Suggested change
Either:
- Change the example to purely numeric filenames (e.g., `1.0.3.sql`) if only numeric-style versions are intended, **or**
- Update the text to explicitly define the accepted version string format and how Joomla compares/sorts them (and adjust “numerically” wording accordingly).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Versioned docs now conflict ✓ Resolved 🐞 Bug ⚙ Maintainability

Description

The updated unversioned manifest docs now state update SQL files are not executed on initial
install, but all versioned copies of this page still state Joomla applies update files on first
install; readers switching doc versions will get contradictory guidance.

Code

docs/building-extensions/install-update/installation/manifest.md[R367-368]

+Note that on first install of an extension none of the SQL update files are run;
+Joomla just notes the name of the latest update file. 

Evidence

The PR introduces a new claim about initial install behavior (“none of the SQL update files are
run”), but the same page in versioned documentation (4.4 through 6.1) still states the opposite
(that Joomla applies update files to reach the installed version). This is a direct documentation
inconsistency within the same repository.

docs/building-extensions/install-update/installation/manifest.md[367-368]
versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md[339-343]
versioned_docs/version-5.4/building-extensions/install-update/installation/manifest.md[339-343]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The unversioned page was updated to say schema update SQL files are not run on initial install, but the versioned docs for released versions still say Joomla applies update files on first install. This creates conflicting instructions depending on which doc version a reader opens.
### Issue Context
This repo uses Docusaurus versioning (`docs/` for current, `versioned_docs/` for released versions). If the behavior is the same across versions, the guidance should be consistent; if behavior differs by Joomla version, the docs should explicitly call that out.
### Fix Focus Areas
- docs/building-extensions/install-update/installation/manifest.md[356-418]
- versioned_docs/version-4.4/building-extensions/install-update/installation/manifest.md[334-344]
- versioned_docs/version-5.4/building-extensions/install-update/installation/manifest.md[334-344]
- versioned_docs/version-6.1/building-extensions/install-update/installation/manifest.md[334-344]
### Suggested change
Either:
- Update the versioned pages to match the corrected behavior description, or
- Add a clear version-specific note explaining why the behavior/guidance differs between the current docs and the versioned docs.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[robbiejackson]

@marcorensch - I've included a new section on SQL schema numbering - feel free to comment.

Easiest way to see the text is via the Preview which is generated for this PR - at
https://schema-numbering.manual-bku.pages.dev/docs/next/building-extensions/install-update/installation/manifest/#sql