Strimzi Documentation Contributor Guide

Strimzi Documentation Contributor Guide

Table of Contents

1. Introduction

This guide provides information to assist contributors to the Strimzi documentation.

Strimzi documentation is written in Asciidoc.

Inclusive language

Strimzi is committed to using inclusive and respectful language in its code, web pages, and documentation. Contributions to the documentation, as with code submissions, must not contain problematic terms or phrases.

1.1. Documentation tools

The following tools are needed to build the documentation:

asciidoctor

Documentation generation tool

make

Make build system to build complete documentation

yq

YAML build tool to build documentation using make targets

Additionally, for generating the API reference you will also need:

java

Java for building code and generating the API reference

mvn

Maven for running the Java build

For most documentation updates, asciidoctor offers the simplest way to check the build.

1.2. Project layout

Strimzi uses public GitHub repositories to host files. The following repositories contain source documentation files.

strimzi-kafka-operator (GitHub)

Strimzi operators code and related documentation.

strimzi-kafka-bridge (GitHub)

Strimzi Kafka Bridge code and related documentation.

strimzi.github.io (GitHub)

Strimzi web site code and quick start documentation.

1.3. Strimzi operators documentation

The main Strimzi documentation is maintained in the /documentation folder of the Strimzi Operators repository. The documentation folder is split into category folders to manage the content.

Documentation category folders contain files related to Strimzi guides (Deploying, Overview, Using), and the files that provide the content for one or more of these guides – assemblies and modules. Assemblies, which usually encapsulate a feature or process, bring the related content contained in modules together.

An assembly is like a sub-section or chapter in a book. For example, the Deploying and Upgrading Strimzi guide has a chapter called Verifying the Strimzi deployment, which is contained in its own assembly.

Documentation folder descriptions
api/                          # Property descriptions for the Custom Resource API Reference section of the Configuring Strimzi guide
contributing/                 # Documentation contributor guide (this book)
deploying/                    # Deploying Strimzi
overview/                     # Strimzi Overview guide
configuring/                  # Configuring Strimzi
assemblies/                   # Assemblies provide content for all guides
modules/                      # Modules provide the content for assemblies
shared/                       # Shared include files
shared/attributes.adoc        # Global book attributes
shared/images/                # Shared image files

1.3.1. Strimzi Overview guide

The intention of the Strimzi Overview guide is for developing an understanding of Strimzi and Apache Kafka. The guide does not contain any instructions. It provides an overview of the concepts behind Apache Kafka, the Kafka component architecture, and how Strimzi supports Kafka in a Kubernetes cluster. The guide also describes how Strimzi Operators help manage a deployment.

The guide contains high-level outlines of the processes required to deploy, configure, secure and monitor a deployment of Strimzi.

1.3.2. Deploying and Upgrading Strimzi

The Deploying and Upgrading Strimzi guide provides instructions on all the options available for deploying and upgrading Strimzi. The guide describes what is deployed, and the order of deployment required to run Apache Kafka in a Kubernetes cluster.

As well as describing the deployment steps, the guide also provides pre- and post-deployment instructions to prepare for and verify a deployment. Additional deployment options described include the steps to introduce metrics.

Upgrade instructions are provided for Strimzi and Kafka upgrades.

1.3.3. Configuring Strimzi

The Configuring Strimzi guide provides configuration instructions for Kafka components, and instructions for using Strimzi Operators. The majority of the content relates to how you might want to modify your deployment and introduce additional features, such as Cruise Control or distributed tracing.

1.3.4. Custom Resource API Reference

The Configuring Strimzi guide (documentation/configuring/configuring.adoc) also contains a Custom Resource API Reference that describes the configuration properties for custom resources.

The Custom Resource API Reference is built from two files.

Custom Resource API Reference files
include::modules/con-common-configuration-properties.adoc[leveloffset=+1]
include::modules/appendix_crds.adoc[]

The con-common-configuration-properties.adoc file contains descriptions of common configuration properties. The content for the documentation/modules/appendix_crds.adoc file is generated directly from descriptions in the Java code.

Java files in the api/ folder are annotated so that the descriptions are picked up in the build.

Java annotations for documentation
import io.strimzi.crdgenerator.annotations.Description;
import io.strimzi.crdgenerator.annotations.DescriptionFile;

The tables in appendix_crds.adoc are built from @Description annotations in the Java files.

Additional information is included by adding:

  1. An @DescriptionFile annotation to the Java file

  2. A corresponding description file (.adoc) in the documentation/api/ folder

  3. An include:DESCRIPTION-FILE-NAME reference to the appendix_crds.adoc

The include:DESCRIPTION-FILE-NAME reference is added automatically by the Maven build, so you do not need to add it manually.

For example, to add additional configuration for the KafkaUserQuotas custom resource:

  1. api/src/main/java/io/strimzi/api/kafka/model/KafkaUserQuotas.java contains:

    • import io.strimzi.crdgenerator.annotations.Description

    • import io.strimzi.crdgenerator.annotations.DescriptionFile

    • @Description("descriptions for individual properties…​");

    • An @DescriptionFile annotation

  2. documentation/api includes the io.strimzi.api.kafka.model.KafkaUserQuotas.adoc file containing the additional configuration description.

    The description file requires the same name as the related Java package.

  3. appendix_crds.adoc contains a reference to include the additional configuration description:

    ### `KafkaUserQuotas` schema reference

/include::../api/io.strimzi.api.kafka.model.KafkaUserQuotas.adoc[leveloffset=+1]

If you change anything in the api module of the Java code, you must rebuild the Custom Resource API Reference using a make command.

1.4. Kafka Bridge documentation

The Kafka Bridge documentation shows how to get started using the Kafka Bridge to make HTTP requests to a Kafka cluster.

The Kafka Bridge documentation is maintained in the Strimzi Kafka Bridge project in GitHub. For information on contributing to the Kafka Bridge documentation, see the readme in the Strimzi Kafka Bridge project.

1.5. Quick start documentation

Strimzi quick starts provide instructions for evaluating Strimzi using Minikube, Kubernetes kind, or Docker Desktop. Steps describe how to deploy and run Strimzi as quickly as possible, with minimal configuration.

The quick starts are maintained in the Strimzi website project in GitHub. For information on contributing to the quick starts, see the readme in the Strimzi website project.

2. Contributing to the documentation

This section shows you how to contribute to the Strimzi documentation and contains important guidelines for creating accessible content.

2.1. Getting started

Before you begin you need to:

  1. Install and set up Git

2.2. Accessibility guidelines

Strimzi aims to make its content accessible. When contributing to the documentation, ensure that your content adheres to the following guidelines:

  • Images:

    • Include a caption

    • Provide alternative text

    • Are described in the surrounding text

  • Images of text are not used (such as with code fragments)

  • Links provide descriptive text about the target (not click here)

  • Tables:

    • Include a caption

    • Contain headings

    • Provide a logical reading order

    • Don’t contain empty cells

  • Color is not used as the only visual means to convey information (not check the green text)

Example image caption and description
.Operators within the Strimzi architecture
image:operators.png[Operators within the Strimzi architecture]
Example table headings
.File connectors
[cols="2*",options="header"]
|===

|File Connector
|Description

|FileStreamSourceConnector
|Transfers data to your Kafka cluster from a file (the source).
|===

2.3. Contributing to the documentation

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

You add content to the documentation hosted on GitHub using pull requests (PRs).

Reviewers might be assigned to the PR depending on the changes. A review from a Subject Matter Expert (SME) will check the technical aspects of the content. The PR might not require an SME review if you’re only fixing a typo or broken link.

Procedure

  1. Open your terminal

  2. cd to the directory where your documentation resides

  3. Checkout the main branch

    $ git checkout main

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

    $ git pull upstream main
$ git push origin main --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 main
$ git push -f origin HEAD

  13. Visit your fork on GitHub

  14. Click Compare & pull request

3. 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`

4. Style guidelines

4.1. Adding code and configuration examples

The Strimzi documentation contains many code and configuration examples. Examples are a useful way of demonstrating a process.

If you want to add example code and configuration to your contribution, use the following format in an asciidoc code block.

Configuration example
[source,yaml,subs="+quotes,attributes"] (1)
----
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: 3 # <1> (2)
    # ... (3)
----

  1. Syntax for the example. Here the source language is yaml. Use subs to apply attributes and formatting. In this example, kafka.strimzi.io/v1beta2 is substituted with an attribute value specified in the /shared/attributes.adoc file. If quotes is specified in subs, asciidoc formatting is applied to the code block. Here, bold is applied to the 3 value of replicas. If quotes isn’t used, asciidoc formatting is ignored in the code block.

  2. Add callouts to describe a line of code or configuration. Use a hash (#) before the callout number so that the example is copy-friendly.

  3. Use a hash and ellipsis (# …​) to show that part of the code or configuration has been omitted.

4.2. 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.

  • 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].

4.3. 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.

4.4. 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]

4.5. 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]

4.6. 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)

4.7. User-replaced values

Style user-replaced values (replaceables) with angle brackets (< >) and italics. Use underscores ( _ ) for multi-word values. If you are referencing code or commands, also use monospace.

Table 6. User-replaced values quick reference
Value Shows as

_<my_replaceable>_

<my_replaceable>

`_<my_code_replaceable>_`

<my_code_replaceable>
Tip
 If adding a user-replaced value within a source code block, add subs="+quotes" to the source tag for it to render. (For example : [source,shell,subs="+quotes"]).
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.

5. Screenshot guidelines

5.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.

5.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.

5.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.

5.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).

5.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!

5.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.

5.7. Browser extensions

5.7.1. Resizing screenshots

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

6. 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 main.

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.

6.1. Make commands to build documentation

make docu_clean

Delete all temporary files

make docu_check

Execute the documentation checks in .azure/scripts/check_docs.sh

make docu_html

Generate the HTML version of all the guides (the HTML files can be found in `documentation/html)

make docu_htmlnoheader

Generate the HTML version of all the guides without the HTML headers so they are suitable for including into a website (the HTML files can be found in `documentation/htmlnoheader)

6.2. Generate the Custom Resource API Reference

The documentation/modules/appendix_crds.adoc file provides the main content for the Custom Resource API Reference. It is generated directly from the Java code when building the operators.

If you change the Strimzi API, you need to regenerate the API Reference before submitting your PR by running the following from the root:

mvn clean -DskipTests install
make crd_install

The build uses yq, so make sure it is kept up-to-date for it to work properly.

Note
 You only have to generate the Custom Resource API Reference if you changed anything in the api module of the Java code.

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: Setting up git

This section explains how to set up your system to connect to the proper git repositories.

B.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

B.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

B.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.

B.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.

B.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/

B.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)

B.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

B.8. References

Appendix C: Git tips

C.1. Delete branches

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

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

To delete one branch:

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

C.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 main
$ git push -f origin HEAD

C.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 main
$ git reset --hard upstream/main
$ git push origin main --force
$ git pull upstream main
$ git push origin main --force

C.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 main
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)

C.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/main as you normally do.

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

  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>

Revised on 2023-05-31 21:06:44 UTC