Merge branch 'theforeman:master' into ansible-diff-mode-doc

Author: bnerickson

.github/ISSUE_TEMPLATE/report-issue.md

@@ -0,0 +1,16 @@
+---
+name: Report issue
+about: Report issues in upstream Foreman/Katello documentation
+title: ''
+labels: direct user feedback
+assignees: ''
+
+---
+
+#### URL of the document
+
+#### Optional: Copy-paste the text you are reading
+
+#### Describe the issue
+
+#### Anything else to add? (context, suggestions for a fix, etc.)

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,19 +4,32 @@
 
 #### Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
 
-#### Checklists
+#### Contributor checklists
 
 * [x] I am okay with my commits getting squashed when you merge this PR.
 * [ ] I am familiar with the [contributing](https://github.com/theforeman/foreman-documentation/blob/master/CONTRIBUTING.md) guidelines.
 
 Please cherry-pick my commits into:
 
-* [ ] Foreman 3.14/Katello 4.16
+* [ ] Foreman 3.16/Katello 4.18 (Satellite 6.18)
+* [ ] Foreman 3.15/Katello 4.17
+* [ ] Foreman 3.14/Katello 4.16 (Satellite 6.17)
 * [ ] Foreman 3.13/Katello 4.15 (EL9 only)
-* [ ] Foreman 3.12/Katello 4.14 (Satellite 6.16)
+* [ ] Foreman 3.12/Katello 4.14 (Satellite 6.16; orcharhino 7.2 on EL9 only; orcharhino 7.3)
 * [ ] Foreman 3.11/Katello 4.13 (orcharhino 6.11 on EL8 only; orcharhino 7.0 on EL8+EL9; orcharhino 7.1 with Leapp)
 * [ ] Foreman 3.10/Katello 4.12
 * [ ] Foreman 3.9/Katello 4.11 (Satellite 6.15; orcharhino 6.8/6.9/6.10)
-* [ ] Foreman 3.8/Katello 4.10
-* [ ] Foreman 3.7/Katello 4.9 (Satellite 6.14)
-* We do not accept PRs for Foreman older than 3.7.
+* We do not accept PRs for Foreman older than 3.9.
+
+#### Review checklists
+
+Tech review (performed by an Engineer who did not author the PR; can be skipped if tech review is unnecessary):
+
+* [ ] The PR documents a recommended, user-friendly path.
+* [ ] The PR removes steps that have been made unnecessary or obsolete.
+* [ ] Any steps introduced or updated in the PR have been tested to confirm that they lead to the documented end result.
+
+Style review (by a Technical Writer who did not author the PR):
+
+* [ ] The PR conforms with the team's style guidelines.
+* [ ] The PR introduces documentation that describes a user story rather than a product feature.

.github/workflows/deploy.yml

@@ -22,7 +22,7 @@ jobs:
       image: quay.io/ivanhorvath/ccutil:amazing
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Compile html-single
         run: make -C guides ccutil -j ${{ env.MAKE_J }}
@@ -45,7 +45,7 @@ jobs:
         working-directory: .
 
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
@@ -102,7 +102,7 @@ jobs:
         working-directory: guides
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           ref: ${{ github.base_ref }}
 
@@ -130,11 +130,16 @@ jobs:
   build-web:
     runs-on: ubuntu-24.04
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - name: Checkout master
+        if: github.event_name != 'pull_request' || github.base_ref != 'master'
+        uses: actions/checkout@v5
         with:
           ref: master
 
+      - name: Checkout PR
+        if: github.event_name == 'pull_request' && github.base_ref == 'master'
+        uses: actions/checkout@v5
+
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1
         with:
@@ -180,13 +185,13 @@ jobs:
 
       - name: Download web (only for master)
         if: github.ref == 'refs/heads/master'
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: foreman-docs-web-${{ env.BRANCH_NAME }}
           path: public
 
       - name: Download HTML
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v5
         with:
           name: foreman-docs-html-${{ env.BRANCH_NAME }}
           path: public/${{ env.BRANCH_NAME }}

.github/workflows/linkchecker.yml

@@ -20,7 +20,7 @@ jobs:
         working-directory: guides
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: Setup Ruby
         uses: ruby/setup-ruby@v1

.github/workflows/preview.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion != 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Download metadata artifact
         run: gh run download '${{ github.event.workflow_run.id }}' -n pr
@@ -32,7 +32,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request' && github.event.workflow_run.conclusion == 'success'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Download metadata artifact
         run: gh run download '${{ github.event.workflow_run.id }}' -n pr

.github/workflows/unused.yml

@@ -0,0 +1,18 @@
+---
+name: Unused modules
+on:
+  pull_request:
+    paths:
+      - 'guides/**.adoc'
+      - '.github/workflows/unused.yml'
+
+jobs:
+  vale:
+    name: Unused modules
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v5
+      - name: Install Asciidoctor
+        run: sudo apt-get install -y asciidoctor
+      - name: Find unused modules
+        run: ./guides/scripts/find_unused_modules

.github/workflows/vale.yml

@@ -13,7 +13,7 @@ jobs:
     name: linter
     runs-on: ubuntu-24.04
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
       - name: Install Asciidoctor
         run: sudo apt-get install -y asciidoctor
       - uses: errata-ai/vale-action@v2

CONTRIBUTING.md

@@ -12,12 +12,13 @@ We respect each others time and energy spent on Foreman documentation.
 * help less experienced community members with git, Github, PRs, asciidoc, and asciidoctor.
 * expect a basic effort in contributions, including the [pull request template](PULL_REQUEST_TEMPLATE.md) being filled out.
 * only merge PRs if the Github Actions are green.
-* only merge PRs that have the `style review done` and `tech review done` labels set, indicating that a technical author has provided editorial review and a subject matter expert (SME) has provided technical review.
 For an overview of what to expect from editorial review, see [Red Hat peer review guide for technical documentation](https://redhat-documentation.github.io/peer-review/#checklist).
 * read the proposed change and make friendly and helpful comments.
 * ping community members with more experience if they are unsure about specific details.
 * try to review PRs in a timely manner.
-* keep non-trivial PRs open for at least 24 hours to allow for input from the community.
+* keep non-trivial PRs open for at least 24 hours (72 hours if over the weekend) to allow for input from the community.
+Examples of trivial PRs: Fixing a typo, fixing markup, or fixing links.
+Non-trivial PRs might not only benefit from additional review but they also represent an opportunity for community members to ask questions and learn.
 
 ## Contributors
 
@@ -46,6 +47,7 @@ See [LICENSE](LICENSE).
 * [ ] When creating my PR, I select all branches I want my change to get cherry-picked to.
 * [ ] I am familiar to proper capitalization for project-specific terminology.
 See [Capitalization](#Capitalization).
+* [ ] The first line of the file contains the modular docs content type attribute, for example, `:_mod-docs-content-type: ASSEMBLY` for assemblies.
 
 ## Capitalization
 

Makefile

@@ -1,7 +1,7 @@
 SHELL := /bin/bash
 DEST := result
 PORT := 5000
-VERSION_LINKS := 3.14 3.13 3.12 3.11 3.10 3.9 3.8 3.7 3.6 3.5 3.4 3.3 3.2 3.1 3.0 2.5 2.4
+VERSION_LINKS := 3.16 3.15 3.14 3.13 3.12 3.11 3.10 3.9 3.8 3.7 3.6 3.5 3.4 3.3 3.2 3.1 3.0 2.5 2.4
 
 .PHONY: all clean html web compile serve prep FORCE toc
 

README.md

@@ -1,6 +1,6 @@
 # Foreman documentation
 
-This git repository contains the following documentation:
+This Git repository contains the following documentation:
 
 * Official documentation for the Katello project
 * PoC of improving documentation for the Foreman project. See [this milestone](https://github.com/theforeman/foreman-documentation/milestone/3) to check the progress.
@@ -16,32 +16,35 @@ Please, familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) and [Contribut
 
 ### Foreman guides
 
-This is a tree of documentation based on Red Hat Satellite 6 official books.
-See [README in the `guides/` subdirectory](guides/README.md) for more information.
+For information on working with the Foreman guides, see the [README in the `guides/` subdirectory](guides/README.md).
 
 ### Static site
 
 The landing page for [docs.theforeman.org](https://docs.theforeman.org) is available as a generated static site.
 The static content is always built from the `master` branch.
 See [README in the `web/` subdirectory](web/README.md) for more information.
 
-## Testing locally
+## Testing the site locally
 
-To build both static site and guides for easy local testing, there is the global `Makefile` in the root directory with the following targets:
+To build both the static site and the guides for easy local testing, a global `Makefile` is provided in the root directory with the following targets:
 
 * `html`: builds HTML guides with all contexts (`foreman-el`, `foreman-deb`, `katello`, `satellite`, and `orcharhino`)
 * `web`: builds static site using the `nanoc` tool
 * `compile`: compiles all content into a single directory `./result`
 * `serve`: serves the result directory via a python web server (the default target)
 
-To test the whole site locally, perform `make serve` command and open up `http://localhost:5000`.
+To use the `Makefile`, you must first install the `gcc`, `gcc-c++`, and `ruby-devel` packages.
+Then, to test the entire site locally, perform `make serve` command and open up `http://localhost:5000`.
 Use `PORT=5008` to change the web server port (5000 by default).
-It builds all contexts so the initial build can be slow, make sure to use `-j` option for faster builds on modern multi-core machines.
-Stable versions are symlink to the nightly (current) version, this can cause issues for deleted (or renamed) guides.
+This builds all contexts, so the initial build might be slow. 
+For faster builds on modern multi-core machines, use the `-j` option.
+Stable versions are symlinks to the nightly (current) version, which can cause issues for deleted (or renamed) guides.
+
+For instructions on locally building only the guides, see [Building locally](https://github.com/theforeman/foreman-documentation/blob/master/guides/README.md#building-locally).
 
 ## Deployment
 
-Github actions perform HTML (with link validation) and WEB artifact creation and if succeeded and branch is master or stable, artifacts are downloaded, extracted and deployed (commited into gh-pages). Deployment does not delete files, in order to remove some unwanted content, manual deletion and push into gh-pages must be performed.
+GitHub actions perform HTML (with link validation) and WEB artifact creation and if succeeded and branch is master or stable, artifacts are downloaded, extracted and deployed (commited into gh-pages). Deployment does not delete files, in order to remove some unwanted content, manual deletion and push into gh-pages must be performed.
 
 When a commit is pushed into `master`:
 
@@ -55,14 +58,14 @@ When a commit is pushed into `X.Y`:
 * HTML artifact is downloaded and copied into `/X.Y`.
 * Changes are pushed into `gh-pages` branch.
 
-## Branching new release
+## Branching a new release
 
 * On `master`, pull the latest changes and create a new `X.Y` branch.
-* On `X.Y`:
+* On the `X.Y` branch:
   * Update `guides/common/attributes.adoc`.
-    * Set `DocState` to `unsupported`.
+    * Set `DocState` to `RC`.
     * Set `ProjectVersion` to `X.Y` and set the matching `KatelloVersion`.
-  * Push into `X.Y` branch.
+  * Push into the `X.Y` branch.
   * Notify the Doc team on the [TheForeman Doc chat](https://matrix.to/#/#theforeman-doc:matrix.org) Matrix channel.
 * On `master`:
   * Update `ProjectVersionPrevious` to `X.Y` in `guides/common/attributes.adoc`.
@@ -71,7 +74,6 @@ When a commit is pushed into `X.Y`:
     * Change `katello` to the right version.
     * Change `Nightly` in titles to the appropriate version.
     * Remove guides which aren't ready for stable branches.
-  * Create a copy of [/web/releases/nightly.adoc](https://github.com/theforeman/foreman-documentation/tree/master/web/releases/nightly.adoc) as `X.Y.adoc` and edit it accordingly. Remove guides which aren't ready for stable branches.
   * Test the changes by following the instructions in [/web/README.md](https://github.com/theforeman/foreman-documentation/tree/master/web/README.md) to deploy the website locally.
   * Add the new Foreman version to [/.github/PULL_REQUEST_TEMPLATE.md](https://github.com/theforeman/foreman-documentation/blob/master/.github/PULL_REQUEST_TEMPLATE.md).
   * Update `VERSION_LINKS` in the root `Makefile`.
@@ -80,4 +82,4 @@ When a commit is pushed into `X.Y`:
 
 ## License
 
-See LICENSE files in individual subdirectories.
+See LICENSE files in the respective subdirectories.