From f3e564b809f2dda5e578ce2b4eb28b2b3c0aae1e Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Thu, 8 Feb 2024 16:25:53 -0500 Subject: [PATCH 1/6] feat: update the openo11y contributing documentation Fixes #18 --- .markdownlint.yaml | 6 +++ CONTRIBUTING.md | 22 ++++++++ docs/contributing.md | 124 +++++++++---------------------------------- 3 files changed, 53 insertions(+), 99 deletions(-) create mode 100644 .markdownlint.yaml create mode 100644 CONTRIBUTING.md diff --git a/.markdownlint.yaml b/.markdownlint.yaml new file mode 100644 index 0000000..6de07ec --- /dev/null +++ b/.markdownlint.yaml @@ -0,0 +1,6 @@ +MD007: + # Spaces for indent + indent: 4 +MD013: + # Number of characters + line_length: 90 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6a5ef2d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,22 @@ +# Contributing Guide + +Your contributions are welcome and encouraged! Thanks for contributing. + +## Contribution Scope and Github Issues + +Changes that are small in scope may be submitted *without* opening a Github issue. This is +viable when correcting typos or small grammatical errors. It may also be viable when +rewording a sentence or paragraph simply for clarity. + +For any other changes, please open a Github issue to propose your changes where they can +be discussed and planned openly. This is appropriate when meaningfully changing or +introducing new content. The content in question could be ideas, recommendations, +diagrams, architectures, tools, etc. + +If you are unsure if an issue is needed, please open an issue to discuss your change. + +## Commits, Branches, and Pull Requests + +All contributions should be committed to a branch and reviewed with a pull request. Forks +certainly may be used but are not required. Commits and pull requests should follow +[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines. diff --git a/docs/contributing.md b/docs/contributing.md index ceae1a7..d1ce2d0 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,112 +1,38 @@ -# Contributing to open o11y +# Contributing to OpenO11y -Anyone is welcome to contribute to open o11y, and there's a few major -aspects of this project to which one can contribute. -This guide will help you understand how our project works and how you can contribute effectively. -If you have any questions that aren't answered in this guide, please feel free to reach out on our [Slack Team](https://liatrio.slack.com/archives/C04KGSFF407). +Anyone is welcome to contribute to OpenO11y and its open projects. There are a few major +aspects of this project to which one can contribute. This guide will help you understand +how our project works and how you can contribute effectively. If you have any questions +that aren't answered in this guide, please reach out by creating a [GitHub issue](https://github.com/liatrio/openo11y.dev/issues). -## Table of Contents - -- [Contributing to open o11y](#contributing-to-open-o11y) - - [Table of Contents](#table-of-contents) - - [Getting Started](#getting-started) - - [Github Repositories](#github-repositories) - - [Liatrio Distribution of the Open Telemetry Collector](#liatrio-distribution-of-the-open-telemetry-collector) - - [Github Issues](#github-issues) - - [Open Source Projects](#open-source-projects) - - [Automation \& Deployment](#automation--deployment) - - [Communication](#communication) - -## Getting Started - -Before you start contributing, make sure to set up your development environment. -Details can be found in our [README.md](https://github.com/liatrio/openo11y.dev/blob/main/README.md) file. +We look forward to your contributions! ## Github Repositories -The following is a list of repositories that relate or are actively being developed as part -of **open o11y**. - -- [o11y-platform-deployment](https://github.com/liatrio/o11y-platform-deployment) #[branch] Terragrunt deployment repo for the o11y platform -- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) #[branch] TF module for managed services in AWS for o11y -- [o11y-docs](https://github.com/liatrio-delivery-povs/o11y-docs) #[branch] GitHub pages repo hosting this docs website -- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) #[branch] Liatrio's distribution of the OTEL Collector -- [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) #[fork] the repo we fork and contribute to on the OTEL project -- [oteps](https://github.com/open-telemetry/oteps) #[fork] the repo we fork for enhancement proposals contributing back to the community via OTEL -- [sdc](https://github.com/liatrio/sdc) #[branch] the original SDC repo, this is deprecated in favor for adding components to the OTEL distro - -Our projects follow a mixture of the Github Fork Flow model and short lived branches. -You will notice above a [tag] that will let you know which each project is. -For repos with a [fork] tag, his means that you will need to create a fork of our repository, -make your changes there, and then create a pull request to contribute those changes back to the main repository. - -Here are some general steps to follow: - -1. Fork the repository by clicking the "Fork" button in the top right corner of the repository page. -2. Clone the forked repository to your local machine. -3. Create a new branch for your changes using `git checkout -b your-branch-name`. -4. Make your changes and commit them with a clear and concise commit message. -5. Push your changes to your forked repository. -6. Go to the original repository and create a new pull request. Be sure to select your fork and the branch that you worked on. - -**NOTE**: We encourage inner sourcing within our team. -This means that team members are free to contribute to any part of the project, -not just the parts they are assigned to. - -## Liatrio Distribution of the Open Telemetry Collector +The following repositories relate to or are actively developed as part of **OpenO11y**. -Liatrio maintains a distribution of the Open Telemetry Collector geared towards -productionalized workloads, removing many of the exporters and receivers that exist -in the binary by default. It also has allowed us to quickly contribute working -receivers, processors, authenticators, and exporters prior to contributing back to the -OSS project. +- [openo11y.dev](https://github.com/liatrio/openo11y.dev) The source for this site +- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) TF module + for managed services in AWS for o11y +- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) Liatrio's + distribution of the OTEL Collector +- [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) + the repo we fork and contribute to on the OTEL project +- [oteps](https://github.com/open-telemetry/oteps) the repo we fork for enhancement + proposals contributing back to the community via OTEL -Our end state goal for this distribution is to ensure its features are contributed back -to the official OSS project 100% of the time where our code changes are accepted. Our predominant -reason for maintaining our own distribution is for fast custom development and reduction of undeeded go -packages, ensuring use of OTLP where ever possible. - -Our model of contribution is reflected in the below diagram: - -```mermaid -flowchart LR - A(o11y induvidual branch or fork) - B(liatrio-otel-collector) - C(opentelemetry-collector-contrib) - E(client-otel-collector) - - A --merge/commit--> B - B --fork/branch--> A - B --> C - B --> E -``` +Anyone is welcome to contribute to any of these projects. These projects generally expect +that contributions start with a Github issue where proposed changes can be discussed and +planned openly. However, each project is independent and contributors should refer to the +documentation within each project for detailed instructions. ## Github Issues -We use Github Issues hosted in a Github project that is attached to multiple repos. -To keep everything organized, each issue should correspond to a specific feature or bug. Here's how you can contribute: - -1. Look for open issues in the [Github project](https://github.com/orgs/liatrio/projects/25/views/1). -2. Comment on the issue you wish to work on and reach out in [#project-o11y slack](https://liatrio.slack.com/archives/C04KGSFF407). -Make sure no one else is working on it. -3. If you find a bug or have a feature idea that doesn't have an issue, feel free to create one. +All of our projects generally expect that contributions start with a Github issue where +proposed changes can be discussed and planned openly. ## Open Source Projects -We rely heavily on open source projects. -If you find a bug or feature that you think should be implemented in one of these projects, consider contributing there first. -This includes submitting PRs to forked projects that are hosted internally. - -## Automation & Deployment - -Our project has automation set up to deploy to various locations. -You can find scripts and instructions in the [deployment](#) directory. -If you have any suggestions for improving our automation and deployment process, we would love to hear them. - -## Communication - -We use Slack for most of our team communication. -If you have any questions or need clarifications, feel free to ask in our [#general](#) channel. -Remember to be respectful and considerate in your communication. - -We look forward to your contributions! +We rely heavily on open source projects. If you find a bug or feature that you think +should be implemented in one of these projects, consider contributing there first. This +includes submitting PRs to forked projects that are hosted internally. From 0d86a28f7ba57aa37b20c36018d3f2e2f12d9dbe Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Fri, 9 Feb 2024 12:35:16 -0500 Subject: [PATCH 2/6] Change line lengths to 80 characters. Update contributing accordingly --- .markdownlint.yaml | 3 --- CONTRIBUTING.md | 24 +++++++++++----------- docs/contributing.md | 47 ++++++++++++++++++++++++-------------------- 3 files changed, 39 insertions(+), 35 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 6de07ec..e9b82f3 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,6 +1,3 @@ MD007: # Spaces for indent indent: 4 -MD013: - # Number of characters - line_length: 90 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6a5ef2d..4b0f5a2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,19 +4,21 @@ Your contributions are welcome and encouraged! Thanks for contributing. ## Contribution Scope and Github Issues -Changes that are small in scope may be submitted *without* opening a Github issue. This is -viable when correcting typos or small grammatical errors. It may also be viable when -rewording a sentence or paragraph simply for clarity. +Changes that are small in scope may be submitted *without* opening a Github +issue. This is viable when correcting typos or small grammatical errors. It may +also be viable when rewording a sentence or paragraph simply for clarity. These +PRs may be approved, merged, or declined without discussion. -For any other changes, please open a Github issue to propose your changes where they can -be discussed and planned openly. This is appropriate when meaningfully changing or -introducing new content. The content in question could be ideas, recommendations, -diagrams, architectures, tools, etc. +For any other changes, please open a Github issue to propose your changes where +they can be discussed and planned openly. This is appropriate when meaningfully +changing or introducing new content. The content in question could be ideas, +recommendations, diagrams, architectures, tools, etc. -If you are unsure if an issue is needed, please open an issue to discuss your change. +If you are unsure if an issue is needed, please open an issue to discuss your +change. ## Commits, Branches, and Pull Requests -All contributions should be committed to a branch and reviewed with a pull request. Forks -certainly may be used but are not required. Commits and pull requests should follow -[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines. +All contributions should be committed to a branch and reviewed with a pull +request. Forks certainly may be used but are not required. Commits and pull +requests should follow [ConventionalCommits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines. diff --git a/docs/contributing.md b/docs/contributing.md index d1ce2d0..64aee73 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,38 +1,43 @@ # Contributing to OpenO11y -Anyone is welcome to contribute to OpenO11y and its open projects. There are a few major -aspects of this project to which one can contribute. This guide will help you understand -how our project works and how you can contribute effectively. If you have any questions -that aren't answered in this guide, please reach out by creating a [GitHub issue](https://github.com/liatrio/openo11y.dev/issues). +Anyone is welcome to contribute to OpenO11y and its open projects. There are a +few major aspects of this project to which one can contribute. This guide will +help you understand how our project works and how you can contribute +effectively. If you have any questions that aren't answered in this guide, +please reach out by creating a [GitHub issue](https://github.com/liatrio/openo11y.dev/issues). We look forward to your contributions! ## Github Repositories -The following repositories relate to or are actively developed as part of **OpenO11y**. +The following repositories relate to or are actively developed as part of +**OpenO11y**. -- [openo11y.dev](https://github.com/liatrio/openo11y.dev) The source for this site -- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) TF module - for managed services in AWS for o11y -- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) Liatrio's - distribution of the OTEL Collector +- [openo11y.dev](https://github.com/liatrio/openo11y.dev) The source for this + site +- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) + TF module for managed services in AWS for o11y +- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) + Liatrio's distribution of the OTEL Collector - [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) the repo we fork and contribute to on the OTEL project -- [oteps](https://github.com/open-telemetry/oteps) the repo we fork for enhancement - proposals contributing back to the community via OTEL +- [oteps](https://github.com/open-telemetry/oteps) the repo we fork for + enhancement proposals contributing back to the community via OTEL -Anyone is welcome to contribute to any of these projects. These projects generally expect -that contributions start with a Github issue where proposed changes can be discussed and -planned openly. However, each project is independent and contributors should refer to the -documentation within each project for detailed instructions. +Anyone is welcome to contribute to any of these projects. These projects +generally expect that contributions start with a Github issue where proposed +changes can be discussed and planned openly. However, each project is +independent and contributors should refer to the documentation within each +project for detailed instructions. ## Github Issues -All of our projects generally expect that contributions start with a Github issue where -proposed changes can be discussed and planned openly. +All of our projects generally expect that contributions start with a Github +issue where proposed changes can be discussed and planned openly. ## Open Source Projects -We rely heavily on open source projects. If you find a bug or feature that you think -should be implemented in one of these projects, consider contributing there first. This -includes submitting PRs to forked projects that are hosted internally. +We rely heavily on open source projects. If you find a bug or feature that you +think should be implemented in one of these projects, consider contributing +there first. This includes submitting PRs to forked projects that are hosted +internally. From 6926492e7ce73b719d49bcdeb90d0b7fa80e758b Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Fri, 9 Feb 2024 12:50:05 -0500 Subject: [PATCH 3/6] Updating contributing docs based on feedback --- CONTRIBUTING.md | 6 +++--- docs/contributing.md | 15 +++++---------- 2 files changed, 8 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4b0f5a2..5fa43de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,6 @@ change. ## Commits, Branches, and Pull Requests -All contributions should be committed to a branch and reviewed with a pull -request. Forks certainly may be used but are not required. Commits and pull -requests should follow [ConventionalCommits](https://www.conventionalcommits.org/en/v1.0.0/) guidelines. +All contributions should be made in a fork, committed to a branch, and reviewed +with a pull request. Commits and pull requests should follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) +guidelines. diff --git a/docs/contributing.md b/docs/contributing.md index 64aee73..c6f19fd 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -16,13 +16,13 @@ The following repositories relate to or are actively developed as part of - [openo11y.dev](https://github.com/liatrio/openo11y.dev) The source for this site - [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) - TF module for managed services in AWS for o11y + TF module for managed services in AWS for observability - [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) Liatrio's distribution of the OTEL Collector -- [opentelemetry-collector-contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) - the repo we fork and contribute to on the OTEL project -- [oteps](https://github.com/open-telemetry/oteps) the repo we fork for - enhancement proposals contributing back to the community via OTEL +- [liatrio/opentelemetry-demo](https://github.com/liatrio/opentelemetry-demo) A + fork from OpenTelemetry that demos the GitProviderReceiver +- [terraform-grafana-config-module](https://github.com/liatrio/terraform-grafana-config-module) + A terraform module for deploying Grafana to AWS Anyone is welcome to contribute to any of these projects. These projects generally expect that contributions start with a Github issue where proposed @@ -30,11 +30,6 @@ changes can be discussed and planned openly. However, each project is independent and contributors should refer to the documentation within each project for detailed instructions. -## Github Issues - -All of our projects generally expect that contributions start with a Github -issue where proposed changes can be discussed and planned openly. - ## Open Source Projects We rely heavily on open source projects. If you find a bug or feature that you From 64b9759bb713177205ae15555e254f3809419b39 Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Fri, 9 Feb 2024 14:06:07 -0500 Subject: [PATCH 4/6] Refactor docs/contributing.md --- docs/contributing.md | 41 ++++++++++++++++------------------------- 1 file changed, 16 insertions(+), 25 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index c6f19fd..f30d65f 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,38 +1,29 @@ # Contributing to OpenO11y -Anyone is welcome to contribute to OpenO11y and its open projects. There are a -few major aspects of this project to which one can contribute. This guide will -help you understand how our project works and how you can contribute -effectively. If you have any questions that aren't answered in this guide, -please reach out by creating a [GitHub issue](https://github.com/liatrio/openo11y.dev/issues). +Anyone is welcome to contribute to OpenO11y. Please start by reviewing our +[CONTRIBUTING](https://github.com/liatrio/openo11y.dev/blob/main/CONTRIBUTING.md) +guidelines. If you have any questions that aren't answered in this guide, please +reach out by creating a [GitHub issue](https://github.com/liatrio/openo11y.dev/issues). We look forward to your contributions! -## Github Repositories +## Open Source Projects -The following repositories relate to or are actively developed as part of -**OpenO11y**. +OpenO11y relies heavily on open source projects. If you find a bug or feature +that you think should be implemented in one of these projects, consider +contributing there as well. The following repositories directly relate to +OpenO11y. -- [openo11y.dev](https://github.com/liatrio/openo11y.dev) The source for this - site -- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) - TF module for managed services in AWS for observability -- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector) +- [opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector) +- [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector): Liatrio's distribution of the OTEL Collector - [liatrio/opentelemetry-demo](https://github.com/liatrio/opentelemetry-demo) A fork from OpenTelemetry that demos the GitProviderReceiver +- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) + TF module for managed services in AWS for observability - [terraform-grafana-config-module](https://github.com/liatrio/terraform-grafana-config-module) A terraform module for deploying Grafana to AWS -Anyone is welcome to contribute to any of these projects. These projects -generally expect that contributions start with a Github issue where proposed -changes can be discussed and planned openly. However, each project is -independent and contributors should refer to the documentation within each -project for detailed instructions. - -## Open Source Projects - -We rely heavily on open source projects. If you find a bug or feature that you -think should be implemented in one of these projects, consider contributing -there first. This includes submitting PRs to forked projects that are hosted -internally. +Note that this list represents independent and varied open source projects. If +you choose to contribute to one, please review and understand the contributing +guidelines associated with that project. From 197be801219d38307e47b489d4ed486c99782cc1 Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Fri, 9 Feb 2024 14:08:49 -0500 Subject: [PATCH 5/6] Add missing colons --- docs/contributing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index f30d65f..d5cc681 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -17,11 +17,11 @@ OpenO11y. - [opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector) - [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector): Liatrio's distribution of the OTEL Collector -- [liatrio/opentelemetry-demo](https://github.com/liatrio/opentelemetry-demo) A +- [liatrio/opentelemetry-demo](https://github.com/liatrio/opentelemetry-demo): A fork from OpenTelemetry that demos the GitProviderReceiver -- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services) +- [aws-managed-service-module](https://github.com/liatrio/aws-managed-services): TF module for managed services in AWS for observability -- [terraform-grafana-config-module](https://github.com/liatrio/terraform-grafana-config-module) +- [terraform-grafana-config-module](https://github.com/liatrio/terraform-grafana-config-module): A terraform module for deploying Grafana to AWS Note that this list represents independent and varied open source projects. If From 1da0229b1662485c7497b0bca0e8c33c2e6933b8 Mon Sep 17 00:00:00 2001 From: Alex Ramsay Date: Fri, 9 Feb 2024 15:26:09 -0500 Subject: [PATCH 6/6] Update docs/contributing.md based on feedback --- docs/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contributing.md b/docs/contributing.md index d5cc681..0aedf99 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -11,8 +11,8 @@ We look forward to your contributions! OpenO11y relies heavily on open source projects. If you find a bug or feature that you think should be implemented in one of these projects, consider -contributing there as well. The following repositories directly relate to -OpenO11y. +contributing there as well. The following repositories are frequently used and +referenced by OpenO11y. - [opentelemetry-collector](https://github.com/open-telemetry/opentelemetry-collector) - [liatrio-otel-collector](https://github.com/liatrio/liatrio-otel-collector):