Strimzi

Strimzi Documentation Contributor Guide

1. Introduction

This guide is meant to assist contributors to the Strimzi documentation.

1.1. Dependencies

  • asciidoctor

  • python

1.2. Project layout

quickstart/                          # Quickstart guide
using/                               # User guide
assemblies/                          # Assemblies for all guides
modules/                             # Modules for all guides
shared/                              # Shared include files
shared/attributes.adoc               # Global book attributes
shared/images/                       # Shared image files

2. Setting up git

Strimzi uses git to manage repositories. This guide explains how to set up your system to connect to the proper git repositories.

strimzi-kafka-operator (GitHub)

A public GitHub repo that hosts all of the Strimzi code and documentation.

2.1. Install git

If using Fedora, open your terminal and enter the proper installation command.

Fedora

$ yum install git (up to Fedora 21)
$ dnf install git (Fedora 22 and later)

Other operating systems

2.2. Configuring git

Once you have git installed you’ll want to set up your git account.

Procedure

  1. Open Terminal

  2. Set your name and email

    $ git config --global user.name "<your-name>"
$ git config --global user.email "<your-email>"
    Tip
    		 The email you specify should be the same one found in your email settings. To keep your email address hidden, see Keeping your email address private.

  3. Set your git defaults

    $ git config --global pull.rebase true
$ git config --global push.default simple

2.3. Fork the upstream (GitHub) repository

Fork the strimzi-kafka-operator upstream repository to create a copy under your own GitHub ID. This allows you to work on multiple features and push changes to branches in your own GitHub instance so that you do not have to worry about losing work. When you are ready, you can request the changes to be merged back into the upstream repository.

Procedure

  1. Open a browser and navigate to the upstream repository located at https://github.com/strimzi/strimzi-kafka-operator

  2. Click Fork located in the upper right under your profile icon.

  3. Select your user account for the location of the forked repository. This creates your own copy of the repository under your own GitHub ID.

2.4. Add your SSH keys to GitHub

If you choose to use the SSH address for your clones, you will need to add an SSH Key to GitHub first.

Procedure

  1. Open Terminal.

  2. Check to see if you have a public SSH key:

    $ ls ~/.ssh/

  3. If you don’t have a key, generate one:

    $ ssh-keygen -t rsa -C "<your-email>"

  4. Open your key in an editor:

    $ cd ~/.ssh/
$ vi id_rsa.pub

  5. Copy the contents of the file to your clipboard.

  6. Visit https://github.com/settings/keys

  7. Click New SSH Key.

  8. Give your key a name and paste the contents of your key file.

  9. Click Add SSH Key.

2.5. Clone your forked upstream repository

Clone your forked repository to bring your GitHub repository files to your local machine. Your forked repository is now the origin repository for your local files.

Note
 For more information about forking and cloning, consult the official GitHub documentation.

Using SSH

Procedure

  1. Open Terminal.

  2. Navigate to the directory where you want to create the new repository folder.

  3. Type the following command:

    $ git clone git@github.com:<username>/strimzi-kafka-operator.git

  4. Navigate to the newly created strimzi-kafka-operator folder.

    $ cd strimzi-kafka-operator/

Using HTTPS

While there are fewer steps in this option, you have to enter your GitHub credentials with every change you make.

Procedure

  1. Open Terminal.

  2. Navigate to the directory where you want to create the new repository folder.

  3. Type the following command:

    $ git clone https://github.com/<username>/strimzi-kafka-operator.git

  4. Enter your GitHub credentials to complete the clone.

  5. Navigate to the newly created strimzi-kafka-operator folder.

    $ cd strimzi-kafka-operator/

2.6. Add the upstream as a remote repository

Once you have your fork checked out and cloned locally, add the downstream repository as a remote.

Using SSH

Procedure

  1. List the current remote repositories:

    $ git remote -v
origin	git@github.com:<username>/strimzi-kafka-operator.git (fetch)
origin	git@github.com:<username>/strimzi-kafka-operator.git (push)

  2. Add the upstream as a remote repository and fetch its contents. This allows you to check out and work with the latest source code.

    $ git remote add -f upstream  git@github.com:strimzi/strimzi-kafka-operator.git

  3. Enter your GitHub credentials to complete the remote add process.

  4. Verify the new remote was added:

    $ git remote -v
origin	git@github.com:<username>/strimzi-kafka-operator.git (fetch)
origin	git@github.com:<username>/strimzi-kafka-operator.git (push)
upstream	git@github.com:strimzi/strimzi-kafka-operator.git (fetch)
upstream	git@github.com:strimzi/strimzi-kafka-operator.git (push)

Using HTTPS

Procedure

  1. List the current remote repositories:

    $ git remote -v
origin	https://github.com/<username>/strimzi-kafka-operator.git (fetch)
origin	https://github.com/<username>/strimzi-kafka-operator.git (push)

  2. Add the upstream as a remote repository and fetch its contents. This allows you to check out and work with the latest source code.

    $ git remote add -f upstream  https://github.com/strimzi/strimzi-kafka-operator.git

  3. Enter your GitHub credentials to complete the remote add process.

  4. Verify the new remote was added:

    $ git remote -v
origin	https://github.com/<username>/strimzi-kafka-operator.git (fetch)
origin	https://github.com/<username>/strimzi-kafka-operator.git (push)
upstream	https://github.com/strimzi/strimzi-kafka-operator.git (fetch)
upstream	https://github.com/strimzi/strimzi-kafka-operator.git (push)

2.7. Updating repository URLs

If the upstream repository is moved, you can change the downstream URL by using the following command:

$ git remote set-url upstream https://github.com/strimzi/strimzi-kafka-operator.git

Use the following command any time you need to fetch the latest source code locally:

$ git fetch upstream

2.8. References

3. Contributing to the documentation

The following guide walks you through contributing to the Strimzi documentation.

3.1. Getting started

Before you begin you need to:

  1. Install and set up Git

3.2. Contributing to the documentation

Once you have your local repository set up and have up to date copies of upstream content you need to follow these steps to contribute to the documentation.

Procedure

  1. Open your terminal

  2. cd to the directory where your documentation resides

  3. Checkout the master branch

    $ git checkout master

  4. Update your local repository and fork with the upstream content

    $ git pull upstream master
$ git push origin master --force

  5. Create a new branch for your work (using the issue number is helpful)

    $ git checkout -b <branch-name>

  6. Make your edits in the editor of your choice

  7. Save your changes locally

  8. Build your documentation to verify that there are no build errors and that everything looks right

    1. This can be done with the Make tooling

  9. If you are creating new files, add the files to the repository

    $ git status
$ git add <file-name>

  10. Commit your changes

    $ git commit -a -s -m "<message>"

    Note that the project requires all commits to be signed off, indicating that you certify the changes with the developer certificate of origin (DCO).

  11. Push your changes to your fork

    $ git push origin HEAD

  12. If the update is rejected because the commit is behind, merge your changes

    $ git pull upstream master
$ git push -f origin HEAD

  13. Visit your fork on GitHub

  14. Click Compare & pull request

  15. If a SME review is needed:

    1. Add SME Review Needed label.

    2. When SME review is complete, remove SME Review Completed label and go to step 16.

  16. Add Peer Review Needed label and assign a Reviewer.

    1. When peer review has been completed, the reviewer deletes the Peer Review Needed label and adds the Peer Review Done label.

  17. When Peer Review Done label has been added:

    1. If no changes are needed, remove Peer Review Done label and add Ready for Merge label.

    2. If changes are needed and the changes are minor, make changes to the files, commit, and push, and then remove Peer Review Done label and add Ready for Merge label.

    3. If you want an additional review on the updated content, add the Peer Review Needed label and ask for another review in a comment.

4. AsciiDoc format reference

Tips for which AsciiDoc markup to use when formatting text.

Monospace (`)
Item Example

File names and paths

The `/home/user/.bashrc` file …​

Literal values

If the value is `true` …​

Configuration attributes

Set the `enabled` attribute …​

Java class names

The `java.sql.Connection` class …​

Java annotations

The `@Clustered` annotation …​
Italics (_)
Item Example

Guide titles

See the _Installation Guide_ …​

Emphasis for a term (only emphasize first time)

_High availability_ refers to the …​
Bold (*)
Item Example

GUI items (menus, buttons)

Click the *Add* button and …​
Underline (value)
Item Example

Default item in a multi-select

`yes|[.underline]#no#|maybe`

5. Style guidelines

5.1. General styles

Table 1. General quick reference
Item Use Not

Filesystem names and paths, symbols, and literals.

`filename`

GUI items (Match the capitalization of the button)

*bold*

Navigation link text

*bold*

Superuser console commands

$ sudo

#

Emphasis

_yay_

*yay*

List of options (underline the default if there is one)

1|[.underline]#2#|3

1/2/3

Decimal integers < 10

four

4

Decimal integers >= 10

12

twelve

Hexadecimal integers (always numeric, lowercase x)

0x123

0X13

Number ranges (always use numerals)

1-20

1-twenty

Do not use Latin abbreviations

that is

i.e.

and so on

etc.

for example

e.g.

Cannot

cannot

can not

And

and

&

Choices

and

and/or

or

Heartbeating

heartbeating

heart-beating
Additional general guidelines

  • Stick to one file per chapter unless the content is too long, excluding reusable topics.

  • Don’t use contractions, ;).

  • Document IDs are book-scoped, so they don’t need the book title in them.

  • Terminate bulleted and numbered lists with periods unless the items listed are simple names.

  • The words "server" and "broker" are not capitalized unless they begin a sentence or appear in a title.

  • Avoid the word "simply" unless it clarifies.

  • For substitution of {attr} in code blocks, use [subs=+attributes].

  • For styling of *bold* (bold) in code blocks, use [subs=+quotes].

5.2. Naming files

Table 2. File Names Quick Reference
Item Use Not

Custom attributes

`ThisStyle`

`this-style`

`this_style`

File and directory names

`module_this-style`

`module-this_style`

`ModuleThisStyle`

Learn more about naming files in the Files and Attributes appendix.

5.3. Styling headings and titles

Uses sentence-case headings for modules, tables, and figures.

Table 3. Headings quick reference
Item Use Not

Section headings

Configuring the system with RHEL

Configuring the System with RHEL

Configuring The System With RHEL

Procedure Titles (gerund)

Configuring

Configure

Table and block titles

This is an example

This is an Example

This Is An Example

Hyphenated headings

Configuring point-to-point messaging

Configuring Point-To-Point Messaging

Configuring Point-to-point Messaging

Unnumbered titled sections

[discrete]

5.4. Section IDs

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.

Learn more about reusing content in the Modular Documentation Reference Guide.

Table 4. IDs quick reference
Item Use Not

Document IDs

[id="same-as-section-heading-{context}"]

[[this-heading-here]]

[[ThisHeadingHere]]

[#anchor-name]

5.5. Styling punctuation

General punctuation guidelines

  • Do not refer to an individual punctuation mark or special character by its symbol alone.

  • Use the name alone, or use the name followed by the symbol in parentheses.

  • Use the name alone if the punctuation mark or special character is standard, such as a comma or period, and including the symbol would clutter the text.

  • Include the symbol in parentheses when a punctuation mark or special character is not well known or when including the symbol improves clarity.

Table 5. Punctuation quick reference
Character Name

&

Ampersand

< >

Angle brackets, opening angle bracket, or closing angle bracket

" "

Double quotation marks, opening quotation marks, or closing quotation marks (not quotes or quote marks)

' '

Single quotation marks, opening quotation mark,or closing quotation mark (not quotes or quote marks)

%

Percent sign

( )

Parentheses, opening parenthesis, or closing parenthesis

$

Dollar sign

*

Asterisk (not star)

#

Number sign

!

Exclamation point (not exclamation mark or bang)

5.6. Styling replaceables

Replaceable values in the text and code must be styled as monospace, italics, lowercase, arrow brackets, and hyphens.

Table 6. Replaceables quick reference
Item Use

Replaceable value

_`<some-value>`_

Location of broker instance

_`<broker-instance-dir>`_

Component install directory

_`<install-dir>`_
Tip
 If using a replaceable within a source block, you will need to add subs="+quotes"` to the source tag for it to render. (For example : [source,subs="+quotes"]).
Important
 If you enter the source language, for example, 'shell', the italics will not render.
Table 7. Links Quick Reference
Item Use Not

Zip files

zip

.zip

ZIP

Tar files

tar

.tar

TAR

External links

link:github.com[GitHub^]

link:github.com[GitHub]

Internal links

xref:doc_id[Section Title]

xref:doc_id[Section Title^]
Note
 If you use the caret syntax more than once in a single paragraph, you may need to escape the first occurrence with a backslash.
Important
 Links with attributes (including the subject and body segments on mailto links) are a feature unique to Asciidoctor. When they are enabled, you must surround the link text in double quotes if it contains a comma.
Additional link guidelines

  • Refer to the top-level sections of books as chapters, not sections or topics.

  • Do not split link paths across lines when wrapping text. This will cause issues with the doc builds.

6. Screenshot guidelines

6.1. Summary

  • Images should be saved as PNG or JPG, with a width of at least 660 px, at 110 dpi. Try to keep file size less than 300 KB.

  • Screenshots supplement the text, not replace it. Do not rely on images to provide information or context.

  • Do not include any testing/pre-release labels.

  • Do not include any personally identifying information.

  • Capture just the part of the screen or window that users must focus on; do not include window headers in the final screenshots unless completely necessary.

  • Manipulate your screenshots to condense important information in them and limit empty GUI space and other inconsequential parts.

6.2. General guidelines

  • Screen captures can be useful and successful when they achieve one or more of these objectives:

    • Illustrate a user interface that is fairly complex or difficult to explain in text

    • Help the user find a small element in a complex user interface

    • Show the results of a series of steps or user actions

    • Orient readers who are reading the publication without the user interface in front of them

  • Use the smallest number of screenshots possible.

  • Use screenshots to provide verification for the reader, rather than instruction. For example, screenshots are meant to supplement the text, not replace it. Do not rely on images to provide information or context. Instead, use them only to provide the reader with orientation.

    Note
    		 Example 1: Do not tell the reader to fill out a form according to the image; instead list the values needed for the form in text.
    Note
    		 Example 2: Do not include an image of the directory tree; instead tell the user exactly where to find the file in running text (…​/standalone/configuration/standalone.xml).

  • Bearing in mind the affect on localization and accessibility, aim to write your document so that, were you to remove all screenshots from the book, the text still makes sense.

    Note
    		 For example: Do not write "see image below" or "as is shown in the image"

  • When you are snapping a GUI form, fill it with relevant input first.

  • Verify that the screenshots do not include any testing/pre-release labels.

  • Verifty that the screenshots do not include any personally identifying information.

    Note
    		 For example: Always use 'test' as the username or fake contact information. If including the browser title bar hide your bookmarks and use a default browser theme.
    Tip
    		 Use Chrome Dev Tools to select elements on the page and rewrite their contents.

  • Include the cursor, mouse pointer, or menus only when their presence is significant.

  • Increase font size in the browser if it is hard to read before snapping the image.

  • Capture just the part of the screen or window that users must focus on.

    Note
    		 For example: Unless necessary, do not include window headers in the final screenshots to indicate your currently used window manager or desktop environment.

  • If possible, try not to cut any elements on the screen.

  • Show the user interface elements exactly as they are displayed for most users for quick recognition.

    Note
    		 For example: If you have a custom theme on your system, disable it and take the screenshot using the default theme.

  • Do not add borders around or drop shadows to your screenshots.

  • Do not use rounded corners. If the screenshot contains rounded corners, then that is acceptable. But, the screenshot should remain squared.

6.3. Tech specifications

  • Image width should be at least 660 px (internal tools will automatically resize the image to a max width of 660 px).

  • The preferred format is PNG or JPG .

  • The output resolution of images should be 110 dpi to ensure good quality in the generated PDF.

    Tip
    		 In GIMP, select Image/Scale Image…​ to set resolution

  • If possible, try to keep screenshot size less than 300 KB.

  • If possible, avoid snapping images in various terminals with 8-bit color scale or less.

  • Manipulate your screenshots to condense important information in them and limit empty GUI space and other inconsequential parts.

    Note
    		 You can do this by setting a low screen resolution or resizing your browser window to a smaller size. Remember that you should only do this if it does not adversely affect the readability of the image.
    Note
    		 If you need to take a screenshot of the entire window, use a tool such as the Window Resizer Google Chrome extension to ensure the browser window is a set size before taking the screenshot. This helps ensure that all full window screenshots are of standard dimensions.

  • If necessary, call attention to hard to find parts of the screenshot with red outlines (border: #C00, width:1px) or with a transparent gray (#ECECEC) layer over unimportant parts of the picture.

6.4. Accessibility

  • Section 508 compliance requires that all of the information is available in a text format for accessibility reasons (for instance, screen readers can not extract information from images).

  • Also, a large number of screenshots can possibly slow download of docs for those on slow connections (rarer for most enterprises these days).

6.5. AsciiDoc syntax

  • Insert a block-level image, which uses a double colon (::). Good for screenshots, diagrams, etc.

    • Example 1: Include an image title in title case (which automatically appends a Figure #).

      .Image Title
image::icon.png[Alt text, 50, 50]

    • Example 2: Insert an inline image. Note, there is only one colon (:) used here.

      This is an inline image. image:icon.png[Alt text] Cool!

6.6. Additional questions

  • When should I add a screenshot to my book?

    • When introducing a new part of the UI.

    • When the UI is suboptimal and some elements are difficult to find, located in unusual places, hidden, or somehow less visible.

  • When, in the development cycle, should I add my screenshots?

    • Add them as late in the cycle as possible, preferably during the review process. At this late stage, hopefully there will be fewer UI changes to the product.

      Tip
      		 Add a placeholder for the screenshot early on in the development cycle. This way it will not be forgotten.

  • What image editor should I use?

    • The recommended graphical editor is GIMP.

6.7. Browser extensions

6.7.1. Resizing screenshots

There are a couple simple browser extensions that can assist in resizing your browser to the appropriate dimensions.

7. Using make with documentation

When you make changes to the documentation, it is a good practice to do a local test build to verify the book builds successfully and renders as you expect before you submit the merge request back to upstream master.

Make is a useful tool for building your documentation and pushing it to a public website so that peer and quality reviewers can see your edits as the user would.

7.1. Make commands to build documentation

make clean

Delete all temporary files

make check

Execute the custom checks in .travis/check_docs.sh

make build

Build the docs using asciidoc, excluding the generated documentation

make buildall

Build the docs using asciidoc, including the generated documentation (requires mvn).

make publish

Build the docs via make build and publish them using rsync. The publish destination is configured via a Makefile.publish (not included in this PR; provided by each user so they can publish to their own location). The Makefile.publish needs to configure a single PUBLISH_DEST variable which is the remote directory (<host>:<dir>) to copy the generated docs to.

See the output in your browser at file in your project directory at: documentation/html/index.html

Appendix A: Files and attributes

A.1. Important files

Standard attributes

shared/attributes.adoc

Shared includes

shared/

Images

shared/images/

A.2. Anchor names and file names

To optimize modular documentation, follow these guidelines for naming module anchors and files:

Anchor names

Provide an anchor in the format [id='anchor-name'] for every module so that it can be identified by Asciidoctor when reused or cross-referenced. Give the anchor the same or similar name as the module heading, separated by dashes:

[id='anchor-name']
= Module Heading

First sentence of topic.
Note
Note on other anchor formats (Not Recommended)

The format defined here is recommended because it is the most stable and versatile of anchor formats, and supports variables that enable topics to be reused and cross-referenced properly. Other anchor formats include [[anchor-name]] and [#anchor-name], but these formats either do not support variables for content reuse or do not support certain character types, such as periods. These limitations cause errors at build time.
File names

Give the module file the same name as the anchor used in it (which is the same as or similar to the module heading), also separated by dashes. Add a prefix with an underscore to the file name to indicate the module type in the format prefix-file-name. Use snip- for a snippet, con- for concept, ref- for reference, proc- for procedure, assembly- for assembly, and image- for images and screenshots.

Examples

  • snip-guided-decision-urls.adoc (Snippet of reusable content)

  • con-guided-decision-tables.adoc (Concept module)

  • proc-creating-guided-decision-tables.adoc (Procedure module for creating)

  • proc-editing-guided-decision-tables.adoc (Procedure module for editing)

  • ref-guided-decision-table-examples.adoc (Reference module with examples)

  • ref-guided-decision-table-columns.adoc (Reference module with column types)

  • assembly-guided-decision-tables.adoc (Assembly of guided decision table modules)

  • image-guided-decision-example.adoc (Screenshot or image of guided decision table modules)

Learn more in the Modular Documentation Reference Guide.

Appendix B: Git tips

B.1. Delete branches

To delete all of your branches except the branch you are on:

$ git checkout master
$ for br in `git branch` ; do git branch -D $br ; done

To delete one branch:

$ git checkout master
$ git branch -D <branch-name>

B.2. Resolve conflicts

To resolve a merge conflict in an existing pull request:

$ git checkout <branch-name>
$ git branch -u origin <branch-name>
$ git pull --rebase upstream master
$ git push -f origin HEAD

B.3. Reset your fork

If your fork is both ahead of and behind the origin you can reset your fork to match the origin and start with a clean slate.

$ git checkout master
$ git reset --hard upstream/master
$ git push origin master --force
$ git pull upstream master
$ git push origin master --force

B.4. Using ssh-agent to save your SSH key’s passphrase

If you have to enter your SSH key’s passphrase whenever working with the repository from the command line, you might want to use the ssh-agent to remember the passphrase for you.

Before using the ssh-agent you will see a prompt to enter your passphrase after each git command.

[amq-repo]$ git pull --rebase upstream master
Enter passphrase for key '/home/<username>/.ssh/id_rsa':

To add your passphrase to the ssh-agent:

[amq-repo]$ ssh-add
Enter passphrase for /home/<username>/.ssh/id_rsa:

After entering your passphrase you will see confirmation that your passphrase has been saved:

Identity added: /home/<username>/.ssh/id_rsa (/home/<username>/.ssh/id_rsa)

B.5. Access another writer’s unmerged commits

This is the process you can use if you need commits another writer has submitted in a merge request that is not yet merged.

  1. Check out a new topic branch from upstream/master as you normally do.

    $ git fetch upstream
$ git checkout -b <new-topic-branch> upstream/master

  2. If you have not yet added that writer’s remote repository, add it now.

    $ git remote add -f <user> git@github.com:<user>/strimzi-kafka-operator.git

  3. Rebase to bring in the changes that are in that user’s outstanding origin/<merge-request-branch> branch.

    $ git rebase <user>/<merge-request-branch>

    (you’ll see the following response)

    First, rewinding head to replay your work on top of it...
Fast-forwarded <new-topic-branch> to <user>/<merge-request-branch>

Appendix C: Templates

The following templates must be used to produce consistent modular documentation for Strimzi. Download the adoc files in zip format.

C.1. Doing one procedure

This paragraph is the procedure module introduction: a short description of the procedure.

Prerequisites

  • A bulleted list of conditions that must be satisfied before the user starts following this assembly.

  • You can also link to other modules or assemblies the user must follow before starting this assembly.

  • Delete the section title and bullets if the assembly has no prerequisites.

Procedure

  1. Start each step with an active verb.

  2. Include one command or action per step.

  3. Use an unnumbered bullet (*) if the procedure includes only one step.

Additional resources

C.2. Concept explanation

A short introductory paragraph is required for the concept module. It will provide an overview of the module.

The contents of a concept module give the user descriptions and explanations needed to understand and use a product.

  • Look at nouns and noun phrases in related procedure modules and assemblies to find the concepts to explain to users.

  • Explain only things that are visible to users. Even if a concept is interesting, it probably does not require explanation if it is not visible to users.

  • Do not include any instructions to perform an action, such as executing a command. Action items belong in procedure modules.

Additional resources

C.3. Reference material

A short introductory paragraph is required for the reference module. It will provide an overview of the module.

A reference module provide data that users might want to look up, but do not need to remember. It has a very strict structure, often in the form of a list or a table. A well-organized reference module enables users to scan it quickly to find the details they want. AsciiDoc markup to consider for reference data:

Unordered list
Labeled list
Term 1

Definition

Term 2

Definition

Table 8. Table
Column 1 Column 2 Column 3

Row 1, column 1

Row 1, column 2

Row 1, column 3

Row 2, column 1

Row 2, column 2

Row 2, column 3

Revised on 2019-11-16 01:05:45 UTC