Skip to content

Latest commit

 

History

History
217 lines (184 loc) · 8.85 KB

contributing.adoc

File metadata and controls

217 lines (184 loc) · 8.85 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 openshift-docs@redhat.com

  • Create an issue in GitHub

  • If you would like to do the work yourself, or if it is a substantial change, then you should clone the repository, make your changes, and submit a PR. Each PR should have closely-related changes. In particular, it is a good idea to use separate PRs for bugfix changes (for an old or current release) vs enhancement changes (for an upcoming new release). If you are submitting content for OCP 4.0, please read how to contribute user stories.

What happens when you submit a PR?

If you make a substantial change and submit a PR in GitHub, your PR will be reviewed by our documentation team. Tag the team using @openshift/team-documentation as a comment to get their attention. If there are any further changes, updates, or corrections required, we will inform you in the PR. When the PR has been reviewed and all changes have been accepted by our documentation team, your PR will be merged.

Repository organization

Each top directory in the OpenShift documentation repository can include a collection of top-level topics, and/or subdirectories that further contain a second level of topics. 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 the topics as AsciiDoc files, any <subtopic> subdirectories, and an images directory where all images for that topic are stored.

/
/topic_dir1
/subtopic_dir1
/subtopic_dirN
/topic_dir/topic1.adoc
/topic_dir/topicN.adoc
/topic_dir/subtopic_dir1/topic1.adoc
/topic_dir/subtopic_dirN/topicN.adoc
/topic_dir/images
/topic_dir/images/img1.png
/topic_dir/images/imgN.png
...
/topic_dir2

Version management

Most of the content applies to all four OpenShift products: OKD, Online, Dedicated and Enterprise (some versions of Enterprise), so approximately 80% of the content is reused. In many cases, this means that individual topics may need to include or exclude individual paragraphs with respect to a specific OpenShift product. While it is possible to accomplish this solely with Git branches to maintain slightly different versions of a given topic, doing so would make the task of maintaining internal consistency extremely difficult for content contributors.

Git branching is still extremely valuable and serves the important role of tracking the release versions of documentation for the various OpenShift products.

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

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

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

Note that the following limitations exist when conditionalizing text:

  1. The ifdef/endif blocks have no size limit, however, they should not be used to conditionalize an entire topic. If an entire topic file is specific to a given OpenShift distribution, see the How it all comes together section for information on how to conditionalize whole topics with the metadata yaml 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 topics with ifdef/endif and conditionalizing whole topics with the metadata yaml file, the master branch of this repository always contains a complete set of documentation for all three 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 - OKD latest code; essentially, this is our working branch

  • enterprise-N.N - OpenShift Enterprise support releases

  • The dedicated and online branches are built using the enterprise version that they correspond to.

On a 6 hourly basis, the documentation websites 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 6 hours.

Note

All OpenShift content development occurs on the master, or working branch. Therefore, when submitting your work the PR must be created against the master branch. Once it is reviewed that content will then migrate to the corresponding release branches.

How it all comes together

The documentation build system reads the _distro_map.yml to figure out which branches to build and then the _topic_map.yml metadata 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 metadata file in order to be processed by the build system.

Metadata file format

The format of this file is as indicated:

--- //(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 (7)
  - Name: The Numerous Nematodes
    Dir: the_numerous_nematodes (8)
    Topics:
      - Name: The Wily Worm (9)
        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

  5. Topic name

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

  7. Which OpenShift versions this topic is part of

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

  9. Topics belonging to a subtopic group are listed just like regular topics with a Name and File.

Notes on Distros metadata attribute

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

Next steps