Different ways to contribute

There are a few different ways you can contribute to oVirt documentation:

  • Create an issue in GitHub

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

What happens when you submit a PR?

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.

Repository organization

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 index.adoc and 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.

Version management

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 include statements, ifdef/endif statements, and attributes in individual files.

Conditional text between products

oVirt documentation uses AsciiDoc’s ifdef/endif and 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:

  • ovirt-doc

  • rhv-doc

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::[]

While the ifdef/endif blocks have no size limit, do not use them to to conditionalize the text of an entire file within that file. Instead, use include statements to include the file in the top-level assembly, that is, the index.adoc file, or use ifdef macros around the include statement if the assembly is shared between oVirt and RHV.

Release branches

All published oVirt content is on the master branch. Therefore, when submitting your work create the PR against the master branch. After it is reviewed, a writer will merge the content.

Creating a pull request (PR)

  1. For the PR title, use this format: <issue_id>: [Docs] [<Guide_abbreviation>] <Short description>

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

  3. After creating the PR, add the documentation label.

  4. Prevent merging by clicking Convert to draft.

  5. When the PR is ready to merge, click the Ready for review button.