[doc] contributing guidelines and code of conduct... aren't.

[guest20]

TL;DR: The docs for submitting PRs/issues could use improvement.

Where

Github's issue and PR user interface, as configured by .github/ bureaucracy files.

Description

When one opens their first issue / pull request on github will show a popup.

The popup links to relevant policy documents to let users know what the project expects of them.

The popup looks like this:

The popup reads:

👋 It looks like this is your first time opening {a pull request|an issue} in this project!

Be sure to review the contributing guidelines and code of conduct.

Reporting a security vulnerability? Check out the project's security policy.

The links in this dialog are very much sub-useful.

CONTRIBUTING.pod is a symbolic link

because .github/CONTRIBUTING.pod is a symlink, Github just shows the name the link points to. It does not render the pod. It does not link the user to the linked file. The user then has to navigate there via the file tree on the left.

perlhack is a lengthy, repetitive document with a "3 different gospels retelling the crucifixion" type vibe to it. The "SUPER QUICK PATCH GUIDE" section is nearly 2 pages, and seems to duplicate the content of perlgit, yet does not cover "just clicking edit directly on github".

If I had to read 1321 lines (893 loc) · 44 KB of meandering pod before submitting a pull request to fix a typo in pod, I'd likely end up submitting an issue about that instead of submitting the original PR

code of conduct

This links to a document:

• tells you to go read perlpolicy (linking to perldoc.perl.org and to pod/perlpolicy.pod), the CoC is at the end of perlpolicy and 2 of the 3 links to that document are without anchors pointing to that section.
• links to perlgov and
• finally, it defensively mentions that the PSC is independent of TPF.

neither perlgov nor perlpolicy are focussed on code of conduct, and are far too involved for someone to read before submitting their first PR/issue.

Perhaps the STANDARDS OF CONDUCT section from perlgov should be dumped directly in /CODE_OF_CONDUCT.pod and referenced from the places that need to (perlgov references removal for violating CoC, but doesn't link to a CoC, for example)?

It's short enough to not need the intermediate summary document, .

security policy

This links to a document detailing how to report security issues, so that one's spot on. Good stuff.

I think the difference here is that SECURITY.md is a short summary of a single, focused perl* doc instead of linking to a section in another document

[leonerd]

Since github doesn't follow a symlink in order to render CONTRIBUTING.pod, why don't we just copy it?

In order to prevent it getting out of sync with the real one, we could just have a regen/github.pl script that does the copy for us in case it breaks...