Skip to content

Latest commit

 

History

History
221 lines (189 loc) · 8.89 KB

contributing.adoc

File metadata and controls

221 lines (189 loc) · 8.89 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 documentation team [email protected]

  • 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 required, 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 all updates are complete, and all commits are squashed, we’ll merge your PR and apply it to the valid versions.

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, Azure Red Hat OpenShift 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 file 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

These attributes can be used by themselves or in conjunction to conditionalize text within a topic document.

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.

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

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

Note that the following limitations exist when conditionalizing text:

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

  2. Avoid using ifndef/endif. As of writing, it’s use is broken and buggy.

Release branches

With the combination of conditionalizing content within files with ifdef/endif and conditionalizing whole files in the _topic_map.yml file, the master 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 master branch is merged down to new or existing release branches. Here is the general naming scheme used in the branches:

  • master - This is our working branch.

  • master-3 - OKD latest code; essentially, this is our working branch for the 3.x stream.

  • 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 master 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 master, or working branch. Therefore, when submitting your work the PR must be created against the master 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.

We have a separate master branch for 3.x stream of OpenShift: master-3. You should submit content against that branch for changes to 3.x stream.

Adding files to the collection

After you create 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 master 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 topics that are created must be included in the _topic_map.yml file in order to be processed by the build system.

Topic map file format

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 process 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 three product documentation.

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

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

  5. Topic name.

  6. Topic 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. Topics belonging to a subtopic group are listed just like regular topics with a Name and File.

Next steps