diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md index 449d600d298..db4aa979f23 100644 --- a/docs/coding-guidelines.md +++ b/docs/coding-guidelines.md @@ -47,11 +47,40 @@ When naming configuration structs, use the following guidelines: - Use the `Settings` suffix for configuration structs that are set by developers in the code. For example, `component.TelemetrySettings` ends in `Settings` since it is set by developers in the code. - Avoid redundant prefixes that are already implied by the package name. For example, use`configgrpc.ClientConfig` instead of `configgrpc.GRPCClientConfig`. -#### Experimental module naming - -Experimental modules can be introduced as submodules of stable modules. They MUST have the same name as the stable -modules prefixed with `x`. For example, `config/confighttp` module can have an experimental module named -`config/confighttp/xconfighttp` that contains experimental APIs. +### Module organization + +As usual in Go projects, organize your code into packages grouping related functionality. To ensure +that we can evolve different parts of the API independently, you should also group related packages +into modules. + +We use the following rules for some common situations where we split into separate modules: +1. Each top-level directory should be a separate module. +1. Each component referenceable by the OpenTelemetry Collector Builder should be in a separate + module. For example, the OTLP receiver is in its own module, different from that of other + receivers. +1. Consider splitting into separate modules if the API may evolve independently in separate groups + of packages. For example, the configuration related to HTTP and gRPC evolve independently, so + `config/configgrpc` and `config/confighttp` are separate modules. +1. Testing helpers should be in a separate submodule with the suffix `test`. For example, if you + have a module `component`, the helpers should be in `component/componenttest`. +1. Experimental packages that will later be added to another module should be in their own module, + named as they will be after integration. For example, if adding a `pprofile` package to `pdata`, + you should add a separate module `pdata/pprofile` for the experimental code. +1. Experimental code that will be added to an existing package in a stable module can be a submodule + with the same name, but prefixed with an `x`. For example, `config/confighttp` module can have an + experimental module named `config/confighttp/xconfighttp` that contains experimental APIs. + +When adding a new module remember to update the following: +1. Add a changelog note for the new module. +1. Add the module in `versions.yaml`. +1. Use `make crosslink` to make sure the module replaces are added correctly throughout the + codebase. You may also have to manually add some of the replaces. +1. Update the [otelcorecol + manifest](https://github.com/open-telemetry/opentelemetry-collector/blob/main/cmd/otelcorecol/builder-config.yaml) + and [builder + tests](https://github.com/open-telemetry/opentelemetry-collector/blob/main/cmd/builder/internal/builder/main_test.go). +1. Open a follow up PR to update pseudo-versions in all go.mod files. See [this example + PR](https://github.com/open-telemetry/opentelemetry-collector/pull/11668). ### Enumerations