Fix broken links in the Devguide

[Mariatta]

Looks like the Link check step in the CI is broken. It has always been allowed to fail for a long time.
Would be great to fix them all.

Please see the output here:
https://github.com/python/devguide/runs/2463428458?check_suite_focus=true

While looking at the output, I noticed that pypy.org is listed as broken. I think that's the correct url though. I've filed the issue here:

pypy/pypy.org#23
Update: the url seems to work now.

But it would be good to look through the rest and update the urls accordingly.

[Mariatta]

I think it would be great if link check becomes a required CI check, once we fixed all the urls.

[himanshu007-creator]

Hi, i would like to fix the broken links. Please assign me this issue

[Mariatta]

We don't assign issues to non core developers. You can just start creating the PR and we go from there.

[himanshu007-creator]

There are total 11 broken links. I have fixed 6 of 'em. But there are some links i would like to ask about.

this and this link point to same website and this website just shows a white screen

This metadata is not available as mentioned in issue

This link doesn't work because the repo is either made private or deleted

This website shows a 522 error

I would like to know how should they be resolved.

[Mariatta]

This website shows a 522 error

Looks like gmane.org moved to https://gmane.io/

This link doesn't work because the repo is either made private or deleted

Yes the python/voters repo is a private repo that is available for Python core devs only. So it looks like we will have to allow that the linkcheck to be broken :( Is there a way to tell sphinx linkcheck to ignore this specific url?

This metadata is not available as mentioned in issue

Hmm yes, I also don't know what the correct URL is. It has been discussed previously in
#456.

Does anyone know where is the the Issue tracker for the tracker is? I thought that it's now being tracked at github.com/python/bugs.python.org, but this is the issue tracker for our own instance of it. It sounds like there is another issue tracker just for Roundup. But I don't know where that is.

this and this link point to same website and this website just shows a white screen

Those are Phillip Guo's websites. Seems like it's not active anymore. I'm not sure if they have another website now.
Perhaps we can either remove the links, or point to a different resource.

I understand that there are still broken links, however, if you can just start opening the pull request with the fixes that you've made, I think it would bring us to a better place already. We can continue fixing the broken links later.

[Mariatta]

There is a way to tell linkcheck to ignore urls. The documentation is here:
https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=linkcheck#options-for-the-linkcheck-builder

Perhaps we need to add the python/voters url to it.

[hugovk]

Does anyone know where is the the Issue tracker for the tracker is? I thought that it's now being tracked at github.com/python/bugs.python.org, but this is the issue tracker for our own instance of it. It sounds like there is another issue tracker just for Roundup. But I don't know where that is.

Is it https://issues.roundup-tracker.org/ ?

[Mariatta]

Yes it looks like it.

[pratyaksh1610]

I am new to open source . Can you guide me through the journey ?
How can I resolve my first issue ?

[pratyaksh1610]

@Mariatta

[jablonskidev]

@pratyaksh1610 If you're looking for guidance on how to find and fix your first issue, you can check out this resource: https://realpython.com/start-contributing-python/

[Noel-Voelin]

As far as I see, this issue is resolved. @Mariatta can you please close this or update with what is needed? Thanks!

[Mariatta]

@Noel-Voelin there are still broken URLs in the linkcheck stage, and we need to get them fixed.

The output is here: https://github.com/python/devguide/pull/727/checks?check_run_id=3079759235

Some of the urls are not broken but rather restricted/hidden. You may need to adjust the config/settings such that linkcheck will ignore those urls. This doc describes how to set the options: https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=linkcheck#options-for-the-linkcheck-builder

Hope this helps.

[za]

Hi @Mariatta

I can't see the output anymore:

The logs for this run have expired and are no longer available.

Do you mind to re-run/paste/summarize the output?

Thank you.

[MohitMandalia]

Hi @Mariatta,

I would like you to check this link from documentation it says website can't be reached , I am not sure what site it points.

Also this link points to an empty git repo.

Please let me know how to fix those.

Thank you.

[hugovk]

I would like you to check this link from documentation it says website can't be reached , I am not sure what site it points.

https://t.me/pybr_i18n is a link to a Telegram channel. If you have Telegram installed on your phone, it opens the channel in the app. Tested just now on Android and it works.

[MohitMandalia]

I would like you to check this link from documentation it says website can't be reached , I am not sure what site it points.

https://t.me/pybr_i18n is a link to a Telegram channel. If you have Telegram installed on your phone, it opens the channel in the app. Tested just now on Android and it works.

Thanks.

[BrianWisniewski]

There also appears to be a broken link within both steps 5 and 7 here.

[hugovk]

https://github.com/python/voters/ is a private repo so only those with access can see it.

I've created #793 to try and make it more obvious the repo is locked/private.

[slateny]

Some more broken links (copy the text then ctrl+f in the page) that I'm not too sure what to do:

described in the buildbot documentation
For an example, see the Py_NewRef (not broken, but misaligned - maybe use hash instead of Python version)
The Tracker-discuss mailing list
In Python’s Zulip Chat
Extended bio (for Brett Cannon)

[hugovk]

described in the buildbot documentation

Here's an archived version or perhaps you can find something relevant at https://docs.buildbot.net/current/ ?

For an example, see the Py_NewRef (not broken, but misaligned - maybe use hash instead of Python version)

Yeah, for these, I recommend fixing the #Lxxx-Lyyy bit, and then press the y key on your keyboard to get a permalink.

The Tracker-discuss mailing list

There's an archive but "Discussions about the bug tracker itself", referring to bpo, is irrelevant so I think this can be removed.

In Python’s Zulip Chat

I think this can be removed, but @Mariatta can confirm as it referred to her office hour in Zulip.

(https://devguide.python.org/help) Extended bio (for Brett Cannon)

Hi @brettcannon, this used to link to https://stackoverflow.com/cv/DrBrettCannon but it's 404. Would you like another link here, or have it removed?

[brettcannon]

@hugovk the link can just go.

But I honestly don't know if that page is even worth keeping since not many people have filled it out and I know some of it is outdated (e.g. @kushaldas has changed employers).

[slateny]

Thanks for the links, Couldn't find a page exactly relevant to buildbot so I used the archieve, and I've updated the PR with all but the Zulip. If Zulip's no longer used, then should the entire section on it be removed?

And as an aside, if it does get removed, it feels that the help page gets a bit bare and a good chunk of content overlaps with the communications page, so maybe some merging can be considered as well?

[hugovk]

I've never used Zulip, and I understand it's little used. People will have more luck getting help on the other channels so I'd say it makes sense removing the Zulop section.

The aside:

There's still quite a bit of stuff on the help page.

To me the help page, "Where to Get Help", and the communications page, "Following Python’s Development", serve quite different purposes.

[ezio-melotti]

I merged actions/toolkit#831.
I was also looking at the the workflow that runs the make linkcheck:

devguide/.github/workflows/ci.yml

Lines 24 to 26 in ad524ba

	- name: Link check
	run: make linkcheck
	continue-on-error: true

In https://github.com/python/devguide/runs/6050460764?check_suite_focus=true everything looks green, but the "Link check" step failed with

 build finished with problems.
make: *** [Makefile:132: linkcheck] Error 1
Error: Process completed with exit code 2.

I understand that the step is allowed to fail (because of the continue-on-error), but the failure seems completely hidden unless you open the logs. I found actions/runner#2347 that discusses the issue, but there doesn't seem to be a clean solution -- just some workarounds.

I was also exploring other ways to report the failure: steps.<step_id>.outcome can be used to obtain the status of the previous step (e.g. the link check), however I wasn't able to find a way to set the status description of the job so that it shows next to the name of the check.

In the meanwhile I created actions/toolkit#840, and also found actions/toolkit#727 that is related to the continue-on-error

[kushaldas]

@hugovk the link can just go.

But I honestly don't know if that page is even worth keeping since not many people have filled it out and I know some of it is outdated (e.g. @kushaldas has changed employers).

Wondering if I should create a PR to update properly!!

[hugovk]

@kushaldas Sure!

@ezio-melotti I saw your comment at #727 (comment) and replied to it there: #727 (comment)