[Testing] Broken links to PHPUnit "stable" documentation

[MrYamous]

Hi,

PHPUnit doesn't seem to use links based on phpunit.readthedocs.io/en/stable anymore, which cause several broken links on this page (and maybe others). For example, the link under "Writing Tests for PHPUnit" on this part is broken.

Documentation now use version-based link, for my precedent example https://phpunit.readthedocs.io/en/9.5/writing-tests-for-phpunit.html is working, but it seems more difficult to maintain if links must be edited for each new version.

I can work on a PR for it, but do you think we should use links mentioning explicitly the PHPUnit's version or rather remove links that go to a specific page and only link to index to avoid managing this ? Or any other solution I haven't thought off ?

[mdoutreluingne]

I think that here the best solution would be to remove all the links which refer to a page of the PHPUnit documentation in order to replace them with the home page of the documentation (which automatically chooses the latest version of PHPUnit) for reasons of maintainability.

e.g

- You can learn about it in the PHPUnit documentation: `Writing Tests for PHPUnit`_.
+ You can learn about it in the `documentation`_.

...

.. _`documentation`: https://phpunit.readthedocs.io/
- .. _`Writing Tests for PHPUnit`: https://phpunit.readthedocs.io/en/stable/writing-tests-for-phpunit.html

What do you think?

[javiereguiluz]

I've checked and we have LOTS of links to deep PhpUnit doc pages. Some are broken, others point to outdated doc pages, etc.

Fixing this (and keeping it fixed) requires a significant maintenance effort. Maybe we should remove all links and just mention the name of the PHPUnit feature and show a generic link to the main doc page?

Ping @symfony/team-symfony-docs

[wouterj]

Hmm, I only find 11 links to the PHPunit documentation (and 8 more links that link to the homepage of the docs or PHPunit project). I wouldn't call this a lot...

There are indeed some URLs pointing to old versions of the documentation (mostly in the PHPUnitBridge docs). All other links are working, apart from the stable version to no longer work (changing "stable" to "9.5" generates all valid URLs pointing to the correct sections).

I don't think we should degrade the reader experience by changing all links to be generic in this case. Even more, I don't see a valid reason to make this decision for PHPunit but still keep precise php.net and Composer URLs.

[wouterj]

@sebastianbergmann the "stable" URLs were a great way to have links that remain up to date. I see this version no longer exists on readthedocs. Is this an intended change? If it is, would it create problems to reintroduce a URL that remains up to date that we can use to reference the PHPUnit docs?

[sebastianbergmann]

This was an intentional change.

Before https://github.com/sebastianbergmann/phpunit-documentation-english/issues/261, I was not even aware that this "branch" of the documentation was available. The |version| placeholder is used in a couple of places in the documentation's sources. When it is replaced with stable, for instance, this leads to confusing and/or wrong output.

I think you should link to https://phpunit.readthedocs.io/ which redirects to the default version.

[MrYamous]

Fixing this (and keeping it fixed) requires a significant maintenance effort. Maybe we should remove all links and just mention the name of the PHPUnit feature and show a generic link to the main doc page?

I don't think we should degrade the reader experience by changing all links to be generic in this case. Even more, I don't see a valid reason to make this decision for PHPunit but still keep precise php.net and Composer URLs.

I agree with both of you, maybe we can try to use versioned links, and change them later if it requires too much effort to keep it up to date?