Skip to content

Latest commit

 

History

History
231 lines (189 loc) · 10.4 KB

contributing.adoc

File metadata and controls

231 lines (189 loc) · 10.4 KB
Raw

Contribute to OpenShift documentation

Different ways to contribute

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

  • Email the OpenShift Docs team at [email protected].

  • Create a GitHub, Jira, or Bugzilla documentation ticket.

  • Submit a pull request (PR). You can create a local clone of your own fork of the openshift-docs 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 following diagram outlines the OpenShift documentation contribution process:

OpenShift documentation contribution workflow

When you submit a PR, the OpenShift Docs team reviews the PR and arranges further reviews by Quality Engineering (QE), subject matter experts (SMEs), and others, as required. If the PR requires changes, updates, or corrections, the reviewers add comments in the PR. We might request that you make the changes, or let you know that we incorporated your content in a different PR. Occasionally, we might add commits to the original PR directly. When the PR has been reviewed, all updates are complete, and all commits are squashed, the documentation team merges the PR and applies it to the valid versions.

For a more detailed description of the contribution workflow, see Understanding the contribution workflow.

Repository organization

Each top directory in the OpenShift documentation repository can include a collection of top level assemblies and subdirectories that contain more assemblies. The exceptions to this rule are directories whose names start with an underscore (like _builder_lib and _javascripts), which contain the assets used to generate the finished documentation.

Each top level <topic> directory contains AsciiDoc assembly files, any <subtopic> subdirectories, and symlinks to the images and modules directories that contain all the images and modules for the collection.

/
/topic_dir1
/subtopic_dir1
/subtopic_dirN
/topic_dir/assembly1.adoc
/topic_dir/assemblyN.adoc
/topic_dir/subtopic_dir1/assembly1.adoc
/topic_dir/subtopic_dirN/assemblyN.adoc
/topic_dir/~images
/topic_dir/~modules
...
/topic_dir2

Version management

Most of the content applies to all five OpenShift products: OKD, OpenShift Online, OpenShift Dedicated, ROSA and OpenShift Container Platform. While a large amount of content is reused for all product collections, some information applies to only specific collections. Content inclusion and exclusion is managed on the assembly level by specifying distributions in the _topic_map.yml files in the _topic_maps folder or by using ifdef/endif statements in individual files.

Conditional text between products

OpenShift documentation uses AsciiDoc’s ifdef/endif macro to conditionalize and reuse content across the different OpenShift products, down to the single-line level.

The supported distribution attributes used with the OpenShift build mechanism are:

  • openshift-origin

  • openshift-online

  • openshift-enterprise

  • openshift-dedicated

  • openshift-aro

  • openshift-webscale

  • openshift-rosa

These attributes can be used by themselves or in conjunction to conditionalize text within an assembly or module.

Here is an example of this concept in use:

This first line is unconditionalized, and will appear for all versions.

ifdef::openshift-online[]
This line will only appear for OpenShift Online.
endif::[]

ifdef::openshift-enterprise
This line will only appear for OpenShift Container Platform.
endif::[]

ifdef::openshift-origin,openshift-enterprise
This line will appear for OKD and OpenShift Container Platform, but not for OpenShift Online or OpenShift Dedicated.
endif::[]

Note that the following limitation exists when conditionalizing text:

  • While the ifdef/endif blocks have no size limit, do not use them to to conditionalize an entire file. If an entire file is specific to a only some OpenShift distributions, specify them in the _topic_map.yml file.

Release branches

With the combination of conditionalizing content within files with ifdef/endif and conditionalizing whole files in the _topic_map.yml file, the main branch of this repository always contains a complete set of documentation for all OpenShift products. However, when and as new versions of an OpenShift product are released, the main branch is merged down to new or existing release branches. Here is the general naming scheme used in the branches:

  • main - This is our working branch.

  • enterprise-N.N - OpenShift Container Platform support releases. The docs for OpenShift Online and OpenShift Dedicated are based on the appropriate enterprise-N.N branch.

On a 12-hourly basis, the documentation web sites are rebuilt for each of these branches. This way the published content for each released version of an OpenShift product will remain the same while development continues on the main branch. Additionally, any corrections or additions that are "cherry-picked" into the release branches will show up in the published documentation after 12 hours.

Note

All OpenShift content development for the 4.x stream occurs on the main, or working branch. Therefore, when submitting your work the PR must be created against the main branch. After it is reviewed, a writer will apply the content to the relevant release branches. If you know which branches a change applies to, be sure to specify it in your PR.

When adding or updating content for version 3.11, you should create a feature branch against enterprise-3.11 to submit your changes.

Adding files to the collection

After you create assembly files, you must add them to the _topic_map.yml so that the build system can render them. The documentation build system reads the _distro_map.yml from the main branch to determine which branches to build and then the _topic_map.yml file for each of the branches to construct the content from the source files and publish to the relevant product site at https://docs.openshift.com. The build system only reads this file to determine which topic files to include. Therefore, all new assemblies that are created must be included in the _topic_map.yml file in order to be processed by the build system.

For all supported versions, the topic map files are available in the _topic_maps folder. Older versions support _topic_map.yml file in the root folder.

OpenShift Dedicated and OpenShift ROSA have their own topic maps: _topic_map_osd.yml and _topic_map_rosa.yml. Edits to these files should be coordinated with Service Delivery documentation team members as that team is primarily responsible for maintaining this content.

Note

Module files are included in the appropriate assembly files. Modules are not added directly to the _topic_map.yml file.

Topic map file format

For supported branches the _topic_map.yml is based in the _topic_maps folder in the root directory and are organized (primarily) by distributions.

The _topic_map.yml file uses the following format:

--- //(1)
Name: Origin of the Species (2)
Dir:  origin_of_the_species (3)
Distros: all (4)
Topics:
  - Name: The Majestic Marmoset (5)
    File: the_majestic_marmoset (6)
    Distros: all
  - Name: The Curious Crocodile
    File: the_curious_crocodile
    Distros: openshift-online,openshift-enterprise (4)
  - Name: The Numerous Nematodes
    Dir: the_numerous_nematodes (7)
    Topics:
      - Name: The Wily Worm (8)
        File: the_wily_worm
      - Name: The Acrobatic Ascarid  <= Sub-topic 2 name
        File: the_acrobatic_ascarid  <= Sub-topic 2 file under <group dir>/<subtopic dir>

  1. Record separator at the top of each topic group.

  2. Display name of topic group.

  3. Directory name of topic group.

  4. Which OpenShift versions this topic group is part of.

    • The Distros setting is optional for topic groups and topic items. By default, if the Distros setting is not used, it is processed as if it was set to Distros: all for that particular topic or topic group. This means that topic or topic group will appear in all product documentation versions.

    • The all value for Distros is a synonym for openshift-origin,openshift-enterprise,openshift-online,openshift-dedicated,openshift-aro,openshift-webscale.

    • The all value overrides other values, so openshift-online,all is processed as all.

    • Do not use openshift-dedicated or openshift-rosa in the main _topic_map.yml file. Use the distribution specific topic map file.

  5. Assembly name.

  6. Assembly file under the topic group dir without .adoc.

  7. This topic is actually a subtopic group. Instead of a File path it has a Dir path and Topics, just like a top-level topic group.

  8. Assemblies belonging to a subtopic group are listed just like regular assemblies with a Name and File.

Next steps