Project

General

Profile

Task #2084

Broken bugzilla help links

Added by B.J. Herbison about 1 year ago. Updated 6 months ago.

Status:
Closed
Priority:
Normal
Category:
-
Target version:
Team - Pool
Start date:
Due date:
% Done:

80%

Estimated time:
Tags:
URL:

Description

From a ticket (https://bugs.documentfoundation.org/show_bug.cgi?id=60215 for example) the Help link at the top and bottom right is broken. Current link: https://bugs.documentfoundation.org/docs/en/html/using/understanding.html

From https://bugs.documentfoundation.org/ the Documentation link is broken. Current link: https://bugs.documentfoundation.org/docs/en/html/using/index.html

From https://bugs.documentfoundation.org/admin.cgi the Help link at the top and bottom right is broken. Current link: https://bugs.documentfoundation.org/admin.cgi

History

#1 Updated by Florian Effenberger about 1 year ago

  • Assignee set to Christian Lohmaier
  • Target version set to Pool

#2 Updated by Jean Spiteri about 1 year ago

If no work has been done on this already, I can take care of it.

#3 Updated by Jean Spiteri about 1 year ago

  • Status changed from New to In Progress

The problem here is that Bugzilla migrated to an externally hosted documentation site. However, in the code, Bugzilla is checking whether inbuilt docs exist (which they do) and thus is sending the user to them. The inbuilt help is, however, out of date.

There are two solution for this
- Removing the docs folder and thus letting Bugzilla to default to the default one (bugzilla.readthedocs.org)
- Updating the inbuilt Bugzilla docs (currently are based on 4.4.6)
- Removing the if statement that is doing the check

If my help is needed/wanted, I am ready to help. However, I think that I need further guidance on which way should the fix go.

#4 Updated by Jean Spiteri about 1 year ago

The if statement mentioned above starts at line 1043 of Bugzilla/Template.pm

#5 Updated by Florian Effenberger about 1 year ago

Thanks a lot for looking into this, Jean!
Can you provide a patch/diff we can apply to the code? Let me know, when we can proceed that way :)

#6 Updated by Jean Spiteri about 1 year ago

I've no problem to do a patch. However, I need to know whether the docs are needed on the server (in reality they seem to be outdated) or whether it's good to lead users to an external site for them (the Bugzilla Docs site). Removing the if statement is a workaround, I'd think is better to avoid.

#7 Updated by Jean Spiteri about 1 year ago

  • Assignee changed from Christian Lohmaier to Jean Spiteri

#8 Updated by Florian Effenberger about 1 year ago

There is indeed a "Help" link for each bug pointing to an invalid URL

What's also still in place is the big "?" link at the main page pointing to https://bugs.documentfoundation.org/docs/en/html/using/index.html

For the moment, let's use https://bugzilla.readthedocs.io/en/5.0/using/index.html as external source

Our Bugzilla source for the patch is at git://gerrit.libreoffice.org/bugzilla

#9 Updated by Jean Spiteri about 1 year ago

I have submitted a patch to Gerrit https://gerrit.libreoffice.org/#/c/31950/ that removes the whole docs/ folder. If this is merged and the server is updated, then the docs/ folder on the server should be checked again to make sure that it is empty (the docs/ folder could contain files that are ignored by git). The lack of docs should redirect the user to the external source.

Otherwise, the current docs can be updated by running docs/makedocs.pl. I do not have any access so I don't know if this can be done or not.

Let me know if I can help further.

#10 Updated by Jean Spiteri 12 months ago

I know this is not the best time to submit this but everyone can see this at the time he wants to, so I'll submit it. I've done another patch that adds the generated docs to the repository. This adds quite some files to the repository but don't think that it should be a problem because these files are already on the server, it seems. The Gerrit patch request can be found on https://gerrit.libreoffice.org/#/c/32232/. This avoids the need to delete anything and avoids also the need for an external source of documentation.

If someone can review this issue and patches and tell me which one is more suitable, I'd be very grateful. Please note that these patches can't be applied both since they do opposite things. If the latter patch is applied, I can try to create a git hook that automatically updates the docs, if requested.

Let me know if anything else is needed. Thanks.

#11 Updated by Florian Effenberger 11 months ago

Thanks a lot - asked Xisco to have a look!

#12 Updated by Guilhem Moulin 11 months ago

Thanks for the pointer to `docs/makedocs.pl`, Jean. Quoting myself on [[https://gerrit.libreoffice.org/#/c/32232]],

files under the docs/en/{html,txt,xml} directories can be automatically generated using
`docs/makedocs.pl`, so I think it's a bit counter intuitive to store them in the VCS.

I just (manually) ran the above command to build the docs, but of course if we go down that
path, the proper way would be to use a git hook in order to run it automatically after each
merge/rebase touching files under `docs/en/rst`.

I leave the bug open as someone might object and prefer to delete the directory altogether
(to redirect users outside of TDF infra); and until a proper git hook is installed on
`bugs.documentation.org` the docs will diverge again next time a file under `docs/en/rst`
is modified.

#13 Updated by Jean Spiteri 11 months ago

Guilhem Moulin wrote:

I just (manually) ran the above command to build the docs, but of course if we go down that
path, the proper way would be to use a git hook in order to run it automatically after each
merge/rebase touching files under `docs/en/rst`.

So, just to check if I understood well, the bug mentioned here is fixed. However, the suggestion now is that a git hook is installed to run on every merge/rebase right?

Thanks for checking the requests and sorry for the interruption.

#14 Updated by Guilhem Moulin 11 months ago

Jean Spiteri wrote:

So, just to check if I understood well, the bug mentioned here is fixed.
However, the suggestion now is that a git hook is installed to run on
every merge/rebase right?

Correct

#15 Updated by Jean Spiteri 11 months ago

I've prepared a script that can run as the git hook. I've tested it and it should work but of course, it should be tested on the test bugzilla first. How should I send it to you? Should I send it through email or upload to the repo, please?

#16 Updated by Guilhem Moulin 11 months ago

Email is fine, but as you prefer. You'll find my address by clicking on my name in this page. Thanks for working on this!

#17 Updated by Jean Spiteri 11 months ago

Sent it. Thanks for your quick reply.

#18 Updated by Jean Spiteri 11 months ago

  • % Done changed from 0 to 80

#19 Updated by Jean Spiteri 6 months ago

  • Assignee changed from Jean Spiteri to Guilhem Moulin

Guilheim Moulin made an updated hook. I don't know what happened after that so I'm assigning it to him.

#20 Updated by Guilhem Moulin 6 months ago

  • Status changed from In Progress to Closed

According to my notes I installed the following post-merge hook on Feb 21, but forgot to close this :-/

#!/bin/sh

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.

if ! git diff --quiet ORIG_HEAD HEAD -- docs/; then
    echo "Docs files have been changed, generating new documentation..." >&2
    docs/makedocs.pl
    echo "Docs have been regenerated." >&2
fi

Also available in: Atom PDF