docs/CONTRIBUTING.md: Fix links in CONTRIBUTING #32473
Conversation
docs/CONTRIBUTING.md
Outdated
| @@ -38,8 +38,8 @@ See [reporting of security vulnerabilities](/SECURITY). | |||
| ## Posting Pull Requests | |||
|
|
|||
| * Make sure to post PRs only relative to a recent tip of the `main` branch. | |||
| * Follow our [Coding Style](/CODING_STYLE) when contributing code. This is a requirement for all code we merge. | |||
| * Please make sure to test your change before submitting the PR. See the [Hacking guide](/HACKING) for details on how to do this. | |||
| * Follow our [Coding Style](./CODING_STYLE.md) when contributing code. This is a requirement for all code we merge. | |||
There was a problem hiding this comment.
Why? We need absolute path here, and the rendered files are .html, not .md ...
If currently the links are broken for systemd.io, that's because the recent changes haven't been deployed.
There was a problem hiding this comment.
I wasn't aware of https://systemd.io/CONTRIBUTING/ . My experience as a first-time contributor was to open a new PR, get side dialog from Github telling me to review the contributing guide and get a 404 when checking those files.
Is there a way to have the links work both on Github and on systemd.io ? I see a few absolute links (e.g. the README one) and was wondering why the difference, that makes sense now.
There was a problem hiding this comment.
Is there a way to have the links work both on Github and on systemd.io ?
Well, I'd rather avoid reading raw .md files (although they might be readable). Instead, convert links that point to these markdown files to point to systemd.io?
There was a problem hiding this comment.
Good point. Changed to that.
There was a problem hiding this comment.
So, I sympathize with having valid links in the documents that are rendered by GH as well, and I think I have a potential solution, but will need to do a couple of tests first just to make sure it doesn't break anything.
There was a problem hiding this comment.
@YHNdnzj : I amended the commit but forgot to add 🤦 Fixed now.
@mrc0mmand : I don't have a strong opinion either way. The docs on systemd.io are nicely rendered, but I could live with the ones in Github as well. What matters most to me is that first time contributors don't run into obstacles when getting started. Perhaps there's value in having them stay on Github but I leave that judgement call to more seasoned contributors.
There was a problem hiding this comment.
Oh well, nevermind. The trailing slash we have in the page permalink is really annoying and thwarts any attempts to work around this, but we can't drop it without breaking existing links. Not sure what to do here, but rI guess eplacing the absolute links with fully qualified URLs might be a possibility.
YHNdnzj
added
documentation
reviewed/needs-rework 🔨
github-actions
bot
added
please-review
YHNdnzj
added
reviewed/needs-rework 🔨
Geod24
force-pushed
the
mlang/CONTRIBUTING
branch
from
4c6ae24
to
b7cfbf8
Compare
Geod24
changed the title
github-actions
bot
added
please-review
Get them to point to the rendered version, instead of letting Github thinks they are absolute links in the repository. The rendered version is much more user-friendly.
Geod24
force-pushed
the
mlang/CONTRIBUTING
branch
from
b7cfbf8
to
650c6d9
Compare
|
Hmm, I was more thinking about changing README.md, so that new contributors go directly to systemd.io rather than the markdown files. |
I didn't get there through README though, I got there through the prompt on the RHS: There's also this when you open a PR: (Contributing link) |
Get them to point to the rendered version, instead of
letting Github thinks they are absolute links in the
repository. The rendered version is much more user-friendly.Use relative links and the right name.