mirror of
https://github.com/openshift/openshift-docs.git
synced 2026-02-05 12:46:18 +01:00
213 lines
8.9 KiB
Plaintext
213 lines
8.9 KiB
Plaintext
[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
|
|
`_topic_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 `_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` - 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 `_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
|
|
* 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.
|