Enable more version of the docs

[Coffee2CodeNL]

This is:

- [ ] a bug report
- [X] a feature request
- [ ] **not** a usage question (ask them on https://stackoverflow.com/questions/tagged/phpspreadsheet or https://gitter.im/PHPOffice/PhpSpreadsheet)

What is the expected behavior?

Have docs for all tags in this repo

What is the current behavior?

There's only docs available for master, latest and stable

Could solve it by enabling the SemVer matcher: https://docs.readthedocs.io/en/stable/guides/automation-rules.html

[PowerKiKi]

@oleibman, @MarkBaker , I don't think PhpSpreadsheet should have so many maintained branches. As of now, there is 3.x, 4.x and 5.x. IMHO it only increase maintenance burden, and it is harder for users to know what is supported or not. What is the point to have so many of them when 5.x still support PHP 8.1 ?

I think we should go back to a single, maintained, version. WDYT ?

PS: branch names would also be clearer if named like something like 2.x, 3.x, 4.x, as seen for example in Angular repo

[oleibman]

The maintained branches came about because of the security patches which were applied. In particular, when the first one hit (not sure, but let's say it was for 2.3.0), there was a lot of pressure to add the patch for 1.29 (because of Laravel, which is how a lot of our users get to us). And then for 2.1 (because RedHat comes with Php8.0 and a promise to apply security updates for that version).

Release 3 was a breaking change (dynamic arrays). Since we claim to adhere to "semantic versioning", a new release is required for breaking changes.

Release 4 was many breaking changes (data validations, conditional formatting, many others).

Release 5 was totally frustrating. "SSRF when reading and displaying a processed HTML document in the browser." This was completely contradictory with an earlier advisory "Absolute path traversal and Server-Side Request Forgery in HTML writer when embedding images is enabled." I requested help with that, and, with none forthcoming, dealt with that in the only way I could think of, with a breaking change. The only good news here is that all of release 4 became unsupported because they all had a security vulnerability.

At this point, we had 5 supported branches - release1291, release210, release222, release390, and master. I have made only a handful of changes to any of them, except for security patches.

I made a breakthrough recently by helping Laravel get to a point where they could support our current release SpartnerNL/Laravel-Excel#4302 They have merged, but not yet released, that change.

Php8.5 has been quite problematic for us. Many changes were, of course, needed because of the deprecation of the increment operator for strings, which we use for looping through columns all over the place. With Laravel more-or-less taken care of, I did not apply any of those changes to the release129 branch, and I just tagged a new release for it stating explicitly "no more changes except for security". In addition, since release210 exists solely because of a need to support 8.0, I saw no reason to make it 8.5-compatible, and tagged a new release for it also stating "no more changes except for security".

So, at the moment, our supported releases are release222, release390, and master. I do intend to have a new release for each after 8.5 is official. However, I am neutral about whether we need to support them beyond that. Perhaps there are users who don't want dynamic arrays or the other breaking changes. If so, perhaps we shouldn't care about them. I know that we do get a fair number of issues from people using the older versions, and I am not sure one way or another whether "you need to upgrade" is a valid solution - easy for us to say, not necessarily so easy for them to do. I have no problem including in the upcoming release notes that we will only support the older branches until a specified date, or until Php moves beyond 8.5.

[PowerKiKi]

I mean ultimately it is up to you, because you are doing all the work for it. I am just saying not to overwork yourself for that. We don't need solve all users' issues. Eg, if they are not willing to (or can't) upgrade, maybe we don't to go the extra mile for that, or at least not every time.

For the time being we should make it clearer which branch is maintained. I guess a section in the README of master branch giving a short list of maintained branch would be enough. Then we should rename existing branch to be easier to understand. Eg, instead of release390, what about 3.x, because patch and minor version should probably not be in a branch name ?

Finally, I think it would be nice if we can reduce the number of maintained branch to only two. Master of course, and a sort of pseudo "legacy" branch for people who are somehow stuck in the past. I am not sure which version this should be as of now... v2 or v3 ? you probably have a better idea about that than me.

tl;dr: "you need to upgrade" is a perfectly valid solution, IMHO, when we all are volunteers giving away our free time

PS: great news about Laravel ❤️

[oleibman]

Just to document, not to be argumentative. The existing supported branches are currently enumerated in CONTRIBUTING.md. For each unsupported branch, README.md contains a statement "This branch (releasexxxx) is not the latest version of PhpSpreadsheet, and may therefore lack features and bug fixes found in the latest version."; also an additional statement "Security Changes Only. Except for security changes, no further maintenance will be applied to this branch." For each supported branch (except master), "This branch (releasexxx) is maintained (for security and some bug fixes), but it is not the latest version of PhpSpreadsheet, and may therefore lack features and bug fixes found in the latest version.". If you can think of a better location for documenting lack of maintenance, I will be glad to add that. I can certainly add something to master README.md to further document things.

I think I will document in the release notes for release220 that it will not be supported for updates after Php8.6/9.0. It is not as clear that I should do that for release390. I will think about that - it could be the "legacy" which you mention.

I have no problem at all with renaming the branches (except that release210 and release222 will conflict). I do not have your extensive knowledge of github. Is that as easy to do as it seems? I can rename the branch and people can still get to the old tagged versions if they need? I can schedule that for after our post-Php8.5 release (possibly waiting till Laravel completes their merge).

[Coffee2CodeNL]

The discussion currently ongoing in this ticket is not what this ticket is about.

I merely requested to have documentation available for older versions so features that are only supported in the latest release aren't documented for that version.

[oleibman]

@Coffee2CodeNL Understood. We are trying to decide what constitutes "supported", which is why (we think) it is relevant here.

[PowerKiKi]

I was not aware of the differences in the README of respective branches. I guess that might be good enough. Maybe I am anticipating some user confusion that will never actually happen. So instead of doing premature optimisation, let's keep the info as you did, as long as nobody come to us complaining about the situation.

Renaming branches, has no effect on existing tags. So in that regard, yes it is easy. It might have an impact if somebody explicitly depend on a specific branch in his composer.json (eg: "phpoffice/phpspreadsheet": "dev-release222"), then he would never receive the future commits what would only exist on the new branch name. My opinion is that we can ignore that use-case, because depending on a branch name (and thus on a specific commit, instead of a tagged release), is not the recommended way to use composer in production projects. It's a bit of a "power user" use-case. But if we you prefer to be extra cautious we can keep both branch names in parallel, pointing at the same commit. So release222 would be a synonym of 2.x. And when the time comes to branch for 5.x, we would only create a single branch 5.x, without synonyms.

As for the specific naming pattern, the only thing I would recommend is to replace the smallest version number (either the patch or minor version) with a x, and to void the term "release" which might incorrectly suggest a tagged release. We can look at Doctrine in the PHP ecosystem for inspiration: https://github.com/doctrine/orm/branches. It is similar to the Angular way I mentioned, but they chose to have a branch for each minor version, like you did for release210 and release222. Like I said earlier I hope, for your sake, that a branch per major version is enough, so we could go with 2.x, 3.x. But if you feel it's safer/better to have a branch for minor version, we can totally go with 2.1.x, 2.2.x, 3.9.x. I'll let you decide the granularity of branch.

[PowerKiKi]

@Coffee2CodeNL docs for maintained versions are now available via https://phpspreadsheet.readthedocs.io:

If you need docs for un-maintained versions, then I recommend cloning this repository to read the doc source for the exact version you need.

[oleibman]

@PowerKiKi PhpSpreadsheet branches are now renamed.