Created attachment 4866 [details] Photo of bad version The current docs are generated with version 4.0.999. Which means the DISTRO value is 4.0.999 When the DISTRO macro is used in URL path for download, it mismatch and creates broken link. for example: https://downloads.yoctoproject.org/releases/yocto/yocto-4.0.999/ vs. https://downloads.yoctoproject.org/releases/yocto/yocto-4.0/
c.f. https://wiki.yoctoproject.org/wiki/Documentation_Review#Outdated_migration.2Frelease_manuals for context on why we did it this way (for default landing page, and also branch docs (e.g. docs.yoctoproject.org/dunfell)). There is an additional thing that can be done is to have DISTRO_VERSION in poky.yaml set to the latest known tag of the branch (e.g. dunfell branch would set DISTRO_VERSION=3.1.16 right now), this should probably fix most of the link issues?
(In reply to comment #1) > c.f. > https://wiki.yoctoproject.org/wiki/Documentation_Review#Outdated_migration. > 2Frelease_manuals for context on why we did it this way (for default landing > page, and also branch docs (e.g. docs.yoctoproject.org/dunfell)). > > There is an additional thing that can be done is to have DISTRO_VERSION in > poky.yaml set to the latest known tag of the branch (e.g. dunfell branch > would set DISTRO_VERSION=3.1.16 right now), this should probably fix most of > the link issues? I agree that would help a lot. I don't suppose you happen to have a patch? :)
We should make the adjustment to DISTRO version as mentioned but the docs.yoctoproject.org site is not at 4.0.1.
I think doing version by latest tag is OK but I would like to confirm whether or not tag is set when the release build is done. Does the release process apply tag before or after the release build?
Also, it is not clear to me why the value is set to 999 versus 0. I am looking at resolving this issue but the comments in the script do not tell the story why this decision was made. If I know the history I can either a/ think of a resolution or b/ add the comment behind the rationale.
The reason for .999 is to indicate these docs from from the latest HEAD revision of a given branch but haven't been released yet. For the 4.0 series, the version needs to be greater than the last point release but not newer than the other releases so .999 seemed the best compromise
After further inspection: The cause of the broken link is URL construction in rst using :yocto_dl: extlinks in conjunction with &DISTRO; For example: 1. Navigate to https://docs.yoctoproject.org/dev/sdk-manual/appendix-obtain.html 2. See point 1 under section 5.2.1 where the link is https://downloads.yoctoproject.org/releases/yocto/yocto-4.2.999/toolchain/ 3. See the sdk-manual/appendix-obtain.rst file :yocto_dl:`/releases/yocto/yocto-&DISTRO;/toolchain/` ** Options - *Least impact to documentation, adds new release subprocess, best experience for user* In YP releases directory, create '999' placeholder for latest major/minor with a README that explains the purpose of the '999' placeholder. When the final build for the major/minor is done, move .999 to the release build number. When new release is defined, create new .999 placeholder. - *Impacts documentation and maintenance, causes additional steps for user* Do not use the DISTRO; variable in URLs. Point to the parent directory, instruct the user to choose the desired release version and then navigate to any subfolder if necessary. - *Fragile option, may give best experience* When noticed that the &DISTRO; variable is set with build number 999, replace DISTRO with latest release. This could also be technically incorrect especially when the bleeding edge is a major release bump and the latest release is N-1 major version.
To add, this affects the following docs: bsp-guide/bsp.rst dev-manual/qemu.rst ref-manual/system-requirements.rst sdk-manual/intro.rst sdk-manual/appendix-obtain.rst sdk-manual/using.rst test-manual/intro.rst ref-manual/terms.rst : uses DISTRO_REL_TAG instead of DISTRO but has same effect
(In reply to comment #7) > - *Fragile option, may give best experience* When noticed that the > &DISTRO; variable is set with build number 999, replace DISTRO > with latest release. This could also be technically incorrect > especially when the bleeding edge is a major release bump and the > latest release is N-1 major version. I think this may give the best experience which is probably what we need to aim for. We are going to need to check all the uses of DISTRO to ensure this does make sense though.
Bulk move of 5.1 M4 to 5.2 M2 as approved by AlexB.
Patches sent to fix this: https://lists.yoctoproject.org/g/docs/message/6721
This has now been fixed. For example, quoting Richard Elberger here: > 1. Navigate to > https://docs.yoctoproject.org/dev/sdk-manual/appendix-obtain.html > 2. See point 1 under section 5.2.1 where the link is > https://downloads.yoctoproject.org/releases/yocto/yocto-4.2.999/toolchain/ The link will now point to the latest tag on the dev branch. As the dev branch may contain an old tag (because the future release had not been tagged yet) this is not a good example. For the dev branch it is fine to have outdated links, after all, a dev branch doesn't have any release to point to. Discussion about this here: https://lists.yoctoproject.org/g/docs/topic/112169337 A better example would be to take a current release's branch tip: https://docs.yoctoproject.org/styhead/sdk-manual/appendix-obtain.html Here, the link will point to the latest Styhead tag (yocto-5.1.4 as of today). Moving to Resolved fixed.