public inbox for gcc-bugs@sourceware.org
help / color / mirror / Atom feed
* [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
@ 2024-04-16 9:20 jakub at gcc dot gnu.org
2024-04-16 9:20 ` [Bug other/114738] " jakub at gcc dot gnu.org
` (7 more replies)
0 siblings, 8 replies; 9+ messages in thread
From: jakub at gcc dot gnu.org @ 2024-04-16 9:20 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Bug ID: 114738
Summary: [14 Regression] Default DOCUMENTATION_ROOT_URL vs.
release branches
Product: gcc
Version: 14.0
Status: UNCONFIRMED
Severity: normal
Priority: P3
Component: other
Assignee: unassigned at gcc dot gnu.org
Reporter: jakub at gcc dot gnu.org
Target Milestone: ---
gcc/configure.ac uses DOCUMENTATION_ROOT_URL="https://gcc.gnu.org/onlinedocs/"
as the default documentation root. That is great for the trunk, but I'm not
convinced
it is the right thing for release branches. The online docs at that location
are updated daily from the trunk, while the release branches will be supported
for ~ 3 years, during which a lot of the URLs hardcoded into the releases or
snapshots on release branches might get removed, the documentation changed etc.
Another option would be to switch that default on release branches to
docrootbase=
case "$gcc_version" in
*.[123456].0) docrootbase="$gcc_version/";;
*.[123456].1) docrootbase="`echo $gcc_version | sed 's/1$/0$/'`/";;
esac
DOCUMENTATION_ROOT_URL="https://gcc.gnu.org/onlinedocs/$docrootbase"
or so. That has the advantage that the URLs will reflect the corresponding
release's stable documentation for the 3 years (or even after it goes out of
support).
The disadvantage is that unlike the trunk online docs regenerated every day,
the release onlinedocs are only created when release is made.
So, say 14.1.0 docs will be correct, but if something in the docs or in the
options is changed in 14.1.1 between 14.1.0 and 14.2.0, the URLs on the release
branches might be stale.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
@ 2024-04-16 9:20 ` jakub at gcc dot gnu.org
2024-04-16 10:52 ` rguenth at gcc dot gnu.org
` (6 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: jakub at gcc dot gnu.org @ 2024-04-16 9:20 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Jakub Jelinek <jakub at gcc dot gnu.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |dmalcolm at gcc dot gnu.org
Target Milestone|--- |14.0
Priority|P3 |P1
--- Comment #1 from Jakub Jelinek <jakub at gcc dot gnu.org> ---
Marking this as P1 because I think we need to decide what to do before the
release.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
2024-04-16 9:20 ` [Bug other/114738] " jakub at gcc dot gnu.org
@ 2024-04-16 10:52 ` rguenth at gcc dot gnu.org
2024-04-16 10:55 ` rguenth at gcc dot gnu.org
` (5 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: rguenth at gcc dot gnu.org @ 2024-04-16 10:52 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Richard Biener <rguenth at gcc dot gnu.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
CC| |rguenth at gcc dot gnu.org
--- Comment #2 from Richard Biener <rguenth at gcc dot gnu.org> ---
IMO keeping https://gcc.gnu.org/onlinedocs/ is worse than making it release
specific.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
2024-04-16 9:20 ` [Bug other/114738] " jakub at gcc dot gnu.org
2024-04-16 10:52 ` rguenth at gcc dot gnu.org
@ 2024-04-16 10:55 ` rguenth at gcc dot gnu.org
2024-04-16 16:41 ` pinskia at gcc dot gnu.org
` (4 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: rguenth at gcc dot gnu.org @ 2024-04-16 10:55 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
--- Comment #3 from Richard Biener <rguenth at gcc dot gnu.org> ---
We could also make changing it part of branching.html and have additional
directories without minor/patchlevel version, thus
https://gcc.gnu.org/onlinedocs/gcc-14/ where we could autogenerate docs in more
often (but then
14.1.0 may point to stale info when gcc-14/ is updated from the branch).
Similar issues exist of course for older snapshot builds of trunk. Not sure
if this is all well thought through given the somewhat unstable URIs we
produce. The handling of changes.html references is much more sensible.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
` (2 preceding siblings ...)
2024-04-16 10:55 ` rguenth at gcc dot gnu.org
@ 2024-04-16 16:41 ` pinskia at gcc dot gnu.org
2024-04-17 14:18 ` cvs-commit at gcc dot gnu.org
` (3 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: pinskia at gcc dot gnu.org @ 2024-04-16 16:41 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Andrew Pinski <pinskia at gcc dot gnu.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Last reconfirmed| |2024-04-16
Ever confirmed|0 |1
Status|UNCONFIRMED |NEW
--- Comment #4 from Andrew Pinski <pinskia at gcc dot gnu.org> ---
.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
` (3 preceding siblings ...)
2024-04-16 16:41 ` pinskia at gcc dot gnu.org
@ 2024-04-17 14:18 ` cvs-commit at gcc dot gnu.org
2024-04-18 15:10 ` jakub at gcc dot gnu.org
` (2 subsequent siblings)
7 siblings, 0 replies; 9+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2024-04-17 14:18 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
--- Comment #5 from GCC Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Jakub Jelinek <jakub@gcc.gnu.org>:
https://gcc.gnu.org/g:57056146f4ffc5ea347c03e37e1e2c7cd99261d0
commit r14-10007-g57056146f4ffc5ea347c03e37e1e2c7cd99261d0
Author: Jakub Jelinek <jakub@redhat.com>
Date: Wed Apr 17 16:17:22 2024 +0200
DOCUMENTATION_ROOT_URL vs. release branches [PR114738]
Starting with GCC 14 we have the nice URLification of the options printed
in diagnostics, say for in
test.c:4:23: warning: format â%dâ expects argument of type âintâ,
but argument 2 has type âlong intâ [-Wformat=]
the -Wformat= is underlined in some terminals and hovering on it shows
https://gcc.gnu.org/onlinedocs/gcc/Warning-Options.html#index-Wformat
link.
This works nicely on the GCC trunk, where the online documentation is
regenerated every day from a cron job and more importantly, people rarely
use the trunk snapshots for too long, so it is unlikely that further
changes
in the documentation will make too many links stale, because users will
simply regularly update to newer snapshots.
I think it doesn't work properly on release branches though.
Some users only use the relased versions (i.e. MAJOR.MINOR.0) from tarballs
but can use them for a couple of years, others use snapshots from the
release branches, but again they could be in use for months or years and
the above mentioned online docs which represent just the GCC trunk might
diverge significantly.
Now, for the relases we always publish also online docs for the release,
which unlike the trunk online docs will not change further, under
e.g.
https://gcc.gnu.org/onlinedocs/gcc-14.1.0/gcc/Warning-Options.html#index-Wformat
or
https://gcc.gnu.org/onlinedocs/gcc-14.2.0/gcc/Warning-Options.html#index-Wformat
etc.
So, I think at least for the MAJOR.MINOR.0 releases we want to use
URLs like above rather than the trunk ones and we can use the same process
of updating *.opt.urls as well for that.
For the snapshots from release branches, we don't have such docs.
One option (implemented in the patch below for the URL printing side) is
point to the MAJOR.MINOR.0 docs even for MAJOR.MINOR.1 snapshots.
Most of the links will work fine, for options newly added on the release
branches (rare thing but still happens) can have until the next release
no URLs for them and get them with the next point release.
The question is what to do about make regenerate-opt-urls for the release
branch snapshots. Either just document that users shouldn't
make regenerate-opt-urls on release branches (and filter out *.opt.urls
changes from their commits), add make regenerate-opt-urls task be RM
responsibility before making first release candidate from a branch and
adjust the autoregen CI to know about that. Or add a separate goal
which instead of relying on make html created files would download
copy of the html files from the last release from web (kind of web
mirroring the https://gcc.gnu.org/onlinedocs/gcc-14.1.0/ subtree locally)
and doing regenerate-opt-urls on top of that? But how to catch the
point when first release candidate is made and we want to update to
what will be the URLs once the release is made (but will be stale URLs
for a week or so)?
Another option would be to add to cron daily regeneration of the online
docs for the release branches. I don't think that is a good idea though,
because as I wrote earlier, not all users update to the latest snapshot
frequently, so there can be users that use gcc 13.1.1 20230525 for months
or years, and other users which use gcc 13.1.1 20230615 for years etc.
Another question is what is most sensible for users who want to override
the default root and use the --with-documentation-root-url= configure
option. Do we expect them to grab the whole onlinedocs tree or for release
branches at least include gcc-14.1.0/ subdirectory under the root?
If so, the patch below deals with that. Or should we just change the
default documentation root url, so if user doesn't specify
--with-documentation-root-url= and we are on a release branch, default that
to https://gcc.gnu.org/onlinedocs/gcc-14.1.0/ or
https://gcc.gnu.org/onlinedocs/gcc-14.2.0/ etc. and don't add any infix in
get_option_url/make_doc_url, but when people supply their own, let them
point to the root of the tree which contains the right docs?
Then such changes would go into gcc/configure.ac, some case based on
"$gcc_version", from that decide if it is a release branch or trunk.
2024-04-17 Jakub Jelinek <jakub@redhat.com>
PR other/114738
* opts.cc (get_option_url): On release branches append
gcc-MAJOR.MINOR.0/ after DOCUMENTATION_ROOT_URL.
* gcc-urlifier.cc (gcc_urlifier::make_doc_url): Likewise.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
` (4 preceding siblings ...)
2024-04-17 14:18 ` cvs-commit at gcc dot gnu.org
@ 2024-04-18 15:10 ` jakub at gcc dot gnu.org
2024-04-24 16:31 ` cvs-commit at gcc dot gnu.org
2024-04-25 8:51 ` jakub at gcc dot gnu.org
7 siblings, 0 replies; 9+ messages in thread
From: jakub at gcc dot gnu.org @ 2024-04-18 15:10 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Jakub Jelinek <jakub at gcc dot gnu.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Priority|P1 |P2
--- Comment #6 from Jakub Jelinek <jakub at gcc dot gnu.org> ---
Keeping open for discussions on what to do on the release branches after the
release, the release itself should be fine with the committed patch.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
` (5 preceding siblings ...)
2024-04-18 15:10 ` jakub at gcc dot gnu.org
@ 2024-04-24 16:31 ` cvs-commit at gcc dot gnu.org
2024-04-25 8:51 ` jakub at gcc dot gnu.org
7 siblings, 0 replies; 9+ messages in thread
From: cvs-commit at gcc dot gnu.org @ 2024-04-24 16:31 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
--- Comment #7 from GCC Commits <cvs-commit at gcc dot gnu.org> ---
The master branch has been updated by Jakub Jelinek <jakub@gcc.gnu.org>:
https://gcc.gnu.org/g:97a54c05b8e338e673e1f7fb72c0e23abb571c60
commit r14-10109-g97a54c05b8e338e673e1f7fb72c0e23abb571c60
Author: Jakub Jelinek <jakub@redhat.com>
Date: Wed Apr 24 18:29:12 2024 +0200
v2: DOCUMENTATION_ROOT_URL vs. release branches [PR114738]
This patch moves the documentation root URL infix for release branches
from get_option_url/make_doc_url to configure, such that only the default
changes and when users specify a custom documentation root URL, they don't
have to add gcc-MAJOR.MINOR.0 subdirectories for release branches.
Tested by checking
../configure --disable-bootstrap --enable-languages=c --disable-multilib
built trunk on
void
foo (int x)
{
__builtin_printf ("%ld\n", x);
}
testcase and looking for the URL in there, then repeating that after
changing gcc/BASE-VER to 14.1.0 and again after changing it to 14.1.1,
plus normal bootstrap/regtest.
2024-04-24 Jakub Jelinek <jakub@redhat.com>
PR other/114738
* opts.cc (get_option_url): Revert 2024-04-17 changes.
* gcc-urlifier.cc: Don't include diagnostic-core.h.
(gcc_urlifier::make_doc_url): Revert 2024-04-17 changes.
* configure.ac (documentation-root-url): On release branches
append gcc-MAJOR.MINOR.0/ to the default DOCUMENTATION_ROOT_URL.
* doc/install.texi (--with-documentation-root-url=): Document
the change of the default.
* configure: Regenerate.
^ permalink raw reply [flat|nested] 9+ messages in thread
* [Bug other/114738] [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
` (6 preceding siblings ...)
2024-04-24 16:31 ` cvs-commit at gcc dot gnu.org
@ 2024-04-25 8:51 ` jakub at gcc dot gnu.org
7 siblings, 0 replies; 9+ messages in thread
From: jakub at gcc dot gnu.org @ 2024-04-25 8:51 UTC (permalink / raw)
To: gcc-bugs
https://gcc.gnu.org/bugzilla/show_bug.cgi?id=114738
Jakub Jelinek <jakub at gcc dot gnu.org> changed:
What |Removed |Added
----------------------------------------------------------------------------
Assignee|unassigned at gcc dot gnu.org |jakub at gcc dot gnu.org
Status|NEW |RESOLVED
Resolution|--- |FIXED
--- Comment #8 from Jakub Jelinek <jakub at gcc dot gnu.org> ---
Fixed.
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2024-04-25 8:51 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2024-04-16 9:20 [Bug other/114738] New: [14 Regression] Default DOCUMENTATION_ROOT_URL vs. release branches jakub at gcc dot gnu.org
2024-04-16 9:20 ` [Bug other/114738] " jakub at gcc dot gnu.org
2024-04-16 10:52 ` rguenth at gcc dot gnu.org
2024-04-16 10:55 ` rguenth at gcc dot gnu.org
2024-04-16 16:41 ` pinskia at gcc dot gnu.org
2024-04-17 14:18 ` cvs-commit at gcc dot gnu.org
2024-04-18 15:10 ` jakub at gcc dot gnu.org
2024-04-24 16:31 ` cvs-commit at gcc dot gnu.org
2024-04-25 8:51 ` jakub at gcc dot gnu.org
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).