Consolidate readmes and contribution guidelines #4281

aneta-petrova · 2025-09-19T12:31:47Z

What changes are you introducing?

This PR looks at the existing readmes and contribution documents and attempts to make it easier to navigate through them. As a result, there are now:

3 readme files: one generic, one for guides/, one for web/, each with an introduction explaining their purpose (hinting at how they differ)
1 contributing document, which now contains instructions for contributors and maintainers, including Foreman docs' own style guide
The Foreman docs minimalist style guide is new and is home to various pieces of markup and style conventions that were before located in different places.

One new thing that I'm adding is an explanation for the CP checklist in the PR template, to address #3219

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

To better separate types of information: readmes are for how to work with the repo; contributing is for how to contribute; style guide is for Foreman documentation conventions.

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Hopefully the next step would be to review the style guide part to remove redundant information and duplicates. I found a few but I haven't really focused on that yet so if you spot something that could be dropped, I'd be happy to do so.

Contributor checklists

I am okay with my commits getting squashed when you merge this PR.
I am familiar with the contributing guidelines.

Please cherry-pick my commits into:

Foreman 3.16/Katello 4.18 (Satellite 6.18)
Foreman 3.15/Katello 4.17
Foreman 3.14/Katello 4.16 (Satellite 6.17; orcharhino 7.4)
Foreman 3.13/Katello 4.15 (EL9 only)
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)
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.

It duplicates the general readme

aneta-petrova · 2025-09-19T12:34:52Z

CONTRIBUTING.md

+* [ ] I fill out the cherry-picking list in the PR template to the best of my abilities to signify which versions my update applies to.
+If unsure, I let reviewers know so that they can assist.
+
+## Foreman documentation minimalist style guide


Potential reviewers: Note that all these style conventions have been moved from another document. I didn't write them and I'd like to avoid tweaking how they are worded 🙃 If anyone would like to see the wording improved, I'd suggest doing it in another PR. Thanks for understanding!

However, as noted in the PR description, I'd be happy to remove lines that are obsolete or redundant.

github-actions · 2025-09-19T12:36:56Z

The PR preview for 093bb0c is available at theforeman-foreman-documentation-preview-pr-4281.surge.sh

No diff compared to the current base

show diff

maximiliankolb

some comments, overall LGTM!

maximiliankolb · 2025-09-19T14:01:16Z

CONTRIBUTING.md

+| {ProjectName} | Foreman | Red Hat Satellite | orcharhino |
+| {ProjectServer} | Foreman server | Satellite Server | orcharhino server |
+| {SmartProxy} | Smart Proxy | Capsule | orcharhino Proxy |
+| {SmartProxyServer} | Smart Proxy server | Capsule Server | orcharhino Proxy |


Suggested change

| {SmartProxyServer} | Smart Proxy server | Capsule Server | orcharhino Proxy |

| {SmartProxyServer} | Smart Proxy server | Capsule Server | orcharhino Proxy Server |

Was changed recently via dbb63cf

maximiliankolb · 2025-09-19T14:01:27Z

CONTRIBUTING.md

+| -------- | -------------- | --------------------- | ------------------ |
+| {Project} | Foreman | Satellite | orcharhino |
+| {ProjectName} | Foreman | Red Hat Satellite | orcharhino |
+| {ProjectServer} | Foreman server | Satellite Server | orcharhino server |


Suggested change

| {ProjectServer} | Foreman server | Satellite Server | orcharhino server |

| {ProjectServer} | Foreman server | Satellite Server | orcharhino Server |

maximiliankolb · 2025-09-19T14:03:14Z

CONTRIBUTING.md

+* [`proc`](https://redhat-documentation.github.io/modular-docs/#creating-procedure-modules): Files starting with `proc_` contain procedures and explain _how_ to achieve a specific goal.
+Their first line contains the `:_mod-docs-content-type: PROCEDURE` attribute.
+See the [procedure template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc).
+* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, e.g. tables with options.


Suggested change

* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, e.g. tables with options.

* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, for example, tables with options.

maximiliankolb · 2025-09-19T14:03:29Z

CONTRIBUTING.md

+* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, e.g. tables with options.
+Their first line contains the `:_mod-docs-content-type: REFERENCE` attribute.
+See the [reference template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc).
+* [`snip`](https://redhat-documentation.github.io/modular-docs/#using_text_snippets_or_text_fragments_writing-mod-docs): Files starting with `snip_` contain snippets that are reused throughout multiple guides, e.g. admonitions.


same as above.

maximiliankolb · 2025-09-19T14:04:00Z

CONTRIBUTING.md

+Their first line contains the `:_mod-docs-content-type: REFERENCE` attribute.
+See the [reference template](https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_REFERENCE_reference-material.adoc).
+* [`snip`](https://redhat-documentation.github.io/modular-docs/#using_text_snippets_or_text_fragments_writing-mod-docs): Files starting with `snip_` contain snippets that are reused throughout multiple guides, e.g. admonitions.
+Snippets do not require an ID.


Suggested change

Snippets do not require an ID.

Snippets must do not contain any anchors.

maximiliankolb · 2025-09-19T14:04:36Z

README.md

-Contributions are welcome.
-Please, familiarize yourself with [CONTRIBUTING](CONTRIBUTING.md) and [Contribution Guidelines for Foreman guides](guides/README.md#contribution-guidelines).
+We give ourselves these guidelines to collaborate and contribute to Foreman documentation more efficiently.
+It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organisations and backgrounds.


Suggested change

It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organisations and backgrounds.

It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organizations and backgrounds.

maximiliankolb · 2025-09-19T14:05:35Z

README.md


 ## Branching a new release

+When a new Foreman version is released, the Foreman release owner ensures that a new branch for documentation is created.


Suggested change

When a new Foreman version is released, the Foreman release owner ensures that a new branch for documentation is created.

When a new Foreman version is branched, the Foreman release owner ensures that a new branch for documentation is created.

maximiliankolb · 2025-09-19T14:06:12Z

web/README.md

 the changes and all guides and pages will dynamically load the menu from the
 data structure.
+
+To test full site with guides, use the Makefile in the root directory. See [README](../README.md) for more information.


Suggested change

To test full site with guides, use the Makefile in the root directory. See [README](../README.md) for more information.

To test full site with guides, use the Makefile in the root directory.

See [README](../README.md) for more information.

maximiliankolb · 2025-09-19T14:08:13Z

CONTRIBUTING.md

line 28: Please change + to *.

aneta-petrova added 12 commits September 18, 2025 20:16

Restructure main readme

46cb0d5

Clarify that a procedure is in a different readme

e88bedf

Clean up 'contributing'

876b3ea

Create 'minimalist style guide'

6ba54dd

Add introductions to 2 readme files

0fc09a1

Remove guides/README intro

d340853

It duplicates the general readme

Add explanation about CP'ing

c6b61ee

Remove unmaintained RH resources

64161bc

Remove obsolete advice

098c60f

Drop and move redundant 'contributing guideliens'

95d95f2

Drop image naming guidelines that nobody seems to follow

9701f9b

Merge content type info with modular file info

71ee601

pr-processor bot added the Not yet reviewed label Sep 19, 2025

github-actions bot added Needs tech review Requires a review from the technical perspective Needs style review Requires a review from docs style/grammar perspective Needs testing Requires functional testing labels Sep 19, 2025

aneta-petrova commented Sep 19, 2025

View reviewed changes

pr-processor bot removed the Not yet reviewed label Sep 19, 2025

This was linked to issues Sep 19, 2025

Consolidate and update "Contributing" docs (in progress) #3177

Open

Review contribution guidelines for cherry-picking #3219

Open

Move review checklist to PR checklist

093bb0c

maximiliankolb reviewed Sep 19, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Consolidate readmes and contribution guidelines #4281

Consolidate readmes and contribution guidelines #4281

Uh oh!

aneta-petrova commented Sep 19, 2025

Uh oh!

aneta-petrova Sep 19, 2025

Uh oh!

github-actions bot commented Sep 19, 2025 •

edited

Loading

Uh oh!

maximiliankolb left a comment

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

maximiliankolb Sep 19, 2025

Uh oh!

Uh oh!

	\| {SmartProxyServer} \| Smart Proxy server \| Capsule Server \| orcharhino Proxy \|
	\| {SmartProxyServer} \| Smart Proxy server \| Capsule Server \| orcharhino Proxy Server \|

	\| {ProjectServer} \| Foreman server \| Satellite Server \| orcharhino server \|
	\| {ProjectServer} \| Foreman server \| Satellite Server \| orcharhino Server \|

	* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, e.g. tables with options.
	* [`ref`](https://redhat-documentation.github.io/modular-docs/#creating-reference-modules): Files starting with `ref_` contain references and append other files, for example, tables with options.

	Snippets do not require an ID.
	Snippets must do not contain any anchors.

	It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organisations and backgrounds.
	It helps everyone to set expectations, communicate conventions, and ensures happy collaborative work across organizations and backgrounds.


		## Branching a new release

		When a new Foreman version is released, the Foreman release owner ensures that a new branch for documentation is created.

	When a new Foreman version is released, the Foreman release owner ensures that a new branch for documentation is created.
	When a new Foreman version is branched, the Foreman release owner ensures that a new branch for documentation is created.

	To test full site with guides, use the Makefile in the root directory. See [README](../README.md) for more information.
	To test full site with guides, use the Makefile in the root directory.
	See [README](../README.md) for more information.

Consolidate readmes and contribution guidelines #4281

Are you sure you want to change the base?

Consolidate readmes and contribution guidelines #4281

Uh oh!

Conversation

aneta-petrova commented Sep 19, 2025

What changes are you introducing?

Why are you introducing these changes? (Explanation, links to references, issues, etc.)

Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)

Contributor checklists

Review checklists

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

maximiliankolb left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented Sep 19, 2025 •

edited

Loading