openshift-docs/contributing_to_docs/contributing.adoc

[id="contributing-to-docs-contributing"]
= Contribute to OpenShift documentation
:icons:
:toc: macro
:toc-title:
:toclevels: 1
:description: Basic information about the OpenShift GitHub repository

toc::[]

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

* Email the OpenShift Docs team at openshift-docs@redhat.com.
* Create a link:https://github.com/openshift/openshift-docs/issues/new[GitHub] or link:https://issues.redhat.com/secure/CreateIssueDetails!init.jspa?pid=12332330&summary=Documentation_issue&issuetype=1&components=12367614&priority=10200&versions=12391126[Jira issue] for the most relevant documentation component.
* Submit a pull request (PR). You can create a local clone of your own fork of the link:https://github.com/openshift/openshift-docs[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
https://github.com/orgs/openshift/teams/team-documentation[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 four OpenShift products: OKD, OpenShift
Online, OpenShift Dedicated, 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
`&#95;topic&#95;map.yml` file or by using `ifdef/endif` statements in individual
files.

////
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.
endif::[]

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

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

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 `&#95;topic&#95;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 `&#95;topic&#95;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` - OKD latest code; essentially, 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 6 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 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. 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.
====

== Adding files to the collection
After you create files, you must add them to the `&#95;topic&#95;map.yml` so
that the build system can render them. The documentation build system reads
the `&#95;distro&#95;map.yml` from the master branch to determine
which branches to build and then the `&#95;topic&#95;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 `&#95;topic&#95;map.yml` file in
order to be processed by the build system.

=== Topic map file format
The `&#95;topic&#95;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
* First, you should link:tools_and_setup.adoc[Install and set up the tools and software]
on your workstation so that you can contribute.
* Next, link:doc_guidelines.adoc[review the documentation guidelines] to
understand some basic guidelines to keep things consistent
across our content.
* If you are ready to create content, or want to edit existing content, the
link:create_or_edit_content.adoc[create or edit content] topic describes how
you can do this by creating a working branch.