|
1 | | -# Fluent Bit Documentation |
2 | | - |
3 | | -First of all, thanks for taking the time to read this document. It means you are interested in contributing, and we highly appreciate the time you are investing. |
4 | | - |
5 | | -## Introduction |
6 | | - |
7 | | -[Fluent Bit Documentation](https://docs.fluentbit.io) source code lives in a separate repository called [fluent/fluent-bit-docs](https://github.com/fluent/fluent-bit-docs) on Github. The reason of this separate repository is to avoid extra commits on Fluent Bit source code project history that leads to more complexity when maintaining the core project: yes, we read the commit history every single day, and usually, we maintain separate branches and this separation simplify the process for us. |
| 1 | +# Contributing to Fluent Bit docs |
| 2 | + |
| 3 | +First of all, thanks for taking the time to read this guide. The fact that you're |
| 4 | +here means you're interested in contributing to Fluent Bit, and we highly appreciate |
| 5 | +your time. |
| 6 | + |
| 7 | +This repository contains the files for the |
| 8 | +[Fluent Bit documentation library](https://docs.fluentbit.io/). Keeping these docs |
| 9 | +separate from the [main Fluent Bit repository](https://github.com/fluent/fluent-bit) |
| 10 | +helps reduce the number of commits to the Fluent Bit source code and makes it |
| 11 | +easier to maintain both projects. |
| 12 | + |
| 13 | +Fluent Bit has a group of dedicated maintainers who oversee this repository, |
| 14 | +including several technical writers. These writers will review any pull requests |
| 15 | +you open, so don't be afraid to contribute—even if you're not a writer by trade. |
| 16 | +Your suggestions are valuable, and we'll help you wrangle any stray commas. |
| 17 | + |
| 18 | +## GitBook |
| 19 | + |
| 20 | +The Fluent Bit docs library is built and hosted through |
| 21 | +[GitBook](https://docs.gitbook.com/). Unfortunately, GitBook doesn't support |
| 22 | +local previews for contributors, but a Fluent Bit maintainer with a dedicated GitBook |
| 23 | +account can verify that things are formatted correctly after you open a new pull |
| 24 | +request. |
| 25 | + |
| 26 | +Each `.md` file in this repository is a single page. You can use |
| 27 | +[standard Markdown syntax](https://docs.gitbook.com/content-editor/editing-content/markdown) |
| 28 | +to edit existing pages, or create a new `.md` file to add an additional page to |
| 29 | +the docs library. If you create a new page, you'll also need to update |
| 30 | +[GitBook's `SUMMARY.md` file](https://docs.gitbook.com/integrations/git-sync/content-configuration#structure) |
| 31 | +(or ask a maintainer to update it for you). |
8 | 32 |
|
9 | 33 | ## Workflow |
10 | 34 |
|
11 | | -All documentation contributions arrives as Pull Requests (PR) on Github in the repository [fluent/fluent-bit-docs](https://github.com/fluent/fluent-bit-docs). Then some of the maintainers of Fluent Bit will review it, triage it, add comments if needed, or merge it. |
| 35 | +After you open a pull request in this repository, a Fluent Bit maintainer will review |
| 36 | +it, triage it, add comments or suggestions as needed, and then merge it. After |
| 37 | +your changes are successfully merged into `master`, the docs site will update |
| 38 | +within a few minutes. |
12 | 39 |
|
13 | | -Once a PR is merged, a third-party service called [Gitbook](https://gitbook.com) will receive a notification and will grab the latest changes, render a new site and update the content of [docs.fluentbit.io](https://docs.fluentbit.io). |
| 40 | +### Stale pull requests |
14 | 41 |
|
15 | | -## Source Code Structure |
| 42 | +If you open a pull request that requires ongoing discussion or review, the |
| 43 | +Fluent Bit maintainers will add a [`waiting-for-user` tag](#tags) to your pull |
| 44 | +request. This tag means that we're blocked from moving forward until you reply. |
| 45 | +To keep contributions from going stale, we'll wait 45 days for your response, |
| 46 | +but we may close the pull request if we don't hear back from you by then. |
16 | 47 |
|
17 | | -Documentation source code structure depends on Fluent Bit source code structure and its versions. In Fluent Bit source code, we have a stable branch and a development branch; as of now, these are: |
| 48 | +## Submit a contribution |
18 | 49 |
|
19 | | -- stable branch: [1.8](https://github.com/fluent/fluent-bit/tree/1.8) |
20 | | -- development branch: [master](https://github.com/fluent/fluent-bit/tree/master) |
| 50 | +When you open a pull request, make your changes against `master`, which is the |
| 51 | +active development branch. If your contribution also applies to the latest |
| 52 | +stable version, submit another PR for that versioned branch. However, if |
| 53 | +submitting multiple PRs at the same time adds too much complexity, you can instead |
| 54 | +create a single PR against `master` and specify that your changes need to be |
| 55 | +**backported** to other branches; one of our maintainers will take care of that |
| 56 | +process on your behalf. |
21 | 57 |
|
22 | | -For Documentation, we follow the same pattern; we have branches for the stable and development versions. |
| 58 | +All contributions must be made **first** against [master branch](https://github.com/fluent/fluent-bit-docs/tree/master) which is the active development branch, and then **if** the contribution also applies for the current stable branch, submit another PR for that specific branch, if submitting another PR adds some complexity, please specify in the first PR as a comment (for master branch) that it needs to be *backported*. One of our maintainers will take care of that process. |
23 | 59 |
|
24 | | -## Submitting Contributions |
| 60 | +As a contributor, we'll ask you to follow a few best practices related to Git: |
25 | 61 |
|
26 | | -All contributions must be made **first** against [master branch](https://github.com/fluent/fluent-bit-docs/tree/master) which is the active development branch, and then **if** the contribution also applies for the current stable branch, submit another PR for that specific branch, if submitting another PR adds some complexity, please specify in the first PR as a comment (for master branch) that it needs to be *backported*. One of our maintainers will take care of that process. |
| 62 | +### One file per commit |
27 | 63 |
|
28 | | -### GIT email check |
| 64 | +Each commit you make should only modify one file or interface—we follow the same |
| 65 | +practice in the Fluent Bit source code. |
29 | 66 |
|
30 | | -Most of the time GIT is not fully configured in your environment, and when cloning the repository and committing changes, the user email might not be set. Make sure your email is properly configured. You can check your current setting with: |
| 67 | +### Commit subjects |
31 | 68 |
|
32 | | -```bash |
33 | | -cd fluent-bit-docs/ |
34 | | -git config user.email |
35 | | -``` |
36 | | - |
37 | | -If you need to adjust your email, do this: |
38 | | - |
39 | | -``` |
40 | | -git config user.email [email protected] |
41 | | -``` |
| 69 | +Use descriptive commit subjects that describe which file or interface you're |
| 70 | +modifying. |
42 | 71 |
|
43 | | -### Commit Subjects |
| 72 | +For example, if you're modifying the Syslog output plugin doc, whose file is |
| 73 | +located at [pipeline/outputs/syslog.md](https://github.com/fluent/fluent-bit-docs/blob/master/pipeline/outputs/syslog.md), this would be a descriptive commit subject: |
44 | 74 |
|
45 | | -The subject must be representative enough to describe which `file` or `interface` is modifying when committing your changes. An everyday use case or example is: |
| 75 | +`pipeline: outputs: syslog: fix grammar in examples` |
46 | 76 |
|
47 | | -- User is enhancing the documentation for the Syslog output plugin |
| 77 | +Since this commit is prefixed with the relevant file path, it helps our maintainers |
| 78 | +understand and prioritize your contribution. |
48 | 79 |
|
49 | | -Considering that Syslog output plugin documentation resides in this address: |
| 80 | +### Set your email in Git |
50 | 81 |
|
51 | | -- [pipeline/outputs/syslog.md](https://github.com/fluent/fluent-bit-docs/blob/master/pipeline/outputs/syslog.md) |
| 82 | +Make sure your email address is configured in your local Git environment. This |
| 83 | +should be the same email address associated with your GitHub account. |
52 | 84 |
|
53 | | -the suggested commit will be: |
| 85 | +For more information, refer to GitHub's guide to |
| 86 | +[setting your commit email address in Git](https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address#setting-your-commit-email-address-in-git). |
54 | 87 |
|
55 | | -``` |
56 | | -pipeline: outputs: syslog: fix grammar in examples |
57 | | -``` |
| 88 | +### Sign off your commits |
58 | 89 |
|
59 | | -As you can see, the commit is prefixed with the paths of the file being modified. For maintainers, this helps to understand and prioritize the review of the contributions. |
| 90 | +You must sign off your commits to certify your identity as the commit author. If |
| 91 | +you don't sign off your commits, our CI system will flag the pull request with a |
| 92 | +[DCO](https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md) |
| 93 | +error and prevent your pull request from merging. |
60 | 94 |
|
61 | | -Usually, a PR can have multiple commits, but we enforce that every commit only touches one file or interface (we apply the same practice in Fluent Bit source code). |
| 95 | +To prevent DCO errors, refer to the following guide about |
| 96 | +[signing your commits properly](https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md). |
62 | 97 |
|
63 | | -### Sign off your commits |
| 98 | +> :bulb: For faster signing, you can use the `-s` flag in Git: |
| 99 | +> |
| 100 | +> `git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples"` |
| 101 | +> |
| 102 | +> If you're using VSCode, you can also enable the |
| 103 | +> [**Git: Always Sign Off**](https://github.com/microsoft/vscode/issues/83096#issuecomment-545350047) |
| 104 | +> setting, which automatically appends a `Signed-off-by:` message to your commits. |
64 | 105 |
|
65 | | -Your commits must be **sign off**; this certifies who is the author of the commit. It might sound a bit redundant, but it is needed. If you don't sign-off your commits, our CI system will flag the PR with a [DCO](https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md) error and the PR will be blocked. |
| 106 | +## Style guidelines |
66 | 107 |
|
67 | | -The following link explains how to fix DCO error by signing your commits properly: |
| 108 | +The Fluent Bit maintainers refer to the |
| 109 | +[Google developer documentation style guide](https://developers.google.com/style) |
| 110 | +for most topics related to grammar, style, and formatting. We don't expect you |
| 111 | +to memorize these style rules, but the technical writer who reviews your pull |
| 112 | +request may suggest changes accordingly. |
68 | 113 |
|
69 | | -- https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md |
| 114 | +### URLs |
70 | 115 |
|
71 | | -For short: always use `-s` when committing your changes, e.g.: |
| 116 | +When cross-linking to a page in this repository, use a full relative path whenever |
| 117 | +possible. For example: |
72 | 118 |
|
| 119 | +```text |
| 120 | +[LTSV](pipeline/parsers/ltsv.md) and [Logfmt](pipeline/parsers/logfmt.md) |
73 | 121 | ``` |
74 | | -git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples" |
75 | | -``` |
76 | 122 |
|
| 123 | +### Vale |
| 124 | + |
| 125 | +The Fluent Bit maintainers use the [Vale](https://vale.sh/docs/) plugin, which lints |
| 126 | +pull requests and adds suggestions to improve style and clarity. |
0 commit comments