anchor.diff:  ----
   
   == Version management
  -Most of the content applies to all three OpenShift products: Origin, Online, and 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.
  +Most of the content applies to all three OpenShift products: Origin, Online, and
  +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 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.
  +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:
   
  
positive.code: 
  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 link:#how-it-all-comes-together[How it all comes together] section for information on how to conditionalize whole topics with the metadata _yaml_ file.
  
  2. The `ifdef/endif` blocks cannot be nested. In other words, one conditional block cannot contain other conditional blocks.
  
  == Release branches
  With the combination of conditionalizing content within topics with _ifdef/endif_ and conditionalizing whole topics with the link:#how-it-all-comes-together[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` - OpenShift Origin latest code; essentially, this is our *working* branch
  * `origin-N.N` - OpenShift Origin most recent stable release
  * `online` - OpenShift Online most recent release
  * `enterprise-N.N` - OpenShift Enterprise support releases
  
  On a nightly 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 the next day.
  
  [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 `_build_cfg.yml_` metadata file 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 `_build_cfg.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>
  
negative.code: <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 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*.
  ****
  
  == 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, we recommend that you 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 new 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.
  