-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat: update the openo11y contributing documentation (#42)
* feat: update the openo11y contributing documentation Fixes #18 * Change line lengths to 80 characters. Update contributing accordingly * Updating contributing docs based on feedback * Refactor docs/contributing.md * Add missing colons * Update docs/contributing.md based on feedback
- Loading branch information
Showing
3 changed files
with
47 additions
and
108 deletions.
There are no files selected for viewing
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,5 +1,3 @@ | ||
| MD007: | ||
| # Spaces for indent | ||
| indent: 4 | ||
| MD013: | ||
| line_length: 90 |
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,24 @@ | ||
| # 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. 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. | ||
|
|
||
| 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 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. |
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,112 +1,29 @@ | ||
| # Contributing to OpenO11y | ||
|
|
||
| Anyone is welcome to contribute to OpenO11y, 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. 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). | ||
|
|
||
| ## Table of Contents | ||
|
|
||
| - [Contributing to OpenO11y](#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. | ||
|
|
||
| ## Github Repositories | ||
|
|
||
| The following is a list of repositories that relate or are actively being developed as part | ||
| of **OpenO11y**. | ||
|
|
||
| - [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 | ||
|
|
||
| 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. | ||
|
|
||
| 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 | ||
| ``` | ||
|
|
||
| ## 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. | ||
| We look forward to your contributions! | ||
|
|
||
| ## 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! | ||
| 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 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): | ||
| 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 | ||
|
|
||
| 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. |