Vai al contenuto

Contribution Guide

All Contributors

Introduction

So you want to contribute to the Rocky Linux documentation, but aren't sure how to go about that? You've come to the right place. We're excited to have you on board with us.

One of our main goals for Rocky is to have not just good but GREAT documentation, and we cannot do it alone. This document will get you started and will (hopefully) ease any worries you might have about doing so. We will always be here to help, so feel free to ask questions and join in the conversation.

Documentation Subjects

If you can dream it — or better yet, have done it before — then your subject is probably important to the Rocky Linux documentation project.

Where do you come in — both now and in the future? If you have experience with anything Linux-related and can translate that to Rocky Linux, we would like you to start writing!

Where to Start

While you can create documentation in any format (seriously, we will accept it any way you create it), the preferred format is Markdown. You can easily create documents in Markdown, plus Markdown is super-easy to learn. The best way to get started with Markdown is to have a Markdown editor installed and read the tutorial. You can create Markdown files with any text editor, but most Markdown editors allow you to preview what you've input already, so they can be very helpful.

Markdown Editor

As we've said already, the best way to create Markdown files, particularly if you've not done it before, is to grab an editor for the operating system that you use on your PC or Laptop. A simple web search for "Markdown editors" will show you a bunch to choose from.

Pick one to use that is compatible with your Operating System. ReText, a cross-platform Markdown editor, was used to create this document. Again, if you prefer to create your Markdown files in your text editor that you are already familiar with, that is just fine.

Alternate Markdown Editors

ReText is good, but if you feel like exploring your other options, there are a few:

  • Zettlr - Free, cross-platform, and open source
  • Mark Text - Free, cross-platform, and open source
  • Remarkable - Linux and Windows, open source
  • NvChad for the vi/vim user and the nvim client. A lot of plugins are available to enhance the editor for markdown. See this document for a nice set of installation instructions.
  • VS Code - A partially open source project from none other than Microsoft; VS Code is a lightweight and powerful editor available for Windows, Linux and MacOS. To contribute to this document project, you should get the following extensions: Git Graph, HTML Preview, HTML Snippets, Markdown All in One, Markdown Preview Enhanced, Markdown Preview Mermaid Support, and any more that catch your fancy.

Markdown Tutorial

You can get a good feel for how to write Markdown files, by taking a look at Mastering Markdown. This online resource will get you up-to-speed in no time.

Admonitions and Translations

Towards the end of 2021, we started translating our documents using Crowdin. We need more translators for this effort, so if you would like to translate these documents into your language, please consider joining that effort. You can find more information by joining the conversation here.

It should be noted that admonitions are NOT required, but if you choose to use them, they should be formatted a little differently than the default. Here is the default way of creating an admonition:

!!! type "optional additional title within double quotes"
    Any number of other indented markdown elements.
To make this work for our translators in Crowdin, however, we need to format it like this:
!!! type "optional additional title within double quotes"

    Any number of other indented markdown elements.
The first line of the text detail for the admonition must have that extra line feed. Note that each example shows that there are 4 spaces before the actual text begins. When the page is rendered, the document will not have the extra line feed. Here's what the admonition above looks like:

optional additional title within double quotes

Any number of other indented markdown elements.

If you are reading this on GitHub, it will not display the admonition. You can see how it actually displays here.

Author, Contributor, and Other Meta Content

We started to add specific meta to our documentation some time ago. The idea is to get the primary information in the meta. This is done in the source (English) documents. Here's an example of the meta information as it currently stands:

---
title: Document title or the title that appears in the table of contents. (this can be overridden with `.pages` by editors if necessary.) 
author: the author of the source (English) version of the document.
contributors: a comma separated list of contributors to the source document.
tested with: a comma separated list of versions example: 8.6, 9.0
tags: 
  - displayable tags
  - these are also searchable
  - they are two space indented and start with a "-" as shown here
  - generally, they should be one word
---

We ask those involved in translations to leave the meta as is in the document you are translating. We definitely DO want to acknowledge those involved in our translation efforts! That is what the all-contributors bot is for. If you scroll to the bottom of this page, you'll see a list of those who have contributed to the documentation project, even if it was just to change a word or phrase or fix an error.

If a translator runs into a word or phrase that does not translate well from the source document to their language, we ask them to go ahead and push a change to the source document through the normal Git processes. When they do this, they definitely should add their name to the "contributors:" meta!

If you notice that your effort is not properly acknowledged in the all-contributors section, please let someone know in the Mattermost channel so that we can fix it for you. Thank you to everyone who participates!

When writing documentation you often need to use links. This can be links to other documents in the documentation (internal links), or links to external resources (external links). The format for all links within the documentation is square brackets around the descriptive name or label: [our site] followed by your link in parenthesis: (https://example.com). There's a third type of link which we will call a lab-based link. This is a link that does not resolve internally or externally, but refers to examples within your document. In October 22, we instituted a URL checking script within our GitHub PR test process. This script tests for failures of URLs and is great for keeping the documentation clean and accurate. It poses a special set of circumstances for lab-based URLs, however, as those lab-based URLs need to either fit within a set of already excluded names, or the author (you) would need to request that a new exclusion be added. An editor can also adjust your lab-based URL for you, or add an exclusion if they think it is warranted.

The following list of lab-based URLs can be used without requesting exceptions:

  • example.com
  • site.com
  • site1.com
  • site2.com
  • apache-server
  • nginx-server
  • your-server-ip
  • your-server-hostname
  • localhost

Using Git

Like many other projects out there, Rocky Linux uses "git" to manage its code and files, including documentation files. This tutorial assumes a fundamental knowledge of Git and how it works. The second example also presupposes familiarity with the command line.

The steps listed below will get you started. In the meantime (and until we inevitably develop our guide), you can learn Git in-depth with this free Udacity course. If you don't have the time for that, here's a shorter guide.

To submit your text, we ask that you create a GitHub account. When you are ready to submit your written documentation for approval, follow these easy steps:

With the GitHub GUI

You can complete almost all tasks from the web GUI on GitHub. Here's an example of adding a file you've created on your local machine to the Rocky Linux documentation GitHub repository.

  1. log in to your GitHub account.
  2. Navigate to the Rocky Linux Documentation repository at https://github.com/rocky-linux/documentation.git
  3. You should be on the "Main" branch, so check the drop-down label down in the middle section to be sure you are. Your document might not ultimately end up in the "Main" branch, but admins will move it around to where it logically fits later.
    On the right-hand side of the page, click the "Fork" button, which will create your copy of the documentation.
  4. In the middle of the page on the forked copy, just to the left of the Green "Code" drop-down, is an "Add file" button. Click this and choose the "Upload files" option.
  5. This will give you a way to either drag and drop files here or browse to them on your computer. Go ahead and use the method which you prefer.
  6. Once the file is uploaded, the next thing you need to do is create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master.
    Click on "Pull Request" in the upper-left of the screen.
  7. Write a brief message in the "Write" section letting the administrators know what you've done. (New document, revision, suggested change, etc.,) then submit your change.

From the Git Command-Line

If you prefer to run Git locally on your machine, you can clone the Rocky Linux Documentation repository, make changes, and then commit changes afterward. To make things simple, execute steps 1-3 on from With the GitHub GUI above then:

  1. Git clone the repository: git clone https://github.com/your_fork_name/documentation.git
  2. Now, on your machine, add files to the directory.
    Example: mv /home/myname/help.md /home/myname/documentation/
  3. Next, run Git add for that file name.
    Example: git add help.md
  4. Now, run git commit for the changes you have made.
    Example: git commit -m "Added the help.md file"
  5. Next, push your changes to your forked repository: git push https://github.com/your_fork_name/documentation main
  6. Next, we repeat steps 6 and 7 above: Create a Pull Request. This request lets the upstream administrators know that you have a new file (or files) that you would like them to merge with the master branch. Click on "Pull Request" in the upper-left of the screen

Once all of the above is complete, you wait for confirmation that GitHub successfully merged your request. (Or not, as the case may be.)

More Advanced Documents

If you are wanting to add more advanced elements in your document than just text (admonitions, tables, block quotes, etc.), this document will help you get there.

Documentation Local Server

The advantage of having documentation running on a local server instance is that you get to see how your changes will look when they are taken to the live system. You can build a complete documentation system on your local Linux workstation or VM. This procedure isn't for everyone, and is definitely a more advanced topic. There are two documents that will get you to a nice, complete, and protected documentation system, using either Docker or LXD:

There is a third method that will get you up and running fast without either Docker or LXD, but read the caveats of this procedure carefully:

  • Fast Documentation System here

Keep Up With The Conversation

If you haven't already, join the conversation on the Rocky Linux Mattermost Server and stay up-to-date with what is going on. Join the ~Documentation channel, or any other channel you are interested in. We'd be glad to have you with us!

Contributors ✨

Thanks goes to these wonderful people (emoji key):

wale soyinka
wale soyinka

📆 🚧 🖋
sspencerwire
sspencerwire

📆 🚧 🖋
Ezequiel Bruni
Ezequiel Bruni

🚧 🖋
ambaradan
ambaradan

🌍
Antoine Le Morvan
Antoine Le Morvan

🖋 🌍
tianci li
tianci li

🖋 🌍
student
student

🖋
NezSez
NezSez

🖋 🤔
justasojourner
justasojourner

🖋 🤔
Neil Hanlon
Neil Hanlon

🖋 🚧 🤔
Peter Ajamian
Peter Ajamian

🖋
Flávio Siqueira Prado
Flávio Siqueira Prado

🌍
Norio4
Norio4

🌍
Sébastien Pascal-Poher
Sébastien Pascal-Poher

🌍
Lucas Trecanao
Lucas Trecanao

🌍
calderds
calderds

🖋 👀
execion
execion

🌍
lillolollo
lillolollo

🖋
Ahmed alBattashi
Ahmed alBattashi

🖋
StackKorora
StackKorora

🖋
3xtant
3xtant

🖋
almrv
almrv

🌍
Hayden
Hayden

🖋
Louis Abel
Louis Abel

🖋
Ron
Ron

🖋
Amin Vakil
Amin Vakil

🖋
K.Prasad
K.Prasad

🖋
IncorrigiblyBelligerent
IncorrigiblyBelligerent

🖋
Jairo Nonato Júnior
Jairo Nonato Júnior

🖋
Saif Eddine Halila
Saif Eddine Halila

🖋
DrCool2
DrCool2

🖋
codedude
codedude

🖋
Graham
Graham

🖋
Aditya Putta
Aditya Putta

🖋
yangxuan74
yangxuan74

🖋
Morgan Read
Morgan Read

🖋
9p4
9p4

🖋
Alex Zimmerman
Alex Zimmerman

🖋
Andrew Faulkner
Andrew Faulkner

🖋
Todd Levi
Todd Levi

🖋
tahder
tahder

🖋
Takahiro Yoshihara
Takahiro Yoshihara

🖋
Gerard Arthus
Gerard Arthus

🖋
HadManySons
HadManySons

🖋
Brandon Mayfield
Brandon Mayfield

🖋
Anthony Staunton
Anthony Staunton

🖋
whg517
whg517

🖋
MrSkribb
MrSkribb

🖋
jules
jules

🖋
Brendan Fattig
Brendan Fattig

🖋
bittin
bittin

🖋
ichibariki
ichibariki

🖋
Bernat Puigdomenech Pascual
Bernat Puigdomenech Pascual

🖋
Dennis Körner
Dennis Körner

🖋
Pedro Bezunartea López
Pedro Bezunartea López

🌍
Daniel Pogac
Daniel Pogac

🖋
oats
oats

🖋
Alex Harden
Alex Harden

🖋
Jordan Pisaniello
Jordan Pisaniello

🖋
Richard Hennig
Richard Hennig

🖋
caffenix
caffenix

🖋
Lento Manickathan
Lento Manickathan

🖋
Alan Sill
Alan Sill

🖋
Ikko Ashimine
Ikko Ashimine

🖋
William Perron
William Perron

🖋
Roman Gherta
Roman Gherta

🖋
Yiğit can BAŞALMA
Yiğit can BAŞALMA

🖋
markooff
markooff

🖋 🌍
Deng Wenbin
Deng Wenbin

🌍
alikates
alikates

🖋
hopnux
hopnux

🌍
Pedro Garcia Rodriguez
Pedro Garcia Rodriguez

🌍
Lau
Lau

🖋
Serge Croisé
Serge Croisé

🖋
bamtests
bamtests

🖋
jahway603
jahway603

🖋
Nejc Bertoncelj
Nejc Bertoncelj

🖋
Dan Baker
Dan Baker

🖋
Laura Hild
Laura Hild

🖋
Grammaresque
Grammaresque

🖋

This project follows the all-contributors specification. Contributions of any kind welcome!


Ultimo aggiornamento: 3 dicembre 2022