From 3d2fc87f0bdc3f521cba73235712efa0867133c3 Mon Sep 17 00:00:00 2001 From: deerskindoll Date: Fri, 29 Aug 2025 00:06:38 +0200 Subject: [PATCH 01/12] removed additional resources --- README.adoc | 116 ++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 108 insertions(+), 8 deletions(-) diff --git a/README.adoc b/README.adoc index 15d2900775..f4574273bd 100644 --- a/README.adoc +++ b/README.adoc @@ -1,26 +1,126 @@ # Red Hat Developer Hub documentation -This repo is the upstream mirror of https://gitlab.cee.redhat.com/red-hat-developers-documentation/rhdh +This is a repo for Red Hat Developer (RHDH) documentation. -Contribute to this repo and merged changes will be synced to gitlab for build with Pantheon. +## Contributing + +Contribute to this repo to add new and edit existing RHDH documentation published on the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/[Red Hat Documentation page]. + +Before submitting a PR, create a Jira issue associated with your contribution to this repo: + +. In the link:https://issues.redhat.com/secure/RapidBoard.jspa?rapidView=17575&projectKey=RHIDP[Red Hat Internal Developer Platform (RHIDP) Jira project], click *Create*. +. In the *Description* field, describe your contribution. +. In the *Component/s* field, select *Documentation* from the drop-down list. +. Save the created Jira issue. + +[IMPORTANT] +==== +RHDH release notes are single-sourced from the *Release Notes Text* field in the Jira. +If you want to make changes to release notes, you must make them in Jira. +Check the link:https://docs.google.com/document/d/1X2CrrU9K3ZqbxN7DXmU6P1mY7inLD32qs3rpOUHz6Vw/edit?tab=t.0#heading=h.yqxd252ryhua[RHDH Release Notes process document] for more information. +==== + +## Style and formatting + +All contributions are in AsciiDoc. + +Make sure your writing follows the rules +listed in link:https://www.ibm.com/docs/en/ibm-style[IBM Style] and link:https://redhat-documentation.github.io/supplementary-style-guide/[Red Hat supplementary style guide]. + +[NOTE] +==== +If the IBM Style and the Red Hat supplementary style guide offer conflicting solutions, +the Red Hat supplementary style guide solution overrides IBM Style. +==== + +Follow the link:https://redhat-documentation.github.io/modular-docs/[Modular documentation reference guide] +to modularize your content. ## Building locally . Install `asciidoctor` - see https://docs.asciidoctor.org/asciidoctor/latest/install/linux-packaging/ -. Run `build/scripts/build.sh` to generate html with images in titles-generated/ folders +. Run the following command to generate html with images in titles-generated/ folders: + +[source,terminal] +---- +$ build/scripts/build.sh +---- + +## Checking for broken links + +You can run `htmltest` locally to check for broken links in your PR. + +. Install `htmltest` from https://github.com/wjdp/htmltest +. Run the following command: + +[source,terminal] +---- +$ htmltest +---- + +You can run `linkchecker` to check for broken links in the published RHDH docs. + +. Install `linkchecker` from https://github.com/linkchecker/linkchecker. +. Run the following command to create a .txt file with a list of detected broken links: + +[code,terminal] +---- +$ linkchecker --check-extern --output failures --file-output failures/broken-links.txt https://docs.redhat.com/en/documentation/red_hat_developer_hub/ +---- ## Previews -Commits to this repo can be seen as GH Page content here: +You can view commits to this repo as GitHub Page content here: https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/ -Pull requests will have a link to the generated HTML attached a comment. +PRs have a link to the generated HTML attached as a comment. -## Contributing +## Reviews + +All PRs are reviewed for technical accuracy by an SME and writing quality by another tech writer. + +When possible, request a tech review first and implement suggestions from the SME. +After your PR is approved by the tech reviewer, follow it up with a request a peer review. + +Check link:https://docs.google.com/spreadsheets/d/1X1KHZx2Kvbotie-sU1g2xNt5vHWtc8Wq9Zb43JycOlA/edit?gid=1375268335#gid=1375268335[this doc] for the current peer review roster. + +## Merging PRs + +After the peer and tech reviewer approve your PR, the PR is ready for merging and cherry-picking by a gatekeeper. -Submit a pull request against this repo. +Check link:https://docs.google.com/spreadsheets/d/1X1KHZx2Kvbotie-sU1g2xNt5vHWtc8Wq9Zb43JycOlA/edit?gid=0#gid=0[this doc] for the current gatekeeper roster. +## Labels -## Plugins Reference Guide +As you work on your contribution to this repo, +use labels to show the status of your PR and to request reviews: + +* draft: `do-not-merge/work-in-progress` +* ready for peer and technical reviews: `do-not-merge/review-in-progress` +* request for a tech review: `technical-review-needed` +* completed tech review: `technical-review-done` +* request for a peer review: `peer-review-needed` +* completed peer review: `peer-review-done` +* ready for merging: `ready-to-merge` + +[NOTE] +==== +Remember to remove labels as they become outdated. +For example, remove the `do-not-merge/work-in-progress` label when you finalize your draft and your PR is ready for review. +==== + +## Publishing pipeline + +This repo is the upstream mirror of the GitLab RHDH repo https://gitlab.cee.redhat.com/red-hat-developers-documentation/rhdh + +Merged PRs are synced to GitLab for build with Pantheon. + +## Plugins Reference Guide For Plugin configuration guide, see upstream content in https://github.com/janus-idp/backstage-plugins/tree/main/plugins + +## Additional sources + +* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/467060194/RHDH+documentation+contributor+guide[RHDH documentation contributor guide] +* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/494635174/Content+creation+guidelines [RHDH content creation guidelines] +* link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/580260123/GitHub+Labels+-+What+When+Who[RHDH GitHub labels] From f5b4ac2c9a895c1d2da6e18208f84c17608bb4f4 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:41:40 +0200 Subject: [PATCH 02/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index f4574273bd..9628795315 100644 --- a/README.adoc +++ b/README.adoc @@ -4,7 +4,7 @@ This is a repo for Red Hat Developer (RHDH) documentation. ## Contributing -Contribute to this repo to add new and edit existing RHDH documentation published on the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/[Red Hat Documentation page]. +Contribute to this repository to add new and edit existing RHDH documentation published on the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/[Red Hat Documentation page]. Before submitting a PR, create a Jira issue associated with your contribution to this repo: From ff4b91d21364fd215788e9705aebe709e30cbb31 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:41:49 +0200 Subject: [PATCH 03/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 9628795315..88cabb57ab 100644 --- a/README.adoc +++ b/README.adoc @@ -1,6 +1,6 @@ # Red Hat Developer Hub documentation -This is a repo for Red Hat Developer (RHDH) documentation. +This is a repository for Red Hat Developer (RHDH) documentation. ## Contributing From 24d4e3591f6409cf0938a1c80d429fe89835b065 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:42:00 +0200 Subject: [PATCH 04/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 88cabb57ab..55a8556c1f 100644 --- a/README.adoc +++ b/README.adoc @@ -6,7 +6,7 @@ This is a repository for Red Hat Developer (RHDH) documentation. Contribute to this repository to add new and edit existing RHDH documentation published on the link:https://docs.redhat.com/en/documentation/red_hat_developer_hub/[Red Hat Documentation page]. -Before submitting a PR, create a Jira issue associated with your contribution to this repo: +Before submitting a pull request (PR), create a Jira issue associated with your contribution to this repository: . In the link:https://issues.redhat.com/secure/RapidBoard.jspa?rapidView=17575&projectKey=RHIDP[Red Hat Internal Developer Platform (RHIDP) Jira project], click *Create*. . In the *Description* field, describe your contribution. From 718c78a6531f41f46153d6e5d8aff58b1a656c4f Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:42:11 +0200 Subject: [PATCH 05/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 55a8556c1f..e9a21c88f8 100644 --- a/README.adoc +++ b/README.adoc @@ -15,7 +15,7 @@ Before submitting a pull request (PR), create a Jira issue associated with your [IMPORTANT] ==== -RHDH release notes are single-sourced from the *Release Notes Text* field in the Jira. +RHDH release notes are single-sourced from the *Release Notes Text* field in the Jira Epic. If you want to make changes to release notes, you must make them in Jira. Check the link:https://docs.google.com/document/d/1X2CrrU9K3ZqbxN7DXmU6P1mY7inLD32qs3rpOUHz6Vw/edit?tab=t.0#heading=h.yqxd252ryhua[RHDH Release Notes process document] for more information. ==== From 17116b2297550d7e3ce51f56f3f2ea39f51125d2 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:42:22 +0200 Subject: [PATCH 06/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index e9a21c88f8..2ebb2fdc2a 100644 --- a/README.adoc +++ b/README.adoc @@ -43,7 +43,7 @@ to modularize your content. [source,terminal] ---- -$ build/scripts/build.sh +$ build/scripts/build-ccutil.sh ---- ## Checking for broken links From 6d01b874f6cfb165be113c09b0cc174f0c44dce3 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:42:31 +0200 Subject: [PATCH 07/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/README.adoc b/README.adoc index 2ebb2fdc2a..e638eeff54 100644 --- a/README.adoc +++ b/README.adoc @@ -39,6 +39,7 @@ to modularize your content. ## Building locally . Install `asciidoctor` - see https://docs.asciidoctor.org/asciidoctor/latest/install/linux-packaging/ +. Install Podman - see https://podman.io. . Run the following command to generate html with images in titles-generated/ folders: [source,terminal] From 7abf1e0dcd2d68bdfb81b0be9a579c3f2e3467d8 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:43:04 +0200 Subject: [PATCH 08/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index e638eeff54..98d42529ab 100644 --- a/README.adoc +++ b/README.adoc @@ -40,7 +40,8 @@ to modularize your content. . Install `asciidoctor` - see https://docs.asciidoctor.org/asciidoctor/latest/install/linux-packaging/ . Install Podman - see https://podman.io. -. Run the following command to generate html with images in titles-generated/ folders: +. Run the following command to generate html with images in titles-generated/ folders by using `ccutil` in a container. +The `ccutil` CLI tool reproduces the behavior of the production publication chain (Pantheon), including its limitations, and is therefore preferred over using a more recent `asciidoctor` CLI version. [source,terminal] ---- From b4068489e06b0cffcdf628b847665ed2b4e7237f Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:43:22 +0200 Subject: [PATCH 09/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 98d42529ab..8ea1cadc18 100644 --- a/README.adoc +++ b/README.adoc @@ -42,7 +42,7 @@ to modularize your content. . Install Podman - see https://podman.io. . Run the following command to generate html with images in titles-generated/ folders by using `ccutil` in a container. The `ccutil` CLI tool reproduces the behavior of the production publication chain (Pantheon), including its limitations, and is therefore preferred over using a more recent `asciidoctor` CLI version. - ++ [source,terminal] ---- $ build/scripts/build-ccutil.sh From 291b2ff6f6efc2e1bfa979e44c80995b6d4f4d48 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:43:34 +0200 Subject: [PATCH 10/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.adoc b/README.adoc index 8ea1cadc18..d3d4dc4e97 100644 --- a/README.adoc +++ b/README.adoc @@ -48,6 +48,17 @@ The `ccutil` CLI tool reproduces the behavior of the production publication chai $ build/scripts/build-ccutil.sh ---- +[NOTE] +==== +* To build with `asciidoctor` rather than `ccutil`, run the following script. +The output will look differently and you might miss issues with content that cannot build in production. ++ +[source,terminal] +---- +$ build/scripts/build.sh +---- +==== + ## Checking for broken links You can run `htmltest` locally to check for broken links in your PR. From 722ae3d96e42776fce64c37087a27162fbc1ed2c Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:43:44 +0200 Subject: [PATCH 11/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index d3d4dc4e97..447b171835 100644 --- a/README.adoc +++ b/README.adoc @@ -75,7 +75,7 @@ You can run `linkchecker` to check for broken links in the published RHDH docs. . Install `linkchecker` from https://github.com/linkchecker/linkchecker. . Run the following command to create a .txt file with a list of detected broken links: - ++ [code,terminal] ---- $ linkchecker --check-extern --output failures --file-output failures/broken-links.txt https://docs.redhat.com/en/documentation/red_hat_developer_hub/ From 46d413c760b8a0a9d8f4e2167bbeaa60d2fbc159 Mon Sep 17 00:00:00 2001 From: Jana Vrbkova Date: Tue, 14 Oct 2025 09:43:58 +0200 Subject: [PATCH 12/12] Update README.adoc MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Fabrice Flore-Thébault --- README.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.adoc b/README.adoc index 447b171835..8794ecdf3a 100644 --- a/README.adoc +++ b/README.adoc @@ -65,7 +65,7 @@ You can run `htmltest` locally to check for broken links in your PR. . Install `htmltest` from https://github.com/wjdp/htmltest . Run the following command: - ++ [source,terminal] ---- $ htmltest