First of all, thanks for taking the time to read this guide. The fact that you're here means you're interested in contributing to Fluent Bit, and we greatly appreciate your time.
This repository contains the files for the Fluent Bit documentation library. Keeping these docs separate from the main Fluent Bit repository helps reduce the number of commits to the Fluent Bit source code and makes it easier to maintain both projects.
Fluent Bit has a group of dedicated maintainers who oversee this repository, including several technical writers. These writers will review any pull requests you open, so don't be afraid to contribute, even if you're not a writer by trade. Your suggestions are valuable, and we'll help you wrangle any stray commas.
Before you contribute to the Fluent Bit docs, review these critical tips:
- Sign off your Git commits.
- Use soft line wraps in Markdown files.
- Review the results of linters for style and formatting guidance.
After you open a pull request in this repository, a Fluent Bit maintainer will review it, add comments or suggestions as needed, and then merge it. After your changes are successfully merged into master, the docs site will update within a few minutes.
If you're contributing documentation for a Fluent Bit feature that's still in development, ask a maintainer to add the waiting-on-code-merge label to your pull request. This lets other maintainers know that your changes aren't ready to merge yet, even if they were approved.
If you open a pull request that requires extended discussion or review, the Fluent Bit maintainers will add a waiting-for-user label to your pull request. This label means that we're blocked from moving forward until you reply. To keep contributions from going stale, we'll wait 45 days for your response, after which we might close the pull request if we don't hear back from you.
To pass this repository's DCO checks, you'll need to adhere to the following Git practices.
To sign commits properly, you must first set your email address in your local Git environment. This should be the same email address associated with your GitHub account.
For more information, refer to GitHub's guide to setting your commit email address in Git.
You must sign off your commits to certify your identity as the commit author. A commit is signed off when its commit message looks like this:
pipeline: outputs: syslog: fix grammar in examples
Signed-off-by: Tux <tux@linux.org>
For faster signing, you can use the -s flag:
git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples"
💡 If you're using VSCode, the Git: Always Sign Off option appends a
Signed-off-by:message to all of your commits.
If a DCO error blocks your pull request from merging, refer to this guide about how to add sign-offs retroactively.
The Fluent Bit documentation follows the Google developer documentation style guide for most topics related to grammar and style. We don't expect you to memorize these style rules, but the maintainers who review your pull request might suggest changes accordingly.
The active linters in this repository flag certain style errors and, in some cases, explain how to fix them.
The Fluent Bit docs library is built and hosted through GitBook. Unfortunately, GitBook doesn't support local previews for contributors, but a Fluent Bit maintainer with a dedicated GitBook account can verify that things are formatted correctly after you open a new pull request.
When GitBook renders pages, it treats all newlines literally, which means hard line wraps in Markdown files create awkward line breaks in the Fluent Bit docs site. Due to this, docs contributions must use soft line wraps.
✅ Example: soft line wraps
Soft-wrapped text uses newlines only to mark the end of a paragraph. From the perspective of a text editor, this means each paragraph looks like a single, unbroken line of text.
After two newlines, another paragraph begins.
🚫 Example: hard line wraps
Hard-wrapped text uses newlines
in the middle of sentences and
paragraphs.
This can make text easier for
humans to read, but GitBook
renders hard line wraps
awkwardly.
By default, Google Docs and Microsoft Word turn standard straight quotes into "smart" curly quotes. If you copy-paste from one of these tools, you must correct the quotes back to straight quotes. You can also turn off smart quotes in Google Docs or Microsoft Word to prevent this problem.
When you create a new .md file for a new page, you must add an entry to this repository's SUMMARY.md file (or ask a maintainer to add it on your behalf). If you don't update SUMMARY.md, the new page won't appear in the table of contents on the Fluent Bit docs site.
Similarly, if you update the # h1 title header of an existing page, be sure to update that page's SUMMARY.md entry to match. SUMMARY.md entries takes precedence over in-page headers, which means that if you update a page's # h1 title without updating SUMMARY.md, the unchanged SUMMARY.md title will persist in both the rendered page and the table of contents.
This repository runs linters as GitHub Actions for each pull request. If a linter finds errors or makes suggested changes, you can view these results in the Files changed tab.
🔍 Examples: linter results
Vale lints prose for style and clarity. In addition to reviewing the results of each Vale test in GitHub, you can use the Vale plugin for VSCode to view errors and suggestions locally.
Vale tests for the Fluent Bit docs are stored in the /vale-styles folder. Most Vale tests are at the suggestion or warning level and won't block pull requests from merging. However, tests at the error level will block merging until the associated issue is fixed.
Markdownlint lints Markdown formatting and makes suggestions for improvements. In addition to reviewing the results of each test in GitHub, you can use the markdownlint plugin for VSCode to view suggestions locally.
Markdownlint tests for the Fluent Bit docs are stored in markdownlint.json. These tests don't block pull requests from merging.
For general guidance about writing documentation, consult the following resources: