-
Notifications
You must be signed in to change notification settings - Fork 498
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1365 from fluent/alexakreizinger/sc-90990/update-…
…fluent-bit-contribution-guide contributing: add sections and update phrasing
- Loading branch information
Showing
3 changed files
with
99 additions
and
54 deletions.
There are no files selected for viewing
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * @fluent/fluent-bit-maintainers @fluent/chronosphere-tech-writers |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,76 +1,118 @@ | ||
| # Fluent Bit Documentation | ||
|
|
||
| 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. | ||
|
|
||
| ## Introduction | ||
|
|
||
| [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. | ||
| # Contributing to Fluent Bit docs | ||
|
|
||
| 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 highly appreciate | ||
| your time. | ||
|
|
||
| This repository contains the files for the | ||
| [Fluent Bit documentation library](https://docs.fluentbit.io/). Keeping these docs | ||
| separate from the [main Fluent Bit repository](https://github.com/fluent/fluent-bit) | ||
| 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. | ||
|
|
||
| ## GitBook | ||
|
|
||
| The Fluent Bit docs library is built and hosted through | ||
| [GitBook](https://docs.gitbook.com/). 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. | ||
|
|
||
| Each `.md` file in this repository is a single page. You can use | ||
| [standard Markdown syntax](https://docs.gitbook.com/content-editor/editing-content/markdown) | ||
| to edit existing pages, or create a new `.md` file to add an additional page to | ||
| the docs library. If you create a new page, you'll also need to update | ||
| [GitBook's `SUMMARY.md` file](https://docs.gitbook.com/integrations/git-sync/content-configuration#structure) | ||
| (or ask a maintainer to update it for you). | ||
|
|
||
| ## Workflow | ||
|
|
||
| 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. | ||
|
|
||
| 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). | ||
|
|
||
| ## Source Code Structure | ||
| After you open a pull request in this repo, a Fluent Bit maintainer will review | ||
| it, triage 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. | ||
|
|
||
| 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: | ||
| ### Stale pull requests | ||
|
|
||
| - stable branch: [1.8](https://github.com/fluent/fluent-bit/tree/1.8) | ||
| - development branch: [master](https://github.com/fluent/fluent-bit/tree/master) | ||
| If you open a pull request that requires ongoing discussion or review, the | ||
| Fluent Bit maintainers will add a [`waiting-for-user` tag](#tags) to your pull | ||
| request. This tag 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, | ||
| but we may close the pull request if we don't hear back from you by then. | ||
|
|
||
| For Documentation, we follow the same pattern; we have branches for the stable and development versions. | ||
| ## Submit a contribution | ||
|
|
||
| ## Submitting Contributions | ||
| When you open a pull request, make your changes against `master`, which is the | ||
| active development branch. If your contribution also applies to the latest | ||
| stable version, submit another PR for that versioned branch. However, if | ||
| submitting multiple PRs at the same time adds too much complexity, you can instead | ||
| create a single PR against `master` and specify that your changes need to be | ||
| **backported** to other branches; one of our maintainers will take care of that | ||
| process on your behalf. | ||
|
|
||
| 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. | ||
| 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. | ||
|
|
||
| ### GIT email check | ||
| As a contributor, we'll ask you to follow a few best practices related to Git: | ||
|
|
||
| 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: | ||
| ### One file per commit | ||
|
|
||
| ```bash | ||
| cd fluent-bit-docs/ | ||
| git config user.email | ||
| ``` | ||
| Each commit you make should only modify one file or interface—we follow the same | ||
| practice in the Fluent Bit source code. | ||
|
|
||
| If you need to adjust your email, do this: | ||
| ### Commit subjects | ||
|
|
||
| ``` | ||
| git config user.email [email protected] | ||
| ``` | ||
| Use descriptive commit subjects that describe which file or interface you're | ||
| modifying. | ||
|
|
||
| ### Commit Subjects | ||
| For example, if you're modifying the Syslog output plugin doc, whose file is | ||
| 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: | ||
|
|
||
| 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: | ||
| `pipeline: outputs: syslog: fix grammar in examples` | ||
|
|
||
| - User is enhancing the documentation for the Syslog output plugin | ||
| Since this commit is prefixed with the relevant file path, it helps our maintainers | ||
| understand and prioritize your contribution. | ||
|
|
||
| Considering that Syslog output plugin documentation resides in this address: | ||
| ### Set your email in Git | ||
|
|
||
| - [pipeline/outputs/syslog.md](https://github.com/fluent/fluent-bit-docs/blob/master/pipeline/outputs/syslog.md) | ||
| Make sure your email address is configured in your local Git environment. This | ||
| should be the same email address associated with your GitHub account. | ||
|
|
||
| the suggested commit will be: | ||
|
|
||
| ``` | ||
| pipeline: outputs: syslog: fix grammar in examples | ||
| ``` | ||
|
|
||
| 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. | ||
|
|
||
| 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). | ||
| For more information, refer to GitHub's guide to | ||
| [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). | ||
|
|
||
| ### Sign off your commits | ||
|
|
||
| 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. | ||
| You must sign off your commits to certify your identity as the commit author. If | ||
| you don't sign off your commits, our CI system will flag the pull request with a | ||
| [DCO](https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md) | ||
| error and prevent your pull request from merging. | ||
|
|
||
| To prevent DCO errors, refer to the following guide about | ||
| [signing your commits properly](https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md). | ||
|
|
||
| The following link explains how to fix DCO error by signing your commits properly: | ||
| > :bulb: For faster signing, you can use the `-s` flag in Git: | ||
| > | ||
| > `git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples"` | ||
| > | ||
| > If you're using VS Code, you can also enable the | ||
| > [**Git: Always Sign Off**](https://github.com/microsoft/vscode/issues/83096#issuecomment-545350047) | ||
| > setting, whch automatically appends a `Signed-off-by:` message to your commits. | ||
| - https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md | ||
| ## Style guidelines | ||
|
|
||
| For short: always use `-s` when committing your changes, e.g.: | ||
| The Fluent Bit maintainers refer to the | ||
| [Google developer documentation style guide](https://developers.google.com/style) | ||
| for most topics related to grammar, style, and formatting. We don't expect you | ||
| to memorize these style rules, but the technical writer who reviews your pull | ||
| request may suggest changes accordingly. | ||
|
|
||
| ``` | ||
| git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples" | ||
| ``` | ||
| ### Vale | ||
|
|
||
| The Fluent Bit maintainers are working to add a [Vale](https://vale.sh/docs/) plugin | ||
| to this repository, which will automatically lint pull requests and add | ||
| suggestions to improve style and clarity. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters