Skip to content

Latest commit

 

History

History
140 lines (88 loc) · 5.53 KB

CONTRIBUTING.md

File metadata and controls

140 lines (88 loc) · 5.53 KB
Raw

Contributing to the documentation

Editing the documentation

To edit the documentation:

  1. Learn about the general repository structure in the Repository structure HTML section.

  2. Read the writing and markup conventions summary in the Conventions and style guidelines section.

  3. Ensure that you log an issue with the details of the problem in the Documentation Repository Issue Tracker for context and assign it to yourself.

  4. Clone the documentation repository and make the relevant changes in a branch named after the issue you are working on.

  5. Locally build and test the changes. For details on the instructions and tools to do this, see Locally building the documentation.

  6. After the local builds are successful, commit your changes and create a PR for the fixes. In the assignee field, select one of the writers to do a quick review before merging your changes.

  7. For each push to the master branch and each PR, a preview build of the documentation is created and available at https://docs.prod-preview.openshift.io/. Build status: Build Status. The creator of the PR and reviewers can use this build for testing, which is why it is essential to test your changes locally before creating the PR.

  8. When reviewed, and after any changes necessary are complete, the PR is merged into the documentation.

Conventions and style guidelines

To get started quickly, we recommend reviewing the following conventions that are relevant for this documentation suite:

Writing conventions

  • For instructions, state the location, then action and subject. For example:
    • Incorrect: Click OK in the XYZ tab to continue.
    • Correct: In the XYZ tab, click OK to continue.
  • Use gerunds in titles when possible. For example:
    • Incorrect: 1.1 Create a new project
    • Correct: 1.1 Creating a new project
  • All titles should be in sentence case. Exceptions for words that are proper nouns. For example:
    • Incorrect: 1.2 Configuring Your Che Workspace
    • Correct: 1.2 Configuring your Che workspace

Markup conventions

For a quick primer about the Asciidoc conventions, see the Red Hat Asciidoc Markup conventions document.

GitHub issue branch naming conventions

When naming branches, refer to the appropriate GitHub issues as follows:

  1. Use the prefix i1234 to indicate the issue number.

  2. After a hyphen, indicate which repository the issue belongs to (either the fabric8 repository or the openshift.io repository) using f8 or io respectively.

  3. After a hyphen, add a phrase (without spaces and in lowercase) that broadly summarizes the issue.

As an example, the branch name for #249 would be i249-f8-branchnaming.

Additional Convention References

For comprehensive references for documentation conventions, see the following:

  • The IBM Style Guide. A subset of this guide is available here.

Locally building the documentation

After making changes to the documentation, you can locally build and test the changes.

Step 1: Validating markup

After making changes, run the validate script to test the asciidoc markup used in this repository.

  1. Ensure that asciidoctor and xmllint are installed on your machine.
  2. Run the following script:
$ scripts/validate_guides.sh

Step 2: Build the docs

After validating the documentation, you can locally build the docs in one of three ways:

1) Build using AsciiDoctor

To build a specific guide:

  1. Navigate to the target guide's folder:
$ cd docs/<guide>/
  1. Run the build command:
$ asciidoctor --attribute imagesdir=../../images master.adoc
  1. View the built guide in a browser:
$ <www-browser-of-choice> master.html

2) Build using a script

  1. To build all the guides, run the following script:
$ scripts/build_guides.sh
  1. View the results of the build in a browser:
$ <www-browser-of-choice> html/*.html

HTML versions are built into the html/ directory.

3) Build using containers

This method requires the docker daemon running on your machine.

  1. To build the whole docs site, including the landing page, to test the automated building process, run:
$ export CICO_LOCAL=local
$ sudo ./cico_build_deploy.sh
  1. After a successful build, preview the documentation on localhost:
$ <www-browser-of-choice> http://127.0.0.1:2015/

Deploying the documentation on OpenShift

Use the following commands to deploy the documentation on OpenShift:

$ export DOCS_VERSION=$(curl -L http://central.maven.org/maven2/io/fabric8/apps/fabric8-online-docs-app/maven-metadata.xml | grep '<latest' | cut -f2 -d">" | cut -f1 -d"<")

$ oc apply -f http://central.maven.org/maven2/io/fabric8/apps/fabric8-online-docs-app/$DOCS_VERSION/fabric8-online-docs-app-$DOCS_VERSION-openshift.yml