Strimzi

https://strimzi.io/
Admin
Strimzi provides a way to run an Apache Kafka cluster on Kubernetes in various deployment...
Tokens:5,566
Snippets:101
Trust Score:9.5
Update:4 months ago
Show doc for...
Tokens:
Raw
### YAML Configuration Example

Source: https://strimzi.io/contributing/guide

An example of a YAML configuration block for a Kafka resource, demonstrating AsciiDoc source formatting with subs, callouts, and omitted lines.

```yaml
[source,yaml,subs="+quotes,attributes"]
----
```

```yaml
apiVersion: {KafkaApiVersion}
kind: Kafka
metadata:
  name: my-cluster
spec:
  kafka:
    replicas: **3** # <1> **(2)**
    # ... **(3)**
----
```

--------------------------------

### Build a Single Guide with AsciiDoctor

Source: https://strimzi.io/contributing/guide

Use this command to build a specific documentation guide using AsciiDoctor. Replace `<path_to_overview.adoc>` with the actual path to the AsciiDoc file.

```bash
asciidoctor <path_to_overview.adoc>
```

--------------------------------

### Reference File Naming Example

Source: https://strimzi.io/contributing/guide

Example of naming a reference module file with the 'ref-' prefix.

```asciidoc
ref-list-of-mirrormaker2-resources.adoc
```

--------------------------------

### Assembly File Naming Example

Source: https://strimzi.io/contributing/guide

Example of naming an assembly module file with the 'assembly-' prefix.

```asciidoc
assembly-deploy-kafka-cluster.adoc
```

--------------------------------

### External Link Example

Source: https://strimzi.io/contributing/guide

Example of creating an external link in AsciiDoc.

```asciidoc
link:github.com[GitHub^]
```

--------------------------------

### Snippet File Naming Examples

Source: https://strimzi.io/contributing/guide

Examples of how to name snippet files, including the 'snip-' prefix and dashed words.

```asciidoc
snip-intro-custom-resources
```

--------------------------------

### Example Table Headings

Source: https://strimzi.io/contributing/guide

Demonstrates how to define table headings and content for file connectors.

```adoc
.File connectors
[cols="2*",options="header"]
|===

|File Connector
|Description

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

--------------------------------

### Procedure File Naming Example

Source: https://strimzi.io/contributing/guide

Example of naming a procedure module file with the 'proc-' prefix.

```asciidoc
proc-creating-logging-filters.adoc
```

--------------------------------

### Install Git on Fedora

Source: https://strimzi.io/contributing/guide

Use this command to install Git on Fedora systems. Choose the appropriate command based on your Fedora version.

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

--------------------------------

### Concept File Naming Example

Source: https://strimzi.io/contributing/guide

Example of naming a concept module file with the 'con-' prefix.

```asciidoc
con-pod-management.adoc
```

--------------------------------

### Example Image Caption and Description

Source: https://strimzi.io/contributing/guide

Illustrates how to add an image caption and description in the documentation.

```adoc
.Operators within the Strimzi architecture
image:operators.png[Operators within the Strimzi architecture]
```

--------------------------------

### Generate HTML Documentation

Source: https://strimzi.io/contributing/guide

Generates HTML versions of all the documentation guides. The output is placed in the `documentation/html` directory. Run this from the root of the strimzi-kafka-operator project.

```bash
make docu_html
```

--------------------------------

### Internal Link Example

Source: https://strimzi.io/contributing/guide

Example of creating an internal link (cross-reference) in AsciiDoc.

```asciidoc
xref:doc_id[Section Title]
```

--------------------------------

### Generate HTML Documentation Without Headers

Source: https://strimzi.io/contributing/guide

Generates HTML versions of all the documentation guides, excluding HTML headers. This is suitable for embedding in other websites. Run this from the root of the strimzi-kafka-operator project.

```bash
make docu_htmlnoheader
```

--------------------------------

### KafkaUserQuotas Schema Reference Example

Source: https://strimzi.io/contributing/guide

Shows how to include additional configuration descriptions for the KafkaUserQuotas custom resource within the Strimzi Custom Resource API Reference.

```adoc
### `KafkaUserQuotas` schema reference

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

--------------------------------

### Inline Image in Step Example

Source: https://strimzi.io/contributing/guide

Format for using an inline image within a step in AsciiDoc.

```asciidoc
. My step
+
image:<image_name>.png[<description_of_image>]
```

--------------------------------

### Image Inclusion Example

Source: https://strimzi.io/contributing/guide

Format for adding an image to a section in AsciiDoc.

```asciidoc
.Title of image
image:<image_name>.png[<description_of_image>]
```

--------------------------------

### Add SSH Key Passphrase to ssh-agent

Source: https://strimzi.io/contributing/guide

Configure `ssh-agent` to remember your SSH key passphrase, avoiding repeated prompts. Add the key using `ssh-add` after initial setup.

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

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

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

--------------------------------

### Include Strimzi Modules for API Reference

Source: https://strimzi.io/contributing/guide

These include directives are used in the Strimzi Custom Resource API Reference guide to incorporate common configuration properties and CRD definitions.

```adoc
include::modules/con-common-configuration-properties.adoc[leveloffset=+1]
include::modules/appendix_crds.adoc[]
```

--------------------------------

### Navigate to Repository Directory

Source: https://strimzi.io/contributing/guide

Change the current directory to the newly cloned Strimzi repository folder.

```bash
$ cd strimzi-kafka-operator/
```

--------------------------------

### Abstract Tagging

Source: https://strimzi.io/contributing/guide

How to mark the introductory paragraph of a file as an abstract using the [role="_abstract"] tag.

```asciidoc
[role="_abstract"]
Start each file with an introductory paragraph.
```

--------------------------------

### Checkout Main Branch

Source: https://strimzi.io/contributing/guide

Command to switch to the main branch of the local repository.

```bash
git checkout main
```

--------------------------------

### Clean Documentation Build Files

Source: https://strimzi.io/contributing/guide

Deletes all temporary files related to documentation builds. Run this from the root of the strimzi-kafka-operator project.

```bash
make docu_clean
```

--------------------------------

### Java Annotations for Strimzi Documentation Generation

Source: https://strimzi.io/contributing/guide

Demonstrates the Java annotations used to generate documentation for Strimzi Custom Resources directly from code.

```java
import io.strimzi.crdgenerator.annotations.Description;
import io.strimzi.crdgenerator.annotations.DescriptionFile;
```

--------------------------------

### Clone Repository using SSH

Source: https://strimzi.io/contributing/guide

Clone your forked Strimzi repository to your local machine using the SSH protocol. Replace '<username>' with your GitHub username.

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

--------------------------------

### Check Documentation Integrity

Source: https://strimzi.io/contributing/guide

Executes the documentation checks defined in `.azure/scripts/check_docs.sh`. Run this from the root of the strimzi-kafka-operator project.

```bash
make docu_check
```

--------------------------------

### Clone Repository using HTTPS

Source: https://strimzi.io/contributing/guide

Clone your forked Strimzi repository to your local machine using the HTTPS protocol. Replace '<username>' with your GitHub username. You will be prompted for credentials.

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

--------------------------------

### User-Replaced Values in AsciiDoc

Source: https://strimzi.io/contributing/guide

Illustrates how to style user-replaceable values using angle brackets and monospace, and how to enable rendering in source blocks.

```asciidoc
<my_replaceable>
```

```asciidoc
`<my_code_replaceable>`
```

```asciidoc
subs="+quotes"
```

--------------------------------

### List Current Git Remotes

Source: https://strimzi.io/contributing/guide

Lists the currently configured remote repositories for your local Git repository. This is useful for verifying existing remotes before adding new ones.

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

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

--------------------------------

### Add New Files to Repository

Source: https://strimzi.io/contributing/guide

Commands to check the status of files and add new or modified files to the staging area.

```bash
git status
git add <file-name>
```

--------------------------------

### Open SSH Key for Editing

Source: https://strimzi.io/contributing/guide

Open the SSH public key file (id_rsa.pub) in the vi editor to copy its contents. Ensure you are in the ~/.ssh directory.

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

--------------------------------

### Content Type Definitions

Source: https://strimzi.io/contributing/guide

Required content type definitions for each documentation file.

```asciidoc
:_mod-docs-content-type: ASSEMBLY
```

```asciidoc
:_mod-docs-content-type: PROCEDURE
```

```asciidoc
:_mod-docs-content-type: CONCEPT
```

```asciidoc
:_mod-docs-content-type: REFERENCE
```

```asciidoc
:_mod-docs-content-type: SNIPPET
```

--------------------------------

### Configure Git User Name and Email

Source: https://strimzi.io/contributing/guide

Set your global Git user name and email address. This is required for committing changes.

```bash
$ git config --global user.name "<your-name>"
$ git config --global user.email "<your-email>"
```

--------------------------------

### Update Local Repository and Fork

Source: https://strimzi.io/contributing/guide

Commands to synchronize the local repository and fork with the upstream main branch.

```bash
git pull upstream main
git push origin main --force
```

--------------------------------

### Verify Added Upstream Remote (HTTPS)

Source: https://strimzi.io/contributing/guide

Confirms that the 'upstream' remote repository has been successfully added using HTTPS. It displays both the fetch and push URLs for the new remote.

```bash
$ 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)
```

--------------------------------

### Anchor ID and Module Heading Structure

Source: https://strimzi.io/contributing/guide

Required structure for anchor IDs and module headings, including the use of context variables.

```asciidoc
[id='name-of-file_{context}']
= Module Heading

First sentence of module.
```

--------------------------------

### Verify Added Upstream Remote (SSH)

Source: https://strimzi.io/contributing/guide

Confirms that the 'upstream' remote repository has been successfully added using SSH. It displays both the fetch and push URLs for the new remote.

```bash
$ 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)
```

--------------------------------

### Push Changes to Fork

Source: https://strimzi.io/contributing/guide

Command to push local commits to the remote fork.

```bash
git push origin HEAD
```

--------------------------------

### Fetch and Checkout Unmerged Commits from Another Writer

Source: https://strimzi.io/contributing/guide

Process to access and integrate unmerged commits from another contributor's merge request. This involves fetching their remote, checking out a new branch, and rebasing.

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

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

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

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

--------------------------------

### Configure Git Defaults

Source: https://strimzi.io/contributing/guide

Set global Git defaults for pull and push operations. This configures Git to use rebase for pulls and a simple push strategy.

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

--------------------------------

### Check for Public SSH Key

Source: https://strimzi.io/contributing/guide

Verify if a public SSH key already exists in your ~/.ssh directory. This is a prerequisite for adding SSH keys to GitHub.

```bash
$ ls ~/.ssh/
```

--------------------------------

### Generate SSH Key

Source: https://strimzi.io/contributing/guide

Generate a new SSH key pair if one does not already exist. Replace '<your-email>' with your actual email address.

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

--------------------------------

### Regenerate Strimzi Custom Resource API Reference

Source: https://strimzi.io/contributing/guide

Regenerates the API Reference from Java code, which is necessary if changes are made to the `api` module. Ensure `yq` is up-to-date. Run this from the root of the strimzi-kafka-operator project.

```bash
mvn clean -DskipTests install
make crd_install
```

--------------------------------

### Reset Fork to Match Upstream Main

Source: https://strimzi.io/contributing/guide

Resets your local fork to match the `upstream/main` branch, useful when your fork is out of sync. Requires force pushing to your origin.

```bash
$ git checkout main
$ git reset --hard upstream/main
$ git push origin main --force
$ git pull upstream main
$ git push origin main --force
```

--------------------------------

### Create New Branch

Source: https://strimzi.io/contributing/guide

Command to create a new branch for feature development, optionally using the issue number.

```bash
git checkout -b <branch-name>
```

--------------------------------

### Merge Changes if Rejected

Source: https://strimzi.io/contributing/guide

Commands to merge upstream changes and force-push to the fork if the push is rejected due to being behind.

```bash
git pull upstream main
git push -f origin HEAD
```

--------------------------------

### Fetch Latest Source Code from Upstream

Source: https://strimzi.io/contributing/guide

Fetches the latest changes from the 'upstream' remote repository. This command is used to update your local repository with the most recent code.

```bash
$ git fetch upstream
```

--------------------------------

### Add Upstream Repository via HTTPS

Source: https://strimzi.io/contributing/guide

Adds the official Strimzi Kafka Operator repository as an 'upstream' remote using HTTPS. This allows fetching the latest source code from the original repository.

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

--------------------------------

### Add Upstream Repository via SSH

Source: https://strimzi.io/contributing/guide

Adds the official Strimzi Kafka Operator repository as an 'upstream' remote using SSH. This allows fetching the latest source code from the original repository.

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

--------------------------------

### Delete All Local Branches Except Current

Source: https://strimzi.io/contributing/guide

Use this command to clean up local branches when you want to remove all branches except the one you are currently on. Ensure you are on the main branch before executing.

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

--------------------------------

### Commit Changes

Source: https://strimzi.io/contributing/guide

Command to commit staged changes with a signed-off message, indicating compliance with the DCO.

```bash
git commit -a -s -m "<message>"
```

--------------------------------

### Update Upstream Repository URL

Source: https://strimzi.io/contributing/guide

Changes the URL of the 'upstream' remote repository. Use this command if the original repository's location has moved.

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

--------------------------------

### Resolve Merge Conflicts in a Pull Request

Source: https://strimzi.io/contributing/guide

Steps to resolve merge conflicts when working with a pull request. This involves checking out the branch, setting upstream, rebasing, and force pushing.

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

--------------------------------

### Delete a Specific Local Branch

Source: https://strimzi.io/contributing/guide

Command to delete a single local branch. Replace `<branch-name>` with the actual name of the branch you wish to remove. Always checkout `main` first.

```bash
$ git checkout main
$ git branch -D <branch-name>
```
Tokens:
Raw