New Contributing Guide

[metalllinux]

Author checklist (Completed by original Author)

• Good fit for the Rocky Linux project? Title and Author Metatags inserted ?
• If applicable, steps and instructions have been tested to work
• Initial self-review to fix basic typos and grammar completed

Rocky Documentation checklist (Completed by Rocky team)

• 1st Pass (Document is good fit for project and author checklist completed)
• 2nd Pass (Technical Review - check for technical correctness)
• 3rd Pass (Detailed Editorial Review and Peer Review)
• Final approval (Final Review)

Summary

• Adds a comprehensive CONTRIBUTING.md guide for Rocky Linux documentation contributors
• Adds .pyspelling.yml configuration for spell checking with hunspell
• Updates .markdownlint.yml to allow <details> and <summary> HTML elements used in documentation

Details

The Contributing Guide includes:

• Step-by-step local editing setup instructions for Rocky Linux 10, 9, 8, macOS Sequoia, and Windows 11
• Validation tooling setup (pyspelling, markdownlint, lychee)
• Document formatting standards and best practices
• Admonition usage guide with examples
• Raw HTML guidelines
• Instructions for submitting a pull request
• Links to Mattermost and GitHub for community support

Test plan

• Verified markdownlint passes with zero errors
• Verified pyspelling runs successfully with hunspell backend
• Verified all internal links resolve correctly
• Review rendered markdown on GitHub for formatting accuracy

🤖 Generated with Claude Code

[sspencerwire]

Hi @metalllinux and thank you again for this. A couple of things:

• First, the front matter is missing in the CONTRIBUTING.md document. Minimum elements there should be:
  Title:
  author:
• Second, it looks like you used AI for some of the coding (which I'm pretty sure we discussed openly in the channel.) That's fine, but can you add the disclaimer at the top that we discussed or something along those lines? I know it isn't technically policy yet, but I think there needs to be something there, and it needs to be at the beginning not at the end of the document.
• Third, I get that the .pyspelling.yml and .markdownlint.yml are in the root (i.e., ahead of the docs directory) but I think that CONTRIBUTING.md should be instead in the contributions section of the guides (docs/guides/contribute/) rather than in the root of the project.
  *Fourth, to maintain file naming conventions that have already been established in the /docs/ section, I think that rather than all capitals that the filename should be contributing.md

If you can justify the reasons for your documents as is, let me know.

Thank you again!

[metalllinux]

Hi @metalllinux and thank you again for this. A couple of things:

• First, the front matter is missing in the CONTRIBUTING.md document. Minimum elements there should be:
  Title:
  author:
• Second, it looks like you used AI for some of the coding (which I'm pretty sure we discussed openly in the channel.) That's fine, but can you add the disclaimer at the top that we discussed or something along those lines? I know it isn't technically policy yet, but I think there needs to be something there, and it needs to be at the beginning not at the end of the document.
• Third, I get that the .pyspelling.yml and .markdownlint.yml are in the root (i.e., ahead of the docs directory) but I think that CONTRIBUTING.md should be instead in the contributions section of the guides (docs/guides/contribute/) rather than in the root of the project.
  *Fourth, to maintain file naming conventions that have already been established in the /docs/ section, I think that rather than all capitals that the filename should be contributing.md

If you can justify the reasons for your documents as is, let me know.

Thank you again!

From the conversation in the Mattermost thread: https://chat.rockylinux.org/rocky-linux/pl/ud6d3z3mabgu88wu6ndrascz5r

Hi @sspencerwire and again thank you ever so much for the review!

First, the front matter is missing in the CONTRIBUTING.md document. Minimum elements there should be:
Title:
author:

Ah, okay got it, so front matter needs to be included for all files, not just guides, books, labs and so on. I'll make sure to include that!

Second, it looks like you used AI for some of the coding (which I'm pretty sure we discussed openly in the channel.) That's fine, but can you add the disclaimer at the top that we discussed or something along those lines? I know it isn't technically policy yet, but I think there needs to be something there, and it needs to be at the beginning not at the end of the document.

AI was used here that is correct. I made sure it was publicly known by the Documentation Team and the community in this thread initially when I started on this endeavour on creating the new CONTRIBUTING.md I want to be as open as possible! I didn't want anything to come as a surprise.

can you add the disclaimer at the top that we discussed or something along those lines?

Absolutely and I'm glad that was brought up, that was one item I was unsure of regarding placing the disclaimer in core guiding docs like CONTRIBUTING.md. I'll make sure to add a disclaimer there as well.

Third, I get that the .pyspelling.yml and .markdownlint.yml are in the root (i.e., ahead of the docs directory) but I think that CONTRIBUTING.md should be instead in the contributions section of the guides (docs/guides/contribute/) rather than in the root of the project.

Okay, thank you and will make the change.

Fourth, to maintain file naming conventions that have already been established in the /docs/ section, I think that rather than all capitals that the filename should be contributing.md

Excellent and I will make that change as well.

@wale - thank you kindly for your review and comments below:

If that's the case - that particular merge request should be declined. My rationale for that is - we can't have Ai assistant or LLM crafting core guiding docs or policies. That bit should be the purview of human doc maintainers and the community.

Absolutely can see where you're coming from - anything core such as principles like CONTRIBUTING.md are fundamental to the Rocky Linux Docs and how the Docs work. It affects how users and maintainers interact with the Docs.

I was initially very resistant from wanting to use AI for the creation of anything - I'm a person that likes to learn and to create and test things himself, that's how I got my start in the wonderful world of Linux and open source.

However, in the IT / computing space, I've given in regarding that battle of resisting AI and have accepted that AI usage is now the norm from an efficiency standpoint and also from a quality of life point of view.

I think it is inevitable that AI generated code will end up on the Docs site / across the Rocky Linux infrastructure in some way, shape or form. How that is handled, I'll gladly add my opinion and I'm happy we're discussing it but ultimately I'd like to leave and will accept the final decision of the Docs, Infra and all the other team leads.

Another point I'd like to kindly highlight as well, I tracked the amount of hours I spent on this project and it was about 7 hours in total. That was going back and forth with the AI and making sure that human review was constantly kept in the chain and that improvements were made. This was not a project where I just placed what I wanted as a prompt into the AI and immediately pushed the end result as a commit without any human review.

I've received enough AI documents in my time which have clearly not had any human review and that always irked me. That's why whenever I create anything with AI, I ensure it goes through human review and testing by myself first, before it is passed along to another person.

My understanding (and reading) of that PR is that it is similar to the slurm document, but simply missing the clear notation in the beginning of the document.

That is right @sspencerwire , it is similar in scope to the slurm document.

I was discouraged by the dependencies listed early in the document - pip, npm, nodejs etc etc. Even if they are just nice-to-haves - it is too much. FOr example I don't want @ganna Zhyrnova dealing with that from a translators perspective.

@wale - good points as well and I can see where you are coming from - there are a lot of dependencies depending on the OS you are using and I can see where that can cause confusion. For me, when testing (I went through the same steps for the slurm-rocky.md that I submitted yesterday), these did work for me.

Great feedback and should I further edit CONTRIBUTING.md so that it more clearly says that the steps are a suggestion, rather than a mandatory setup and that ultimately the local setup should be what the end user is comfortable with?

Apologies for the long post here and I was replying to all of the excellent points raised. Thank you both so much!

[metalllinux]

@sspencerwire and @wsoyinka - when you have a free cycle available, please take a look at the updated PR. I have added the following feedback and further refined by removing sections such as Troubleshooting, which I thought were ultimately unnecessary:

Steven's feedback:

• Requested: Add front matter (title, author) → Done: Added title, author, tags in YAML front matter
• Requested: Add AI disclaimer at top → Done: Added "## AI Usage Disclosure" section at top
• Requested: Move file to docs/guides/contribute/ → Done: File is at docs/guides/contribute/contributing.md
• Requested: Rename to lowercase contributing.md → Done: Renamed from CONTRIBUTING.md to contributing.md

Wale's feedback:

• Requested: Remove dot files (.pyspelling.yml, .markdownlint.yml) → Done: Removed - PR only contains
  contributing.md

Your requests:

• Requested: Move Local Editors under Alternative Tooling → Done: Moved with heading levels adjusted
• Requested: Remove "contributors: Claude AI" from front matter → Done: Removed
• Requested: Change AI disclosure from admonition to heading → Done: Changed to "## AI Usage Disclosure"
• Requested: Remove "(Claude by Anthropic)" from AI text → Done: Changed to just "AI"
• Requested: Add Welcome heading above intro → Done: Added "## Welcome" heading
• Requested: "correctness." to "correctness of the content." → Done: Changed
• Requested: "erases the original author's voice and creates unnecessary churn." to "erases the original author's
  voice." → Done: Changed
• Requested: Remove ALL Troubleshooting sections → Done: Removed all 6 sections (~345 lines)
• Requested: Simplify Mattermost description → Done: Shortened to end at "help you with your document."

[sspencerwire]

Hey @metalllinux leave out the table of contents section. First, internal links (within the document) will break when translated. Second, the table of contents is always available in the right-hand menu once the document is opened. This avoids problems when the document is translated. Second, the level 1 heading (Contributing to the Rocky Linux Documentation) is not needed as it will be picked up from the "Title:" meta entry. Third, once the document is renamed to expert_contributing.md the title should be something on the order of "An experts guide to contributing" or something along those lines. (again, this should replace what is currently in the "Title:" meta. Fourth, (and I can fix this on an editing pass) Sentence style capitalization for the headers would be "AI usage disclosure", "Quick start", "Fork and clone the repository", etc. Again, you don't necessarily need to fix that as I can fix it in an editing pass. Finally, at the end of the document where you are referencing other documents within documentation, these can and should be done by backing up and referencing them, rather than with a full URL. I can fix this as well in editing, I just want you to be aware.

[metalllinux]

Hey @metalllinux leave out the table of contents section. First, internal links (within the document) will break when translated. Second, the table of contents is always available in the right-hand menu once the document is opened. This avoids problems when the document is translated. Second, the level 1 heading (Contributing to the Rocky Linux Documentation) is not needed as it will be picked up from the "Title:" meta entry. Third, once the document is renamed to expert_contributing.md the title should be something on the order of "An experts guide to contributing" or something along those lines. (again, this should replace what is currently in the "Title:" meta. Fourth, (and I can fix this on an editing pass) Sentence style capitalization for the headers would be "AI usage disclosure", "Quick start", "Fork and clone the repository", etc. Again, you don't necessarily need to fix that as I can fix it in an editing pass. Finally, at the end of the document where you are referencing other documents within documentation, these can and should be done by backing up and referencing them, rather than with a full URL. I can fix this as well in editing, I just want you to be aware.

Brilliant and thank you for the further edits there Steven and I will have those incorporated!

[metalllinux]

@sspencerwire - thank you and I have made the requested changes.

[github-actions]

Test results for 9875c4e:

Number of broken URLs: 12

URL,RESULT,FILENAME
 https://mirrors.fedoraproject.org/metalink?repo=epel-8&arch=$basearch&infra=$infra&content=$contentdir,failed,books/admin_guide/13-softwares.md
 https://www.getpagespeed.com/server-setup/varnish/varnish-virtual-hosts,failed,books/web_services/052-load-balancer-proxies-varnish.md
 https://support.torproject.org/glossary/pluggable-transports/,failed,guides/proxies/tor_relay.md
 http://your_ip,failed,guides/cms/mediawiki.md
 http://$(hostname):8080,failed,guides/repositories/pulp_fetch_upload.md
 https://dl.rockylinux.org/pub/rocky/9.6/live/x86_64/,failed,guides/desktop/kde_installation.md
 https://git.launchpad.net/cloud-init,failed,guides/virtualization/cloud-init/07_contributing.md
 https://ftp.gnu.org/gnu/tar/,failed,guides/backup/tar.md
 https://andyscott.me,failed,guides/contribute/README.md
 https://www.ssllabs.com/ssltest/,failed,guides/web/caddy.md
 https://ftp.gnu.org/gnu/hello/hello-2.12.tar.gz,failed,labs/systems_administration_I/lab7-software_management.md
 https://repocompare.rockylinux.org,failed,release_notes/8_5.md

[sspencerwire]

Well done! After giving this a lot of thought, it probably should have been in the local docs section of contribute, BUT, I can either move it there, or we can link to it. Thanks for considering all of the tone and changes.

[sspencerwire]

I missed this in the conversation, but there should have been no reason (that I can think of) why .pyspelling.yml and the update to the .markdownlink.yml files in the root would have needed to be removed. Let's discuss that after this is merged somewhere. Thanks again @metalllinux