Red Hat Developer Hub documentation

This is a repository for Red Hat Developer (RHDH) documentation.

Contributing

Contribute to this repository to add new and edit existing RHDH documentation published on the Red Hat Documentation page.

Before submitting a pull request (PR), create a Jira issue associated with your contribution to this repository.

There are currently three Jira projects related to RHDH:

• RHDHBUGS - For issues related to existing content.

• RHIDP - For new features related to the core platform, including security mechanisms.

• RHDHPAI - For new features related to plugins and AI.

Choose a Jira project that matches your contribution and create a new issue:

1. In the Jira project, click Create.

2. In the Description field, describe your contribution.

3. In the Component/s field, select Documentation from the drop-down list.

4. Save the created Jira issue.

Important

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 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 IBM Style and 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 Modular documentation reference guide to modularize your content.

Building locally

1. Install asciidoctor - see https://docs.asciidoctor.org/asciidoctor/latest/install/linux-packaging/

2. Install Podman - see https://podman.io.

3. 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.

   $  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. $ build/scripts/build.sh

Checking for broken links

You can run htmltest locally to check for broken links in your PR.

1. Install htmltest from https://github.com/wjdp/htmltest

2. Run the following command:

   $ htmltest

You can run linkchecker to check for broken links in the published RHDH docs.

1. Install linkchecker from https://github.com/linkchecker/linkchecker.

2. Run the following command to create a .txt file with a list of detected broken links:

   $ linkchecker --check-extern --output failures --file-output failures/broken-links.txt https://docs.redhat.com/en/documentation/red_hat_developer_hub/<version>

Previews

You can view commits to this repo as GitHub Page content here:

https://redhat-developer.github.io/red-hat-developers-documentation-rhdh/

PRs have a link to the generated HTML attached as a comment.

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 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.

Check this doc for the current gatekeeper roster.

Labels

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

• RHDH documentation contributor guide

• link:https://spaces.redhat.com/spaces/RHDEVDOCS/pages/494635174/Content+creation+guidelines [RHDH content creation guidelines]

• RHDH GitHub labels