Different ways to contribute
There are a few different ways you can contribute to oVirt documentation:
Submit a PR. You can clone the repository, make your changes, and submit a PR. This option is best if you have substantial changes. If you open a PR, be sure that all of its contents are related and apply to the same versions.
The documentation team reviews the PR and arranges further review by the development and quality assurance teams, as required. If the PR requires changes, updates, or corrections, we will let you know in the PR. We might request that you make the changes, or let you know that we incorporated your content in a different PR. When the PR has been reviewed, all updates are complete, and all commits are squashed, we’ll merge the PR and it will be published to the oVirt website.
The oVirt documentation repository is stored under
/source/documentation. Each directory corresponds to a guide, except
common, which includes files that are shared between multiple guides. Each guide’s directory includes
master.adoc files. These are the top-level assemblies for that guide, where
index.adoc is for oVirt and
master.adoc is for Red Hat Virtualization, a downstream distribution of oVirt. Many guides include additional nested assemblies and a
topics subdirectory with individual topics.
Most of the content applies to oVirt and Red Hat Virtualization. While a large
amount of content is reused for both products, some information
applies to only one or the other. Content inclusion and exclusion is managed
by using a combination of
ifdef/endif statements, and attributes
in individual files.
Conditional text between products
oVirt documentation uses AsciiDoc’s
ifeval/endif macros to conditionalize
and reuse content, down to the single-line level.
The supported distribution attributes used with the oVirt build mechanism are:
Here is an example of this concept in use:
This line is not conditionalized, and will appear for both oVirt and RHV. ifdef::ovirt-doc This line will only appear for oVirt. endif:: ifdef::rhv-doc This line will only appear for Red Hat Virtualization. endif::
All published oVirt content is on the
Therefore, when submitting your work create the PR against the
branch. After it is reviewed, a writer will merge the content.
Creating a pull request (PR)
For the PR title, use this format:
<issue_id>: [Docs] [<Guide_abbreviation>] <Short description>
Use the following boilerplate text for the PR description:
[Feature | Bug fix] Fixes (issue # |<issue_URL>) (If the PR should not be published prior to an upcoming release) Do not publish before: <target_release> release Changes proposed in this pull request: - - - I confirm that this pull request was submitted according to the [contribution guidelines](https://github.com/oVirt/ovirt-site/blob/main/CONTRIBUTING.md): (please @mention yourself to sign) This pull request needs review by: (please @mention the reviewer if relevant)Example
PR TITLE: BZ#2010355: [Docs][Admin] Update Inventory Dashboard description Feature This PR addresses https://bugzilla.redhat.com/show_bug.cgi?id=2010355. Do not publish before: oVirt 4.4.9 release Changes proposed in this pull request: * This PR adds a module to describe the new dashboard feature. I confirm that this pull request was submitted according to the [contribution guidelines](https://github.com/oVirt/ovirt-site/blob/main/CONTRIBUTING.md): @ploni) This pull request needs review by: @octocat
After creating the PR, add the documentation label.
Prevent merging by clicking Convert to draft.
When the PR is ready to merge, click the Ready for review button.