From 60aa03a1d20fb03b5532fdcc1ea7941257f23c1f Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Thu, 2 May 2024 19:42:40 -0700 Subject: [PATCH 1/9] contributing: add sections and update phrasing Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 109 ++++++++++++++++++++++++++++++++++-------------- 1 file changed, 78 insertions(+), 31 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index be6c34ca5..2688a65a0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,68 @@ -# 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 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. +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. -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). +### Stale pull requests -## Source Code Structure +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 [three weeks?] for your response, +and close the pull request if we don't hear back from you. -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: +### Labels -- stable branch: [1.8](https://github.com/fluent/fluent-bit/tree/1.8) -- development branch: [master](https://github.com/fluent/fluent-bit/tree/master) +We use the following labels to categorize pull requests: -For Documentation, we follow the same pattern; we have branches for the stable and development versions. +The Fluent Bit docs repository uses labels to categorize pull requests. If you +open a new pull request, -## Submitting Contributions +- **bug:** This pull request addresses a bug. +- **conflict:** This pull request has a conflict that you need to fix. +- **dependencies:** This pull request updates a -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. +## Submit a contribution -### GIT email check +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. -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: - -```bash -cd fluent-bit-docs/ -git config user.email -``` - -If you need to adjust your email, do this: - -``` -git config user.email something@myemailprovider.com -``` +As a contributor, we'll ask you to follow a few best practices related to Git: -### Commit Subjects +### Commit subjects 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: @@ -60,9 +82,17 @@ As you can see, the commit is prefixed with the paths of the file being modified 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). +### Set your email in Git + +Make sure your email address is configured 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 committ 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. +Your commits must be **signed 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. The following link explains how to fix DCO error by signing your commits properly: @@ -74,3 +104,20 @@ For short: always use `-s` when committing your changes, e.g.: git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples" ``` +## Style guidelines + +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. + +### Line wrap + +[TBD] + +### 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. From 8d98e1af72b1ea3ba400cac01e4fc5733ccf7ca5 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Thu, 2 May 2024 20:14:28 -0700 Subject: [PATCH 2/9] contributing: rewrites for clarity Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 56 +++++++++++++++++++------------------------------ 1 file changed, 21 insertions(+), 35 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2688a65a0..a573d4a24 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -6,7 +6,7 @@ your time. This repository contains the files for the [Fluent Bit documentation library](https://docs.fluentbit.io/). Keeping these docs -separate from from the [main Fluent Bit repository](https://github.com/fluent/fluent-bit) +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. @@ -45,42 +45,29 @@ request. This tag means that we're blocked from moving forward until you reply; to keep contributions from going stale, we'll wait [three weeks?] for your response, and close the pull request if we don't hear back from you. -### Labels - -We use the following labels to categorize pull requests: - -The Fluent Bit docs repository uses labels to categorize pull requests. If you -open a new pull request, - -- **bug:** This pull request addresses a bug. -- **conflict:** This pull request has a conflict that you need to fix. -- **dependencies:** This pull request updates a - ## Submit a contribution 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. As a contributor, we'll ask you to follow a few best practices related to Git: -### Commit subjects - -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: - -- User is enhancing the documentation for the Syslog output plugin +### One file per commit -Considering that Syslog output plugin documentation resides in this address: +Each commit you make should only modify one file or interface—we follow the same +practice in the Fluent Bit source code. -- [pipeline/outputs/syslog.md](https://github.com/fluent/fluent-bit-docs/blob/master/pipeline/outputs/syslog.md) +### Commit subjects -the suggested commit will be: +Use descriptive commit subjects that describe which file or interface you're +modifying. -``` -pipeline: outputs: syslog: fix grammar in examples -``` +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: -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. +`pipeline: outputs: syslog: fix grammar in examples` -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). +Since this commit is prefixed with the relevant file path, it helps our maintainers +understand and prioritize your contribution. ### Set your email in Git @@ -88,21 +75,20 @@ Make sure your email address is configured 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 committ 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). +[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 **signed 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. - -The following link explains how to fix DCO error by signing your commits properly: - -- https://github.com/src-d/guide/blob/master/developer-community/fix-DCO.md +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 flat 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. -For short: always use `-s` when committing your changes, e.g.: +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). -``` -git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples" -``` +> :bulb: For faster signing, you can use the `-s` flag in Git:
+> `git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples"` ## Style guidelines From 95f2d701b99b6d2a23ebba5ea3c02f88455b0fdb Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Fri, 3 May 2024 10:48:35 -0700 Subject: [PATCH 3/9] contributing: edits for clarity Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a573d4a24..4b41212e8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -47,6 +47,14 @@ and close the pull request if we don't hear back from you. ## Submit a contribution +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. As a contributor, we'll ask you to follow a few best practices related to Git: @@ -87,7 +95,8 @@ 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). -> :bulb: For faster signing, you can use the `-s` flag in Git:
+> :bulb: For faster signing, you can use the `-s` flag in Git: +> > `git commit -a -s -m "pipeline: outputs: syslog: fix grammar in examples"` ## Style guidelines @@ -98,10 +107,6 @@ 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. -### Line wrap - -[TBD] - ### Vale The Fluent Bit maintainers are working to add a [Vale](https://vale.sh/docs/) plugin From 87c6fab65537b70439b4f1d28673459b976dd750 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Fri, 3 May 2024 11:14:57 -0700 Subject: [PATCH 4/9] maintainers: add new maintainers Signed-off-by: Alexa Kreizinger --- MAINTAINERS.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/MAINTAINERS.md b/MAINTAINERS.md index 0b0d8fc55..9abcf140a 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -2,8 +2,10 @@ Fluent Bit is developed and supported by many individuals and companies. The following table list the names of maintainers per components and the company supporting their work. -| Maintainer Name | Documentation portion | Company | -| :---------------------------------------------------- | ------------------------ | ------------------------------------------------- | -| [Eduardo Silva](https://github.com/edsiper) | All | [Chronosphere](https://chronosphere.io) | -| [Anurag Gupta](https://github.com/agup006) | All | [Calyptia](https://calyptia.com) | -| [Jose Lecaros](https://github.com/lecaros) | All | [Chronosphere](https://chronosphere.io) | +| Maintainer Name | Documentation portion | Company | +| :---------------------------------------------------- | ------------------------ | ------------------------------------------------- | +| [Eduardo Silva](https://github.com/edsiper) | All | [Chronosphere](https://chronosphere.io) | +| [Anurag Gupta](https://github.com/agup006) | All | [Chronosphere](https://chronosphere.io) | +| [Jose Lecaros](https://github.com/lecaros) | All | [Chronosphere](https://chronosphere.io) | +| [Lynette Miles](https://github.com/esmerel) | All | [Chronosphere](https://chronosphere.io) | +| [Alexa Kreizinger](https://github.com/alexakreizinger) | All | [Chronosphere](https://chronosphere.io) | From fe6fc2591a4aee4a9735ef4773f1728246c863a1 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Fri, 3 May 2024 12:48:38 -0700 Subject: [PATCH 5/9] codeowners: add codeowners file Signed-off-by: Alexa Kreizinger --- CODEOWNERS | 1 + 1 file changed, 1 insertion(+) create mode 100644 CODEOWNERS diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 000000000..f919e0f2b --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1 @@ +* @fluent/fluent-bit-maintainers @fluent/chronosphere-technical-writers From 2d49a18d8f03fa046890115ef9e7a2d6d32f59a1 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Fri, 3 May 2024 13:05:48 -0700 Subject: [PATCH 6/9] codeowners: update team name Signed-off-by: Alexa Kreizinger --- CODEOWNERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CODEOWNERS b/CODEOWNERS index f919e0f2b..a93d99381 100644 --- a/CODEOWNERS +++ b/CODEOWNERS @@ -1 +1 @@ -* @fluent/fluent-bit-maintainers @fluent/chronosphere-technical-writers +* @fluent/fluent-bit-maintainers @fluent/chronosphere-tech-writers From a6189acee4cdc93a4773d0de9404ce50febc1075 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Fri, 3 May 2024 13:22:41 -0700 Subject: [PATCH 7/9] contributing: add VS Code shortcut Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b41212e8..a055530cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,6 +98,10 @@ To prevent DCO errors, refer to the following guide about > :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. ## Style guidelines From 241af3ae641af988574a09bd4a0b226e17ed6d13 Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Mon, 6 May 2024 15:29:18 -0700 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: esmerel <6818907+esmerel@users.noreply.github.com> Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a055530cf..e0d6fc9ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,8 +12,8 @@ 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. +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 @@ -88,7 +88,7 @@ For more information, refer to GitHub's guide to ### Sign off your commits 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 flat the pull request with a +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. From 261413c3be733065c2af2ffe1b30b877caab7d3d Mon Sep 17 00:00:00 2001 From: Alexa Kreizinger Date: Mon, 6 May 2024 15:35:52 -0700 Subject: [PATCH 9/9] Update CONTRIBUTING.md Signed-off-by: Alexa Kreizinger --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0d6fc9ad..3beefdb53 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -41,9 +41,9 @@ within a few minutes. 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 [three weeks?] for your response, -and close the pull request if we don't hear back from you. +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. ## Submit a contribution