-
Notifications
You must be signed in to change notification settings - Fork 172
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Update CONTRIBUTING.md * Update CONTRIBUTING.md Co-authored-by: Moritz Wiesinger <[email protected]> * Update CONTRIBUTING.md Co-authored-by: Moritz Wiesinger <[email protected]> * Update CONTRIBUTING.md Co-authored-by: Moritz Wiesinger <[email protected]> --------- Co-authored-by: Moritz Wiesinger <[email protected]>
- Loading branch information
1 parent
ddc7d31
commit 6722b07
Showing
1 changed file
with
105 additions
and
39 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,76 +1,142 @@ | ||
| # Contribution guidelines | ||
| # Contributing to OpenTelemetry Collector Distributions | ||
|
|
||
| This repository contains a set of resources that ultimately results in OpenTelemetry Collector distributions. This document contains information needed to start contributing to this repository, including how to add new distributions. | ||
| ## Introduction | ||
|
|
||
| ## Understanding this repository | ||
| Welcome to the OpenTelemetry Collector Distributions repository! 🎉 | ||
|
|
||
| ### Distribution directory | ||
| Thank you for considering contributing to this project. Whether you're adding new distributions, improving existing ones, or enhancing documentation, your efforts are invaluable to the community. | ||
|
|
||
| Each distribution has its own directory under the [`distributions`](./distributions/) folder, such as [`otelcol`](./distributions/otelcol/). | ||
| Within each one of those, you'll find at least two files: | ||
| This repository assembles various OpenTelemetry Collector distributions, such as the "core" and "contrib" versions. Each distribution contains: | ||
|
|
||
| - `Dockerfile`, determining how to build the container image for this distribution | ||
| - `manifest.yaml`, which is used with [ocb](https://github.com/open-telemetry/opentelemetry-collector/tree/main/cmd/builder) to generate the sources for the distribution. | ||
| - Binaries for multiple platforms and architectures. | ||
| - Multi-architecture container images. | ||
| - Packages for Linux distributions (RPM, deb), Windows (msi) and macOS (brew). | ||
|
|
||
| Within each distribution, you are expected to be able to build it using the builder, like: | ||
| For more details about each distribution, please refer to their respective directories within the repository. | ||
|
|
||
| ```shell | ||
| --- | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| Before you begin, ensure you have the following tools installed: | ||
|
|
||
| - **Go** – [Install Go](https://golang.org/doc/install) | ||
| - **Docker** – [Install Docker](https://docs.docker.com/get-docker/) | ||
| - **Make** – [Install Make](https://www.gnu.org/software/make/) | ||
|
|
||
| Additional Notes: | ||
|
|
||
| - Ensure your Go environment is set up correctly, with `$GOPATH` and `$PATH` configured. | ||
| - Docker is essential for building and testing container images. | ||
| - Familiarity with the OpenTelemetry Collector and its components will be beneficial. | ||
|
|
||
| --- | ||
|
|
||
| ## Repository Structure | ||
|
|
||
| Understanding the repository's structure will help you navigate and contribute effectively: | ||
|
|
||
| - **`distributions/`**: Contains directories for each distribution (e.g., `otelcol`, `otelcol-contrib`). | ||
| - Each distribution directory includes: | ||
| - `Dockerfile`: Defines how to build the container image for the distribution. | ||
| - `manifest.yaml`: Used with the OpenTelemetry Collector Builder (`ocb`) to generate the sources for the distribution. | ||
|
|
||
| - **`scripts/`**: Contains scripts used by the main `Makefile` to automate various tasks. | ||
|
|
||
| --- | ||
|
|
||
| ## Workflow | ||
|
|
||
| ### Pull Request Guidelines | ||
|
|
||
| - Fork the repository and create a new branch. | ||
| - Ensure your code adheres to the project's coding standards. | ||
| - Run all tests and ensure they pass before submitting. | ||
| - Link relevant issues in the PR description. | ||
|
|
||
| --- | ||
|
|
||
| ## Building Distributions | ||
|
|
||
| To build a specific distribution: | ||
|
|
||
| ```bash | ||
| cd distributions/<distribution-name> | ||
| ocb --config manifest.yaml | ||
| ``` | ||
|
|
||
| You can build all distributions by running: | ||
| To build all distributions: | ||
|
|
||
| ```shell | ||
| ```bash | ||
| make build | ||
| ``` | ||
|
|
||
| If you only interested in generating the sources for the distributions, use: | ||
| If you're only interested in generating the sources for the distributions: | ||
|
|
||
| ```shell | ||
| ```bash | ||
| make generate | ||
| ``` | ||
|
|
||
| ### Distribution configurations | ||
|
|
||
| Due to an incompatibility between `goreleaser` and how this directory is structured, the default configuration files to be included in the container images should be placed under [./configs](./configs) instead of within the distribution's main directory. | ||
|
|
||
| ### Scripts | ||
| --- | ||
|
|
||
| The main `Makefile` is mostly a wrapper around scripts under the [./scripts](./scripts) directory. | ||
| ## Generating goreleaser Configuration | ||
|
|
||
| ### goreleaser | ||
| `goreleaser` plays a significant role in producing the final artifacts. Given that the final configuration file for this tool would be extensive and would cause relatively big changes for each new distribution, a `Makefile` target exists to generate the `.goreleaser.yaml` for the repository. | ||
|
|
||
| [goreleaser](https://goreleaser.com) plays a big role in producing the final artifacts. Given that the final configuration file for this tool would be huge and would cause relatively big changes for each new distribution, a `Makefile` target exists to generate the `.goreleaser.yaml` for the repository. The `Makefile` contains a list of distributions (`DISTRIBUTIONS`) that is passed down to the script, which will generate snippets based on the templates from `./scripts/goreleaser-templates/`. Adding a new distribution is then only a matter of adding the distribution's directory, plus adding it to the Makefile. Adding a new snippet is only a matter of adding a new template. | ||
| To generate the `.goreleaser.yaml` file: | ||
|
|
||
| Once there's a change either to the templates or to the list of distributions, a new `.goreleaser.yaml` file can be generated with: | ||
|
|
||
| ```shell | ||
| ```bash | ||
| make generate-goreleaser | ||
| ``` | ||
|
|
||
| After that, you can test the goreleaser build process with: | ||
| After generating the configuration, you can test the `goreleaser` build process with: | ||
|
|
||
| ```shell | ||
| ```bash | ||
| make goreleaser-verify | ||
| ``` | ||
|
|
||
| #### Building multi-architecture Docker images | ||
| --- | ||
|
|
||
| ## Building Multi-Architecture Docker Images | ||
|
|
||
| goreleaser will build Docker images for x86_64, 386, arm, arm64 and ppc64le processors. The build process involves executing `RUN` steps on the target architecture, which means the system you run it on needs support for emulating foreign architectures. | ||
| `goreleaser` will build Docker images for various architectures, including `x86_64`, `386`, `arm`, `arm64`, and `ppc64le`. The build process involves executing `RUN` steps on the target architecture, which means the system you run it on needs support for emulating foreign architectures. | ||
|
|
||
| This is accomplished by installing [qemu](https://www.qemu.org/), and then [enabling support](https://github.com/multiarch/qemu-user-static#readme) for qemu within Docker: | ||
| To set up the environment for building multi-architecture images: | ||
|
|
||
| ```shell | ||
| apt-get install qemu binfmt-support qemu-user-static | ||
| ```bash | ||
| # Install QEMU and related packages | ||
| sudo apt-get install qemu binfmt-support qemu-user-static | ||
|
|
||
| # Enable support for QEMU within Docker | ||
| docker run --rm --privileged multiarch/qemu-user-static --reset -p yes | ||
| ``` | ||
|
|
||
| ### Adding support for new platforms or architectures | ||
| --- | ||
|
|
||
| ## Adding Support for New Platforms or Architectures | ||
|
|
||
| When introducing a new collector distribution image or binary for a different platform or architecture, consider the following: | ||
|
|
||
| 1. **Continuous Integration**: | ||
| - Add the new platform or architecture to the CI test matrix for both the core and contrib repositories to ensure they can be compiled with the new combination. Failing to do so may cause the release to fail due to compilation issues on those uncovered platforms. | ||
|
|
||
| 2. **goreleaser Configuration**: | ||
| - In the `goreleaser/configure.go` file, add the new platform or architecture. | ||
| - Regenerate the `.goreleaser.yaml` file (see the "Generating goreleaser Configuration" section above). | ||
|
|
||
| 3. **GitHub Actions**: | ||
| - In the `.github/workflows/ci-goreleaser.yaml` file, under the "Setup QEMU" action, add the new platform and architecture. | ||
| - In the `.github/workflows/release.yaml` file, under the "Setup QEMU" action, add the new platform and architecture. | ||
|
|
||
| --- | ||
|
|
||
| ## Further Help | ||
|
|
||
| Need assistance? Join our community: | ||
|
|
||
| - **Slack Discussions**: [OpenTelemetry](https://cloud-native.slack.com/archives/CJFCJHG4Q) | ||
| - **Issues**: If you encounter a bug or have a feature request, [open an issue](https://github.com/open-telemetry/opentelemetry-collector-releases/issues) | ||
|
|
||
| When a new collector distribution image or binary is needed in a different platform or architecture, the following should be considered: | ||
| --- | ||
|
|
||
| 1. Add the new platform or architecture to the Continuous Integration test matrix for both the [core](https://github.com/open-telemetry/opentelemetry-collector) and [contrib](https://github.com/open-telemetry/opentelemetry-collector-contrib) repositories, to ensure they can be compiled with the new combination. Failing to do so will eventually cause the release to fail due to compilation failures on those uncovered platforms, resulting in them being removed from the release matrix. | ||
| 2. In the `goreleaser/configure.go` file, add the new platform or architecture | ||
| 3. Regenerate the `.goreleaser` (see [goreleaser](#goreleaser) above) | ||
| 4. In the `.github/workflows/ci-goreleaser.yaml` file, under the "Setup QEMU" action, add the new platform and architecture | ||
| 5. In the `.github/workflows/release.yaml` file, under the "Setup QEMU" action, add the new platform and architecture | ||
| Thank you for contributing! 🚀 |