Mastering Fluent Bit: Beginners Guide for Contributing to our CNCF Project Docs

This series is a general purpose getting started guide for those of us wanting to learn about the Cloud Native Computing Foundation (CNCF) project Fluent Bit.

Each article in this series addresses a single topic by providing insights into what the topic is, why we are interested in exploring that topic, where to get started with the topic, and how to get hands-on with learning about the topic as it relates to the Fluent Bit project.

The idea is that each article can stand on its own, but that they also lead down a path that slowly increases our abilities to implement solutions with Fluent Bit telemetry pipelines.

Let's take a look at the topic of this article, contributing to the Fluent Bit docs project. This is a follow-up to our previous article on contributing to the Fluent Bit project website, and this time we go a step further by tackling documentation contributions. If we can find something undocumented, clarify something confusing, or fix a gap between what the code does and what the docs say — that is a genuine contribution that the community notices.

All examples in this article have been done on OSX and are assuming the reader is able to convert the actions shown here to their own local machines.

Contributing to the Fluent Bit docs project?

Before diving into the hands-on steps, let's understand why contributing to the Fluent Bit docs matters and why it's a great fit for anyone new to contributing to a CNCF project.

The Fluent Bit documentation is the first place developers go when they are trying to figure out how to configure an input plugin, wire up an output, or understand a pipeline behavior. Gaps in that documentation have a real cost — people waste time, open issues that aren't actually bugs, or simply give up. When you fix a doc, you are helping every developer who comes after you.

Contributing docs also gives you a natural reason to dig into the code. You often end up reading the actual source to understand what a plugin really does before you write about it. That is how you start building the intuition that eventually gets you contributing code too. But for now, let's start with documentation and get our first PR in.

Where to get started

This time we have two repositories we need to work on the docs project. The docs project does not live in the same place as the code project, and both are relevant to any fixes we are making as we want to verify everything against the existing code.

The first project is the code project found at fluent/fluent-bit, the upstream canonical source code repository, and we need to fork it to our own username/fluent-bit-fork. Easy enough to do using the GitHub UI. We reference the code project when we need to understand what a feature actually does in practice before we document it. Note, as with our previous article, the fork has been renamed with the -fork suffix to make it easy to identify at a glance. We clone this fork to our location machine.

# Fork the original code project using GitHub.

#

# Check out the fork locally, here using my fork as an example.

$ git clone git@github.com:eschabell/fluent-bit-fork.git

# Add the upstream website repo.

$ git remote add upstream https://github.com/fluent/fluent-bit.git

The second project is the docs project found at fluent/fluent-bit-docs, the upstream documentation repository where all the actual docs content lives, and we need to fork this to our own username/fluent-bit-docs-fork. This is where our documentation changes will land.

# Fork the original docs project using GitHub.

#

# Check out the fork locally, here using my fork as an example.

$ git clone git@github.com:eschabell/fluent-bit-docs-fork.git

# Add the upstream website repo.

$ git remote add upstream https://github.com/fluent/fluent-bit-docs.git

So now we've set up both locally, forking each repository on GitHub, then cloning and adding the upstream remote for each, just as we did in the previous article.

This is a habit worth building from day one — always sync from upstream before starting any new contribution, This prevents the diverged branch headache that will slow down our pull request later, see below for my example:

# Fetch any upstream work done by others.

$ git fetch upstream

# Sync local fork with the upstream changes.

$ git rebase upstream/master

# Last step, push to your fork's repository.

$ git push

Now we are ready to get started with our first change to the Fluent Bit docs.

Finding a fix that is needed

There are two natural ways to find something worth fixing. The first is the GitHub issues list on the fluent-bit-docs repository. Look for issues tagged with documentation, help wanted, or good first issue. These are explicitly flagged by maintainers as accessible starting points. I'll be honest with you though, we don't have a lot of those. We tend to keep our issues list on the docs site to a minimum. 

The second, and frankly more satisfying, is to discover something yourself. Again, being honest with you, using AI to assist you in this is making this path easier than you might think. Either way, when exploring a plugin page and notice a spelling mistake, a missing configuration option, or just wanting to add an example configuration you've used yourself are all valid ways to get started. 

Maybe you try to follow an example and find it no longer works with the current version. Sometimes you can discover a mismatch between what the docs describe and what the code in your fluent-bit-fork actually does (or your AI explorations reveal). That kind of gap is a real contribution waiting to happen. Cross-referencing the docs against the code is exactly the kind of work maintainers appreciate and rarely have enough time to do themselves.

Either way, a nice-to-have habit worth building: open a GitHub issue on fluent-bit-docs before starting the work. Describe what you found and what you plan to fix. It takes just a few minutes, gives maintainers visibility, allows you to ask any questions you might have, and means your PR can reference fixing a specific issue number when you submit it. 

Start with a branch

Once you have found something to fix, it should be noted that the common practice is to never work directly on our main branch. Every change, no matter how small, gets its own branch. The branch name should be descriptive enough to focus on the changes you are making. I personally always use my name to preface all branches as it makes it easier to find in larger listings of branches for bigger projects.

Below is an example of a real branch I was working on recently in the Fluent Bit docs project.

# Starting in our forked master.

$ git checkout -b erics_processors_tda_fixes 

Switched to a new branch 'erics_processors_tda_fixes'

---

Note this is also listing the path the the file I'm working on during this fix. Another standard way of working that I like to apply.

Now make the actual documentation changes. The fluent-bit-docs repository uses Markdown files organized by topic area. Find the relevant file, make your edit, and use the structure and conventions you see in the surrounding content as your guide. The project has a specific style and voice — mirror it rather than going off on your own. Keep the change focused. One file per commit (and if possible, per PR) is a better habit than bundling five things together, especially when you are starting out. 

Testing documentation changes

The docs project uses Vale for prose linting, which checks style consistency and catches common documentation issues before they reach the reviewers. Run it locally before committing so you are not finding out about style violations in CI after the PR is already open.

The following shows a run that basically passes, but has a few suggestions mentioned. It's common to find them outside the. applied changes, and if you do, it's not a bad habit to try and fix them with the changes you are making to this file. 

# Testing docs changes uses Vale to parse against our project rules.

$ vale pipeline/processors/tda.md

pipeline/processors/tda.md
 65:1   suggestion  Spelling check: 'x_t'?                                                  FluentBit.Spelling
 65:12  suggestion  Spelling check: 'x_t'?                                                  FluentBit.Spelling
 91:27  suggestion  Spelling check: 'x_i'?                                                  FluentBit.Spelling
 94:18  suggestion  Spelling check: 'x_i'?                                                  FluentBit.Spelling
 94:24  suggestion  Spelling check: 'x_j'?                                                  FluentBit.Spelling
 156:4  suggestion  'Interpreting Betti numbers' should use sentence-style capitalization.  FluentBit.Headings

✔ 0 errors, 0 warnings and 6 suggestions in 1 file.

# Once you have completed all fixes, the Vale test should run as follows.

$ vale pipeline/processors/tda.md

✔ 0 errors, 0 warnings and 0 suggestions in 1 file.

This is the docs equivalent of making sure the unit tests pass before you commit code — it shows respect for the reviewers' time and signals that you know the contribution process.

Committing changes

Before committing, take a moment to compose a proper commit message. This is not optional and it is not a formality. A good commit message tells the story of what changed and why, and it is the permanent record you are attaching your name to.

The format to follow: a short subject line (under 72 characters) describing the change, a blank line, then a bullet list in the body covering specifically what was modified and the reason behind each change. Note that a good habit is to indicate the file change location in the first line as shown.

# A good commit message.

#

docs: pipeline: processors: tda: doc validation fixes

  - Fix sentence-case heading (TDA title)
  - Merge hard-wrapped paragraph lines for GitBook rendering
  - Add LaTeX math delimiters to R^{mD} notation
  - Fix MD060 table column alignment in parameters and metrics tables
  - Sort configuration parameters table alphabetically.

  Fixes issue #2999.

The last line in the commit is used to point to the issue that this change is addressing. If you tag your commit message with the issue number, it will auto-close the issue on the merge of this docs PR into the master branch. The following is the workflow for adding, committing, and pushing your changes.

# When ready to submit our changes.

$ git add pipeline/processors/tda.md

# Commit the changes using a signed commit (assumes GPG set up).

$ git commit -S

# Push the changes to our repository

# git push --set-upstream origin erics_processors_tda_fixes  

Now we open a pull request against fluent/fluent-bit-docs from the GitHub UI. In the pull request description it should automatically fill with your commit message details. Be sure to explicitly request a review — do not assume the PR will be picked up automatically, and make sure to tag a reviewer. If for some reason it's not possible to request a review through the UI, then feel free to post a comment after submitting the PR and ask me (@eschabell) to review as I'm always happy to help.

AI good habits for contributors

This section is worth paying close attention to, because AI tooling is now part of many developers' daily workflow and if used carelessly in an open source context it can create real problems and broken trust with core project maintainers.

Here are my personal ground rules for working with AI assistance on open source projects and how I work with Fluent Bit projects.

Use your local fork filesystem

Configure your AI tool to work against your local fork checkouts — not a downloaded copy to /tmp or any other ephemeral scratch directory. This is important because your working directory is already version-controlled. Every change the AI proposes is immediately visible via git diff, which means you always know exactly what changed before you decide to commit anything. It also saves on token usage and bandwidth speeding up the AI results to your queries.

Never let AI modify without your approval

I always set a personal rule: no line of code or documentation changes without your explicit review and approval, line by line. AI tools should propose changes and you accept, reject, or modify them. This is not just good open source hygiene — it is how you learn the codebase and the project's conventions. The Fluent Bit docs and website have a specific voice and structure. Furthermore, you are putting your name (signing the commits) on any changes you are pushing, so you might want to make sure you agree with each line that is being modified in your name.

Never let AI touch git

This one is non-negotiable for me in git interactions with my upstream repositories. AI does not commit, does not push, does not fork, and does not open pull requests in my inner developer loop. I do all of that manually. Commits are attribution. When you sign a commit with your name and email, you are asserting that you wrote or have the right to submit that content. In a CNCF project operating under a DCO (Developer Certificate of Origin), this is a legal and community trust matter, not a formality. Keep your hands on the wheel for all git operations and you will also understand the processes and retain your skills.

Check for tests when adding new code

This one is more for code based repositories, but good to know as background information here. If your contribution goes beyond a documentation change and into actual code — a plugin, a configuration example, a script — check whether the Fluent Bit fork has existing test patterns for that area. Follow them. If you are adding testable behavior, add tests. Ask in the PR or issue if you are unsure what test coverage is expected. Maintainers would rather answer that question up front than request changes after review.

Always provide a proper commit message

Every commit should have a clear, structured message. At minimum: a short subject line describing what changed, followed by a list in the body describing why and what specifically was modified. It must be signed or it will fail on DCO sign-off  in the CI/CD process. Check the contributing guide for the expected standard. A good commit message is also your own paper trail — if a maintainer asks why you changed something, your commit history should answer the question. Remember, you are signing this, not your AI tooling.

Nice to have: open an issue before a PR

For anything beyond a trivially obvious contribution, the best practice is to open a GitHub issue first. Describe what you want to write or fix, get a signal from the maintainers that it is welcome, then do the work and open the PR referencing that you are fixing that issue.

More in the series

In this article we explored step-by-step what it takes to make our first documentation contribution to the Fluent Bit docs project — from setting up our fork, testing Vale locally, and submitting a pull request. Finally we tried to help with establishing good habits around AI tooling along the way.

There will be more in this series as you continue to learn how to configure, run, manage, and master the use of Fluent Bit in the wild. Get started with Fluent Bit today using this online free workshop.