[FEATURE] Setup: add database update steps guideline.

[thibsy]

Hi folks,

Here's my proposal for the database update steps guideline.

Please let me know what you think about my recommendations, how strictly we want to phrase adherence (currently "SHOULD") and if there are something else missing or wrong in terms of content.

@fwolf-ilias I have added you to verify my sentences about the ILIAS upgrade and release process in general.

@ILIAS-eLearning/technical-board I have added your label, since this PR was created thanks to your funding.

Kind regards,
@thibsy

[fwolf-ilias]

No objections regarding the state of the database in connection with the release update/upgrade.

[chfsx]

LGTM, thanks a lot!

[mjansenDatabay]

Hi @thibsy ,

Thank you a lot for this pull request. This guideline addresses a real gap in our documentation.

Please answer the following questions:


• Should this document replace, supersede, or complement "docs/development/database-updates.md"? The existing doc still recommends il$COMPONENT…Steps naming and classes/Setup placement, while this guideline proposes ILIAS\<Component>\Setup\Database\V<n>\.... Without an explicit relationship, developers/authorities will not know which convention applies.
• For the n+2 removal rule: can you add a concrete worked example? The rule is understandable (for me) in principle, but the n / n+1 / n+2 notation is easy to misread without one.
• How should backports be handled in practice? Chapter 2 explains the branching problem well, but the operational workflow is missing (e.g. same fix in "trunk" and "release_n" → separate "V11" / "V12" classes? hotfix steps like ilHelpDB10HotfixSteps?).

Please consider the following suggestions. You do not need to follow those, but please indicate shortly why you prefer to do otherwise:


• Cross-link to "docs/development/database-updates.md" for operational basics (prepare(), wiring the Agent, getStatusObjective() with ilDatabaseUpdateStepsMetricsCollectedObjective, using only ilDBInterface, grouping via ObjectiveCollection). This guideline focuses on lifecycle and branching, the other document covers day-to-day implementation.
• Add a minimal example for ObjectiveWithPreconditions when one step class depends on another and/or decide, whether to put this bonus tip to "docs/development/database-updates.md".
• Update code examples to match the real interface or point to "docs/development/database-updates.md": every ilDatabaseUpdateSteps implementation must implement prepare(\ilDBInterface $db): void; . The Agent examples should include getStatusObjective() where applicable.
• Add an explicit warning that renaming or moving an ilDatabaseUpdateSteps class changes its FQDN and causes the setup to treat all steps as new, with potentially dangerous re-execution on existing installations when there is no "guard" code in place.
• Clarify the relationship to the legacy naming still prevalent in the codebase and whether version namespaces are the target state for new code only.
  

Best regards,
Michael

on behalf of the Technical Board

[mjansenDatabay]

Suggested change

	**It is therecore important that the FQDN of an implementation MUST NOT change.** Otherwise update steps are considered
	**It is therefore important that the FQDN of an implementation MUST NOT change.** Otherwise update steps are considered

[mjansenDatabay]

Suggested change

	This guide will refer to database updates as schmea updates (DDL), but it possibly applies to other operations (DML,
	This guide will refer to database updates as schema updates (DDL), but it possibly applies to other operations (DML,

[mjansenDatabay]

Suggested change

	To implement this consistently accross all ILIAS components and prevent possibly divergent database update steps,
	To implement this consistently across all ILIAS components and prevent possibly divergent database update steps,

[mjansenDatabay]

Suggested change

	class AgenfOfX implements \ILIAS\Setup\Agent
	class AgentOfX implements \ILIAS\Setup\Agent

[mjansenDatabay]

Suggested change

	class AgenfOfX implements \ILIAS\Setup\Agent
	class AgentOfX implements \ILIAS\Setup\Agent

[mjansenDatabay]

This has to be 2.1, not 2.2.

[mjansenDatabay]

And again "3.2" ;-)