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]