Integrate sphinx's linkcheck

[dukecat0]

The output.txt will be generated in build/check/.

[webknjaz]

plz don't include updates to this file in the PR

[dukecat0]

This is generated by Github Action. The workflow is running in fork.

[webknjaz]

Interesting. Could you disable the workflow in your fork?

[dukecat0]

Now I've disabled it. However, folks may still have this file in their PR if they didn't disable the workflow. Is there any method to disable it for all forks?

[dukecat0]

Maybe we could add if github.repository=='pypa/packaging.python.org' to our workflow?

I found this here: https://github.community/t/stop-github-actions-running-on-a-fork/17965/2

For reference: https://docs.github.com/en/actions/reference/context-and-expression-syntax-for-github-actions#github-context

[webknjaz]

What if the contributors would actually want to run workflows?

[dukecat0]

Good question. I guess they don't really need to run this workflow in their forks? Since we could run this in our repo once PR is merged.

[webknjaz]

Some people push branches to forks and check if they are fine before creating a PR, though.

[webknjaz]

Re: broken links — I think it's acceptable to ignore all of the failures and then fix them in a follow-up, unless you want to do that right here.

[dukecat0]

@webknjaz Sorry for the late response. I've turned it into a matrix and seems it works.

Re: broken links — I think it's acceptable to ignore all of the failures and then fix them in a follow-up, unless you want to do that right here.

I prefer fixing them in a follow-up. :)

[webknjaz]

I prefer fixing them in a follow-up. :)

Then add them to ignores so that the job is green.

[webknjaz]

@di could you make the linkcheck check required?

[dukecat0]

Then add them to ignores so that the job is green.

Probably I should fix them in this PR. The list is quite long.

[webknjaz]

Probably I should fix them in this PR. The list is quite long.

There's 28 entries. I think it would be more effective should merge and fix them later.

[pradyunsg]

I think it would be more effective should merge and fix them later.

I'm inclined to agree.

[pradyunsg]

@meowmeowmeowcat I suggest you rebase PRs, instead of merging main repeatedly to have a cleaner history -- see https://akrabat.com/the-beginners-guide-to-rebasing-your-pr/.

This also enables you to have more incremental workflows as well, like using fixup commits with git rebase: https://jordanelver.co.uk/blog/2020/06/04/fixing-commits-with-git-commit-fixup-and-git-rebase-autosquash/ (which isn't necessary for most open source projects, but could be useful in professional environments).

[dukecat0]

@pradyunsg Thanks for your suggestion!

[webknjaz]

I think it would be more effective should merge and fix them later.

I'm inclined to agree.

Urgh... I was hoping to merge this with the links added to linkcheck_ignore so we could have that job marked as required right away.

@meowmeowmeowcat I suggest you rebase PRs, instead of merging main repeatedly to have a cleaner history

Honestly, I gave up long ago on having a clean history in this repository. Most of the contributors haven't had proper Git training anyway. But yeah, those "foxtrot merges" are sometimes annoying. OTOH I do prefer a history that actually represents the order of events and the flow of thoughts.

@meowmeowmeowcat if you want to learn to keep the history nice and clean, you probably need to get yourself familiar with interactive rebases. And maybe git-worktree if you tend to work on several PRs in the same project simultaneously.

If you want to go through more aspects of working with Git like a pro, here's a list of resources I have:

• ProGit 2
• Try Git
• Try Git Branching
• Interactive diagram/cheatsheet about git
• You're using git wrong
• Learn git concepts, not commands
• The advantages of an email-driven git workflow
• Git For Ages 4 And Up
• A useful template for commit messages
• Understanding the GitHub Flow
• Closing issues using keywords
• email + git = <3
• http://chris.beams.io/posts/git-commit/
• http://alistapart.com/article/the-art-of-the-commit
• https://robots.thoughtbot.com/5-useful-tips-for-a-better-commit-message
• https://github.com/erlang/otp/wiki/writing-good-commit-messages
• https://wiki.openstack.org/wiki/GitCommitMessages
• http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
• https://dev.to/gonedark/when-to-make-a-git-commit
• https://seesparkbox.com/foundry/atomic_commits_with_git
• https://twitter.com/nedbat/status/1283147492616556544
• https://dhwthompson.com/2019/my-favourite-git-commit

• https://dev.to/cbillowes/why-i-create-atomic-commits-in-git-kfi
• https://curiousprogrammer.io/blog/why-i-create-atomic-commits-in-git
• https://curiousprogrammer.io/blog/how-to-craft-your-changes-into-small-atomic-commits-using-git
• https://frederickvanbrabant.com/posts/atomic-commits
• http://www.pauline-vos.nl/atomic-commits/
• https://www.codewithjason.com/atomic-commits-testing/
• https://fnune.com/2018/02/19/git-best-practices-atomic-commits/
• https://www.freshconsulting.com/atomic-commits/
• https://seesparkbox.com/foundry/atomic_commits_with_git
• http://adopteungit.fr/en/methodology/2017/04/26/how-to-do-atomic-commits.html
• https://zachholman.com/posts/git-commit-history/
• https://stackoverflow.com/a/38155649/595220
• https://git-rebase.io/

[dukecat0]

Urgh... I was hoping to merge this with the links added to linkcheck_ignore so we could have that job marked as required right away.

It's ok. I will open a follow-up for broken links in few days and then we can mark the job as required in it. :)

@webknjaz Thanks for your resources! I found some of them are quite interesting. I'll take some time on reading them. 👍