centos/docs-contributors-guide

CentOS Stream Contributor's Guide

This repository contains sources to the CentOS Stream Contributor's Guide, published at https://docs.centos.org/en-US/docs/.

Structure

|-- README.md
|-- antora.yml ....................... 1.
|-- build.sh ......................... 2.
|-- preview.sh ....................... 3.
|-- site.yml ......................... 4.
`-- modules
    `-- ROOT ......................... 5.
        |-- assets
        |   `-- images ............... 6.
        |       `-- pizza.png
        |-- nav.adoc ................. 7.
        `-- pages .................... 8.
            |-- architecture.adoc
            |-- community.adoc
            |-- faq.adoc
            |-- index.adoc
            |-- pizza-dough.adoc
            `-- pizza-oven.adoc

1. Metadata definition.
2. A script that does a local build. Uses docker.
3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker.
4. A definition file for the build script.
5. A "root module of this documentation component". Please read below for an explanation.
6. Images to be used on any page.
7. Menu definition. Also defines the hierarchy of all the pages.
8. Pages with the actual content. They can be also organised into subdirectories if desired.

Components and Modules

Antora introduces two new terms:

• Component — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity.
• Module — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories.

Local preview

This repo includes scripts to build and preview the contents of this repository.

Both scripts work on Fedora/CentOS (using Podman) and macOS (using Docker).

To build and preview the site, run:

$ ./build.sh && ./preview.sh

The result will be available at http://localhost:8080

Installing Podman

Podman probably is not installed on your system by default. To install it, run:

$ sudo dnf install podman

Then, reboot your system.

docs-contributors-guide's Issues

Wrong manual

This page:
https://docs.centos.org/en-US/stream-contrib/quickstart/#_3_reference_the_bugzilla_you_filed_in_your_commits

Says that commits must contain a rh bz like this:
git commit --signoff -m 'This is my awesome patch, Related: rhbz#123456
git commit --signoff -m 'This is another patch to the same bug, Fixes: #123456 (The checkers let me leave off the rhbz prefix)'

That is incorrect. The Related: rhbz#123456 or equivalent must be at the beginning of the line. Otherwise it does not work:
https://gitlab.com/redhat/centos-stream/rpms/vsftpd/-/merge_requests/9/pipelines

Quickstart doesn't clarify what contributions are wanted

I was trying to understand what CentOS Stream is for and how/whether to contribute, so I started from https://docs.centos.org/en-US/stream-contrib/quickstart/ but I quickly got disoriented and left with more questions than answers.

Based on a discussion at https://fosstodon.org/@carlwgeorge/110709163210683776, I think the main issue is that I don't understand what kind of contributions are desirable in CentOS Stream as opposed to elsewhere.

Use case

I'm looking for a certain update that I know exists upstream, like a patch for a known CVE with an existing tracking bug in https://bugzilla.redhat.com/. I want to ensure it's on its way to my RHEL and Fedora oldstable systems and that it doesn't break my things.

Expected behaviour

Not sure. Maybe https://gitlab.com/redhat/centos-stream/rpms/ should be more like https://bodhi.fedoraproject.org and https://src.fedoraproject.org/rpms/ . Maybe I just need an explanation of what kind of patches live here and where to look whether one is being baked already. Maybe I just need reassurance that if I file a bug or patch in the wrong component it will be redirected where it belongs.

Background

I've read

• https://almalinux.org/blog/future-of-almalinux/
• https://quantum-integration.org/the-curse-of-bug-to-bug-compatibility

which hopefully gave me an idea of what CentOS Stream could be useful for.

Broken link in source-git doc

https://docs.centos.org/en-US/stream-contrib/contributing/source-git/ links to https://git.centos.org/rpms but that URL gives a 404. It's interesting because there are repos are under rpms/, but that URL alone doesn't show anything.