Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Release Versioning Specification #29

Open
wants to merge 13 commits into
base: master
Choose a base branch
from
Open

Release Versioning Specification #29

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
981bd4d
Initial commit of first draft
nibra Nov 20, 2021
0f4a648
Elaborate Section 4.3 of the meta document to answer https://github.c…
nibra Nov 21, 2021
b061e48
Add examples based on @HLeithner's contribution
nibra Nov 23, 2021
39ee97a
Reverted rushed replacements
nibra Nov 23, 2021
35cb62d
Small editorial changes in the example code's comments
nibra Nov 23, 2021
86327ae
Extracted examples into its own document
nibra Nov 26, 2021
8abf925
Fix incorrect phrasing in section 3.2
nibra Nov 26, 2021
8d3e359
Fix wrong function name
nibra Nov 26, 2021
f3e60d9
Add @see annotation
nibra Jan 17, 2022
aa12938
Merge remote-tracking branch 'origin/master' into release-versioning
nibra Aug 13, 2022
bd5cd96
Change removal of deprecated code to x+2
nibra Aug 24, 2022
7a13f05
Fix bug in example code
nibra Aug 24, 2022
a03d12d
Editorial changes
nibra Sep 2, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ The sponsor is responsible for managing the review stage and votes.
| N/A | [Simplify Admin Views*][simplify-admin] | Elisa Foltyn <[email protected]> | N/A |
| N/A | [Simplify Admin Views*][simplify-admin2] | Astrid Günther <[email protected]> | N/A |
| N/A | [Composer support][composer] | Astrid Günther <[email protected]> | N/A |
| N/A | [Release Versioning][release-versioning] | Niels Braczek <[email protected]> | Harald Leithner <[email protected]> |

*) Two different proposals on the same target, need to be merged

Expand All @@ -68,3 +69,4 @@ _**Legend:** A = Accepted | D = Draft | P = Pre-Draft | R = Review | X = Depreca
[simplify-admin2]: https://github.com/joomla-x/joomla-standards/pull/7
[composer]: https://github.com/joomla-x/joomla-standards/pull/8
[rfc-procedure]: https://github.com/joomla-x/joomla-standards/blob/master/accepted/RFC-0-rfc-meta.md
[release-versioning]: https://github.com/joomla-x/joomla-Specifications/tree/master/proposed
101 changes: 101 additions & 0 deletions proposed/release-versioning-meta.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
# Release Versioning Meta Document

## 1. Summary

_This Specification describes how versions are numbered in Joomla projects._

This specification aims to help developers, code reviewers and release leads to determine, whether a new piece or a
change of code belongs to the next patch, minor or major release. It will also cover documentation requirements that are
related to versioning.

## 2. Why Bother?

Sometimes it is hard to tell bug fixes and features apart. The Release Leads want a comprehensive set of rules to be
able to make good and fast decisions about the target release of a contribution.

## 3. Scope

The specification applies to all Joomla projects, e.g., the CMS, the Framework, core extensions, ...

## 4. Considerations

### 4.1 Semantic Versioning

Joomla started to follow [Semantic Versioning](Semver) with release 3.3 in April 2014. The rules were not always
followed strictly ([Issue#16874](16874), [Issue#17583](17583), [Issue#24728](24728) to name a few). This need to change,
because the Joomla ecosystem is heavily depending on reliable information about compatibility. This is done in section 1
of the specification.

[Semver]: https://github.com/semver/semver/blob/master/semver.md

[24728]: https://issues.joomla.org/tracker/joomla-cms/24728

[17583]: https://github.com/joomla/joomla-cms/issues/17583

[16874]: https://github.com/joomla/joomla-cms/issues/16874

### 4.2 API

The main problem with Semantic Versioning seems to be to categorise code contributions as bug fixes or features. This
should be easy enough, as the Semantic Versioning specification is quite clear in that regard. Strongly simplified, it
says: Changes that do not change signatures of functions or methods of the public API and do not add new ones can go
into a patch release.

Unfortunately, Joomla has no official definition of "public API". Section 2 of the specification makes up for the
omission. It describes, how public and internal API are told apart using the `@api` and `@internal` annotations as
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will lead to very few parts of the Joomla CMS being considered a public API. For example, in a discussion of an issue of mine I was told that all plugins are internal. Someone could say that the same applies to all of the core components. In this case 3PDs are expected to have their code break at any given time because they cannot depend on the behavior or the code of anything belonging to core being the same even between patch releases. This mathematically leads to all 3PDs needing to reinvent the wheel.

For example, if I cannot trust com_users to work the same way throughout, say, the 4.x versions then my social login extension and my e–commerce extension are NOT going to go through its models to create users, they are going to be creating database entries directly. This of course means that no events are going to be called with unpredictable results. The alternative is to have my code randomly breaking in patch releases.

Before you start adding tags to code you need to sit down and think REALLY HARD how Joomla is used IN THE REAL WORLD and which parts of it are de facto public APIs. I would posit that every core component model's public methods are a de facto public API.

Further to that, the database schema is a de facto public API. Same goes for core JavaScript.

Just focusing on adding tags to PHP code will be very rightly be seen as a preposterous attempt of the project to deflect responsibility for its breaking changes back to third party developers i.e. victim blaming of the worst kind.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's what I actually want to tackle with this RFC.

As sad the moment we have near zero b/c coverage for the php code (except the library folder).

and actually it's a thing of adding api and internal tag to the functions but not blindly. Instead it have to be well thought as you said. Also triggers should be part of the b/c promise because they actually the only direct way joomla interact with 3rd party extensions...

That said we already do all this and try not to break anything but it's written nowhere which makes it hard to say "the reason this feature request is rejected or deferred because of policy xy".

If you use a extension model with set state it's not guaranteed that the name of the state you set is still the same in the next bugfix release.

The Database structure is not and shouldn't be part of the public api also because of the reasons you already mentioned (events). If something can't be done thru our php api then it should be talked about it why this is the case and if should allow it. But allowing to change the data directly doesn't sound like a good idea.

The JS code is already in the b/c policy which is a bit strange for some code.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was told that all plugins are internal. Someone could say that the same applies to all of the core components.

That's absolutely not intended. Thank you for identifying the definition gap!, I'll update the spec accordingly.

Further to that, the database schema is a de facto public API.

Here we disagree. The model is the accessor for the underlying persistence layer and should never be bypassed.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nibra It would appear that you have never written ANY extension for Joomla and it shows.

I have a ticket component. Tickets are submitted by users. I am storing the user ID with the ticket like a good developer.

How am I supposed to search for a ticket given a partial username or email address if I cannot trust the schema to remain stable within the same major version of Joomla? If I have to first use a model method, the first problem is that this method might not exist. If it exists, it might return a number of results that does not fit in memory. Even if it does, it might be so big that using it in a whereIn query makes the resulting query longer than the MySQL max packet size. All these cause my component to be super slow and/or throw fatal errors. These are OBVIOUS issues to anyone who has built a mass distributed extension. Your lack of experience is telling here.

Another thing is, we create extensions which extend Joomla, it's in the bloody name. If I cannot trust Joomla to have a stable schema how can I do this? If I cannot trust that user IDs will be BIGINT how can I write ANY kind of extension which supports more than one user on the site? I wouldn't know what to store in the bloody database table of mine!

If I can't trust Joomla to have an asset ID for each article, something which is a BIGINT, how can I write a comment extension?

If I can't trust Joomla to store fields in a table, how can I build an extension which searches through the fields given the fact that you do not give me a feature to do that?

If I can't trust Joomla to store extensions a specific way in the database how can I write code which works around Joomla's bugs that the Joomla project refuses to even acknowledge, let alone fix?

OF COURSE THE SCHEMA IS A PUBLIC API, FOR CRYING OUT LOUD!!! If you consider the schema to NOT be a public API then 3PDs cannot trust Joomla for ANYTHING AT ALL, WHATSOEVER! We would have to implement a CMS from scratch and our extensions would only work with it. If that's the case why use Joomla and not build an entire CMS from scratch, one we can control so we don't have to put up with idiotic maxims like this?

Before you implement anything in the Joomla project talk to the people who build sites and mass distributed extensions. If you remove from Joomla what makes it useful — the ability to extend it in ways you cannot have possibly imagined — you will be creating the world's most useless CMS.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No need to get personal. Let's stick to the subject at hand.

Before you implement anything in the Joomla project talk to the people who build sites and mass distributed extensions.

That's exactly, what we're doing here. I will think about your (legitimate) questions and then answer them accordingly. Unfortunately - despite my not inconsiderable experience - this is not something I can just pull out of my sleeve.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry about that, it's been a VERY long day.

I am going to insist that the database schema needs to be treated as a public API throughout a major version of Joomla. Otherwise it is impractical for 3PDs. Without 3PDs you don't have Joomla.

Let me give you examples from my own experience, since I am 90% done converting all of my software to Joomla 4 native API and nobody can accuse me anymore that I am not using core features.

The example I gave previously from the ticket system is something I was implementing just a month ago. I need to display a list of tickets. This list has to be produced fast. Each ticket has two user IDs stored: created_by (who submitted it) and modified_by (who last replied to it). By default, I am displaying 20 tickets per page. Therefore I need to display information about 40 user record entries.

If I use the Joomla API (user factory) I get 41 queries to the database. In most cases the last replying user is one of a handful of people (let's say 2 people) or the same as the user who created the ticket. If I implement a caching user factory in my own code I now need 23 queries. This is still pretty darn slow. If I instead use a LEFT JOIN with he users table I can shave off 40% of the load time of the component page. I am making one query against indexed columns. For this optimization to work I need to know that the schema is going to be stable. If you cannot guarantee that I am back to slow queries and now my Joomla site is no better than a WordPress site. Since the tickets visible to any given user other than Guest may be different than every other user's rendering of that page I can't even use caching.

Besides, if I cannot trust Joomla to have a stable schema throughout a major release what exactly am I storing in the created_by and modified_by columns?! If I cannot trust this to be an integer I will have to save it as a MEDIUMTEXT which will give me enough leeway for whatever you decide to use as the user identifier. However, this column can no longer be indexed and ordered efficiently. Combined with the previous problem my tickets page now goes from 150msec rendering time to over two seconds.

The more you think about it the more you see it's an exercise in absurdity.

The schema MUST be treated as a public throughout a major release. That is to say, you can add to it or do backwards compatible changes to it but you cannot remove anything or rename / change things in a way that causes a b/c break. If you cannot guarantee that then just put a big notice "JOOMLA IS UNSTABLE AND ANYONE USING IT WILL HAVE A BROKEN SITE SEVERAL TIMES A YEAR" and call it a day instead of writing rules and regulations.

You are wrong in saying that the only canonical way to access the data is through the Model. The Models in Joomla are tied to the extreme at the specific features implemented in core components, without any leeway for anything beyond that. I want to create a new user and have Joomla send out notification emails as configured. Do you think that's possible with the current Model? IT. IS. NOT!!! I kid you not!

One of my ticket system features is guest tickets. You are a guest user, you file a ticket, a new user account is created for you. I wanted to use Joomla's model. Joomla's model is, however, tied to the features of com_users and even commits the cardinal sin of looking at the request parameters! YIKES! I had to use Reflection and waste 3 hours working around its limitations to beat it into submission. If I had foregone the core Model I would have been done in a hour but someone out there, especially a certain someone from your country, would be loudly complaining that I am not using the core and ask for my head on a silver platter. You feeling me here? Good.

For reasons like these, to me as a 3PD and someone building sites this RFC seems like a massive leap backwards. Instead of making Joomla more stable, at least through the course of a major version, and defining a sensible way to offer a bridge between two successive major versions this RFC is preoccupied with how to best make most of Joomla unstable by default and pass the buck to the 3PDs and users. Well, 3PDs and users will abandon Joomla in that case.

The simple points you need to address are:

  • The schema needs to be stable throughout a major version.
  • The public API needs to be stable throughout a major version.
  • What is the public API? If it's different than all public methods in classes not marked as @internal, what is the deprecation plan and how are you going to consult with the 3PDs instead of making a unilateral decision?
  • Deprecations must be documented well in advance, along with what is the alternative or whether the feature is going to die completely dropped
  • How to create a Migration Notice document (like PHP does) for each minor and major version
  • Most importantly: there will ALWAYS be a case where you need to violate these rules — typically because of a security fix, as it's happened several times in the past. Who has the final say on that and what it the communication plan to 3PDs and users well in advance of that change?

This is 80% about transparent decision making and good communication and 20% about technical implementation. You only focus on the technical implementation. It's not wrong, it's just not actually solving anything. Most of the technical implementation has been long standardized in PHP and to a certain extent it's already used in Joomla. The decision making and communication has remained as problematic as it's been 16 years ago.

proposed by the draft [PSR19][]. It is recommended to add these annotations to existing code. For new code they are
required.

[PSR19]: https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc-tags.md

### 4.3 Deprecations

The core contributors have not been very cautious about deprecations in the past.
nibra marked this conversation as resolved.
Show resolved Hide resolved
`JObject`, for example, has
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a bad example. Because this is an example of a class we're phasing out without replacement (it was mainly about PHP4 workarounds at the time). But due to huge dependency tree was always going to be slow.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it is a perfect example, We're trying to phase it out without (obviously) being able to do it. So it should remain, until we get rid of its usages. If that's not possible, it is just a proof that we can't deprecate the class.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thats where we disagree. It should be marked deprecated because we know today that it will be replaced with something else in the next major release. Under your rules it cant be marked as deprecated until the replacement code is available and in use. meaning that instead of giving developers advanced notice as soon as possible you are delaying that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this case deprecation doesn't mean replacement. JObject should just be removed (since we didn't it proper enough it's now called CMSObject which I think is really impressive that we can rename something but can't remove it^^).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It was not possible to remove JObject in Joomla 4. Instead, with the new rules, it could be declared as 'internal' along with a phase-out-deprecation as part of the public API. That would be a clean way to handle this. Having a public class in 4.1 which will get removed in 4.0 does by no means make any sense to me.

Copy link
Member Author

@nibra nibra Nov 26, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We're not talking about removal here - replacement code is needed for replacements only. Removal of code is tackled in section 3.2 and offers exactly the information that you need, as soon as possible.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nibra What? Are you responding to the replies I am sending or the replies you THINK I am sending?

Let me phrase it differently.

What every single 3PD is interested in is the following:

  • WHEN is this gonna change? REQUIRED.
  • HOW is this gonna change? REQUIRED.
  • WHAT am I supposed to do when it changes? SEMI–REQUIRED.
  • WHY is it even changing? OPTIONAL.

WHEN is necessary for us to plan our releases. If we are caught by surprise because an unannounced and ill–communicated (if AT ALL communicated) change in Joomla broke something we have to waste our time telling our clients that Joomla broke something YET AGAIN which means that we have even LESS time to fix it. That's the number one reason people leave Joomla and the number one DEVELOPERS leave Joomla. There are developers who literally started working in fintech because the pressure is lower than building Joomla extensions...

HOW is necessary for us to start figuring out what to do. If it's going to be removed we're SOL and left to figure it out on our own. If it's replaced with something else what is it and how are we supposed to use it? Is it a drop–in replacement or do we hav to invent something?

WHAT is linked to the item above. If you have a replacement we'd like to know how it's supposed to be used instead of letting us figure it out on our own, possibly making wrong inferences / assumptions.

WHY is optional but it provides context. Context is great in case the change you did result in a feature we provided being removed. It's far better for us to tell our clients “We removed X because Joomla removed Y due to security concerns, here is the TL;DR version of why this makes sense” than telling our clients “We removed X because Joomla removed Y for no good reason”. The former builds trust to Joomla. The latter breaks trust to Joomla.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@nikosdion We are all on the same site and has more or less the main points covered as you wrote in your last comment

https://github.com/joomla/rfc/blob/8d3e35940c41c14ae5ebdd3eac97f769cc07c7d2/proposed/release-versioning.md#32-phasing-out-features

The DocBlock MUST be annotated to document the future removal of the deprecated element. The deprecation annotation SHOULD be supplemented by a recommendation for an alternative. Example:
/**
 * ...
 * @deprecated X.Y  Will be removed in X+1.0 without replacement.
 *                  Please consider using <solution A> or <solution B> instead.
 */
with X.Y being the minor version introducing the deprecation.

WHEN is this gonna change? REQUIRED.

Version X.Y

HOW is this gonna change? REQUIRED.
WHAT am I supposed to do when it changes? SEMI–REQUIRED.

Please consider using or instead.

WHY is it even changing? OPTIONAL.

The official documentation MUST be updated to let users know about the change.

Maybe you don't see the difference but Niels split the "deprecation with replacement" and the "deprecation without replacement".

In case of phasing out a feature it's more important why we do it, normally we would have a really good reason for this like incompatible with the future of php or joomla or the web.

So yes the point 3.2 should be extended with more information for the developer. But the main needs are already in it, "how to replace or what to use instead" (if possible).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like we're on the same page ;)

WHEN is this gonna change? REQUIRED.

Covered by section 3.1 and 3.2 as required

HOW is this gonna change? REQUIRED.

Covered by section 3.1 and 3.2 as required

WHAT am I supposed to do when it changes? SEMI–REQUIRED.

Covered by section 3.1 (required) and 3.2 (optional)

WHY is it even changing? OPTIONAL.

This first and foremost belongs to the PR introducing the change, where it IMO is mandatory. But I fully agree, that we can and must do more on the documentation part outside the code.

Off Topic:

There are developers who literally started working in fintech because the pressure is lower than building Joomla extensions...

I currently make my living developing FinTech applications as Joomla extensions. Not because the pressure is lower (it is actually quite high), but the revenue is much higher.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@HLeithner Yes, I was confused there. I thought section 3.2 and 3.1 applied together. Thank you for pointing out they are meant to be mutually exclusive. Now it all makes sense in my head!

@nibra Thank you!

Just to clarify about the “why did this change”. I would link to the PR in the @deprecated comment. I would also make sure that the opening comment (the PR body text at the top of the page) is updated by the maintainers upon RTC or merge — that's something up to you guys to decide — to make sure we have the When, How, What and Why.

Now, you'll tell me, why not use Git blame? I am currently doing that and it's really hard to follow this sometimes. The PR replaces another PR which solves an issue which references two other issues. Each one has 20–100 comments. Some important points are also code line comments which are easy to miss. Falling into this rabbit hole wastes half of my day and I am frequently none the wiser as to WHY it was ultimately decided to be done the way it's done and WHAT I am supposed to do instead. In fact, it's so convoluted I am usually better off following the code with XDebug which is not something we should reasonably expect 3PDs to have to do to make sense of Joomla — it's bad developer experience.

Making sure there is a link in the deprecated DocBlock annotation and that the PR tells us everything we need is a low effort way of solving that.

Even better, this allows creating meaningful changelogs (Joomla already links to the PRs in the online changelog so it's halfway there) and migration guides, the latter by tagging PRs as “Architectural Change” and collating each of these PRs' b/c break section into a nice, clean document published once every minor version.

I won't claim to have invented this method. This is pretty much what the PHP project does :)

been [deprecated for Joomla 3.4](https://github.com/joomla/joomla-cms/issues/6125#issuecomment-75035212), but made it
into Joomla 4 (although renamed to CMSObject) with the deprecation annotation still in place. Section 3 describes how to
handle and document deprecations. Among other things, it stipulates that a replacement must be offered and used, if the
deprecation is not phasing out a feature. The documentation requirements make sure that legacy code can easily be
adopted to the new implementation.

### 4.4 User Interface

From a code point of view, improvements of the user interface do not touch the API and thus are not features in the
sense of Semantic Versioning. Template files, however, work like functions, since they rely on injected variables to
produce the output. This interface between a View and a template is a contract and as such underlies the rules of
Semantic Versioning. Section 4 provides the rules for dealing with user interface changes.

### 4.5 External Dependencies

Section 5 deals with external dependencies, a.k.a. libraries. The implementation details of external dependencies are not under the control of the Joomla project. Therefore, the code
of these dependencies is basically internal and does not fall under Semantic Versioning. As a result, these dependencies
can be updated or even exchanged without breaking the compatibility promise. As soon as an external API officially becomes part of the
public API, as in the case of Bootstrap, the rules of Semantic Versioning do apply.

## 5. People

### 5.1 Editor(s)

* Niels Braczek <[email protected]>

### 5.2 Sponsors

* Harald Leithner <[email protected]>

### 5.3 Contributors

* N/A

## 6. Votes

* **Entrance Vote:** 2021-11-16 Production Team Leaders
* **Acceptance Vote:** _(not yet taken)_

## 7. Relevant Links

_**Note:** Order descending chronologically._
* [Semantic Versioning Specification](Semver)

## 8. Errata

...
116 changes: 116 additions & 0 deletions proposed/release-versioning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,116 @@
# Release Versioning

This specification describes how versions are numbered in Joomla projects. It also defines documentation requirements
related to versioning.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119][].

[RFC 2119]: https://www.rfc-editor.org/rfc/rfc2119.html

### Definitions

* "Structural Element" is a collection of Programming Constructs which MAY be preceded by a DocBlock. The collection
contains the following constructs:
* class
* interface
* trait
* function (including methods)
* property
* constant
* variables, both local and global scope.

### References

- [RFC 2119][]: Key words for use in RFCs to Indicate Requirement Levels

## Specification

### 1 Semantic Versioning

1. All releases in all Joomla projects MUST strictly follow the [Semantic Versioning](Semver) specification in its
current version.

[Semver]: https://github.com/semver/semver/blob/master/semver.md

### 2 API

Because Semantic Versioning applies to public API only, a distinction between public and internal API is needed.

#### 2.1 Public API

"Public API" describes the sum of structural elements that MAY be used by extension developers.

1. Changes to the public API are subject to the rules of semantic versioning.
2. In order to distinguish these elements from the internal elements, the following applies:
1. Existing public structural elements SHOULD be annotated with `@api` in the corresponding DocBlock.
1. Newly introduced public structural elements MUST be annotated with `@api` in the corresponding DocBlock.
2. Public structural elements MUST be included in the official documentation.

#### 2.2 Internal API

The "Internal API" comprises the structural elements that are supportive for the core and SHOULD NOT be used by
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you give an example

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For example Registry::toFlatten(), which is used by Registry::flatten(). Extension developers (or developers using the Framework) should not use Registry::toFlatten() directly. At least in the Framework there are a couple of such things. Being able to flag them as internal would make maintenance a lot easier.

extension developers.

1. Changes to the internal API are not subject to the rules of semantic versioning.
2. In order to distinguish these elements from the public elements, the following applies:
1. Existing internal structural elements SHOULD be annotated with `@internal` in the corresponding DocBlock.
1. Newly introduced structural elements MUST be annotated with `@internal` in the corresponding DocBlock.
2. Structural elements with the access modifier `private` and structural elements in final classes with the access
modifier `protected` MUST be treated as internal.
3. Internal structural elements MUST NOT be included in the official documentation. All documentation needed by core
developers SHOULD be available in the corresponding DocBlock.

### 3 Deprecations

Deprecating existing functionality is a normal part of software development and is often required to make forward
progress. There are two reasons to deprecate code: (1) architectural changes or (2) removal of features. This section
applies to public API only.

#### 3.1 Architectural Changes

1. The official documentation MUST be updated to let users know about the change.
1. The DocBlock MUST be annotated to document the replacement for the deprecated element. The deprecation annotation
SHOULD be supplemented by a usage example for the replacement. Example:
```php
/**
* ...
* @deprecated X.Y Will be removed in X+1.0. Use <replacement> instead.
* Before (version < X.Y):
* <sample code with deprecated element>
* After (version >= X.Y):
* <sample code using the replacement>
*/
```
with X.Y being the minor version introducing the deprecation.
2. A new minor release MUST be issued with the deprecation in place. That release MUST NOT use the deprecated code
anywhere.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That release MUST NOT use the deprecated code anywhere.

Why?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My understanding of this is as follows

Before this RFC

  1. 1.0 released
  2. amazing new functionality appears that we want to use in J to replace current functionality but it will break b/c
  3. at this point we mark the existing code as deprecated to be removed in 2.0
  4. 1.1 released with the deprecation notices
  5. 2.0 is developed in parallel not using the deprecated code and instead using the new stuff
  6. 2.0 is released replacing 1.1

After this RFC

  1. 1.0 released
  2. amazing new functionality appears that we want to use in J to replace current functionality but it will break b/c
  3. we cant just mark the code as deprecated because we are not allowed to use that code and we cant use the new code because its not written

Now we are stuck. We cant notify people in advance of a deprecation before replacement code is ready and used.
But if that replacement code requires a B/C break (perhaps something different such as php99) then it can never be released and as you cant release 1.1 with a deprecation notice while still using the deprecated code. Confused yet? Which comes first the chicken or the egg.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we cant just mark the code as deprecated because we are not allowed to use that code and we cant use the new code because its not written

Exactly, that's intended. Deprecation can take place, when the alternative code exists. It is meaningless to deprecate code, if it still is needed. In your example, the new code has to be present in 1.1

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry but that makes no sense in the real world. Here is a scenario

php version 9 introduces a new feature called gimble
gimble offers some great new ability that will enable us to rewrite jbanana with a lot less code and perform faster.
We cannot use gimble until the next major release due to the php version 9 requirement but we know that we will be replacing jbanana with gimble. In fact development on the rewrite has already started in the j5 branch.

With this rule we cannot mark jbanana as deprecated until J5.0 when gimble is released. Whereas we should be giving everyone advance notice as soon as it is possible.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Assuming that jbanana is a Joomla feature, it should not change its signature, if it is going to use gimble behind the scenes. If jbanana is a PHP feature that will be replaced by gimble, the signature of the Joomla code using jbanana should not change, when it is rewritten for gimble.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @HLeithner for the code examples! With your permission, I will include them in the meta-document with the appropriate annotations.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure @nibra but I wouldn't add it to the meta document, I would create a new document "appendix" or "examples". Because I would expect we will have a bunch of examples at some point.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  1. Unlikely to be an outcry because that is the current behaviour
  2. The replacement can be shown in the 13.0 development

You're thinking too high level. It might be appropriate for a single library but not for the cms

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't add it to the meta document, I would create a new document "appendix" or "examples". Because I would expect we will have a bunch of examples at some point.

I put into meta document for now; we can separate the examples later on. For the current discussions, I think having two documents (the sepc and the meta) is challenging enough ;)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You're thinking too high level. It might be appropriate for a single library but not for the cms

Well, for extension developers, the CMS IS a library. And we've seen a couple of times, that 3PD start late on adapting their code to CMS changes. The fact that not providing a transition phase "is the current behaviour" should not encourage us to continue behaving that way.

3. The deprecated code MUST be removed in the next major release.

#### 3.2 Phasing out Features

1. The official documentation MUST be updated to let users know about the change.
1. The DocBlock MUST be annotated to document the replacement for the deprecated element. The deprecation annotation
SHOULD be supplemented by a recommendation for an alternative. Example:
```php
/**
* ...
* @deprecated X.Y Will be removed in X+1.0 without replacement.
* Please consider using <solution A> or <solution B> instead.
*/
```
with X.Y being the minor version introducing the deprecation.
2. A new minor release MUST be issued with the deprecation in place. That release MUST NOT use the deprecated code
anywhere.
3. The deprecated code MUST be removed in the next major release.

### 4 User Interface

1. Changes to the user interface are considered compatible if they do not affect the public API.
2. If variables passed to or required by template files change, it MUST be treated as a change of the public API.

### 5 External Dependencies

1. Updating external dependencies is considered compatible since it does not affect the public API.
2. The API of the dependencies is not part of the project's API, unless explicitly stated in the official documentation.
3. Extension developers MUST NOT rely on the presence of dependencies that are not covered in the official documentation.