|
1 | 1 | # Contributing |
2 | 2 |
|
3 | | -If you would like to contribute please read OpenTelemetry Collector |
4 | | -[contributing guidelines](https://github.com/open-telemetry/opentelemetry-collector/blob/main/CONTRIBUTING.md) |
5 | | -before you begin your work. |
| 3 | +If you would like to contribute please read OpenTelemetry Collector [contributing |
| 4 | +guidelines](https://github.com/open-telemetry/opentelemetry-collector/blob/main/CONTRIBUTING.md) before you begin your |
| 5 | +work. |
| 6 | + |
| 7 | +## Pull-request title |
| 8 | + |
| 9 | +The title for your pull-request should contain the component type and name in brackets, plus a short statement for your |
| 10 | +change. For instance: |
| 11 | + |
| 12 | + [processor/tailsampling] fix AND policy |
6 | 13 |
|
7 | 14 | ## Adding New Components |
8 | 15 |
|
9 | | -**Before** any code is written, [open an issue](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/new?assignees=&labels=new+component&template=new_component.md&title=New%20component) providing the following information: |
| 16 | +**Before** any code is written, [open an |
| 17 | +issue](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/new?assignees=&labels=new+component&template=new_component.md&title=New%20component) |
| 18 | +providing the following information: |
10 | 19 |
|
11 | | -* Who's the sponsor for your component. A sponsor is an approver who will be in charge of being the official reviewer of the code and become a code owner for the component. For vendor-specific components, it's good to have a volunteer sponsor. If you can't find one, we'll assign one in a round-robin fashion. For non-vendor specific components, having a sponsor means that your use case has been validated. |
12 | | -* Some information about your component, such as the reasoning behind it, use-cases, telemetry data types supported, and anything else you think is relevant for us to make a decision about accepting the component. |
13 | | -* The configuration options your component will accept. This will help us understand what it does and have an idea of how the implementation might look like. |
| 20 | +* Who's the sponsor for your component. A sponsor is an approver who will be in charge of being the official reviewer of |
| 21 | + the code and become a code owner for the component. For vendor-specific components, it's good to have a volunteer |
| 22 | + sponsor. If you can't find one, we'll assign one in a round-robin fashion. For non-vendor specific components, having |
| 23 | + a sponsor means that your use case has been validated. |
| 24 | +* Some information about your component, such as the reasoning behind it, use-cases, telemetry data types supported, and |
| 25 | + anything else you think is relevant for us to make a decision about accepting the component. |
| 26 | +* The configuration options your component will accept. This will help us understand what it does and have an idea of |
| 27 | + how the implementation might look like. |
14 | 28 |
|
15 | 29 |
|
16 | | -Any component (receiver, processor, exporter, or extension) needs to implement |
17 | | -the interfaces defined on the [core |
18 | | -repository](https://github.com/open-telemetry/opentelemetry-collector). |
19 | | -Familiarize yourself with the interface of the component that you want to |
20 | | -write, and use existing implementations as reference. |
| 30 | +Any component (receiver, processor, exporter, or extension) needs to implement the interfaces defined on the [core |
| 31 | +repository](https://github.com/open-telemetry/opentelemetry-collector). Familiarize yourself with the interface of the |
| 32 | +component that you want to write, and use existing implementations as reference. |
21 | 33 |
|
22 | | -*NOTICE:* The Collector is in Beta stage and as such the interfaces may |
23 | | -undergo breaking changes. Component creators must be available to update or |
24 | | -review their components when such changes happen, otherwise the component will |
25 | | -be excluded from the default builds. |
| 34 | +*NOTICE:* The Collector is in Beta stage and as such the interfaces may undergo breaking changes. Component creators |
| 35 | +must be available to update or review their components when such changes happen, otherwise the component will be |
| 36 | +excluded from the default builds. |
26 | 37 |
|
27 | | -Generally, maintenance of components is the responsibility of contributors who |
28 | | -authored them. If the original author or some other contributor does not |
29 | | -maintain the component it may be excluded from the default build. The component |
30 | | -**will** be excluded if it causes build problems, has failing tests or |
31 | | -otherwise causes problems to the rest of the repository and the rest of |
32 | | -contributors. |
| 38 | +Generally, maintenance of components is the responsibility of contributors who authored them. If the original author or |
| 39 | +some other contributor does not maintain the component it may be excluded from the default build. The component **will** |
| 40 | +be excluded if it causes build problems, has failing tests or otherwise causes problems to the rest of the repository |
| 41 | +and the rest of contributors. |
33 | 42 |
|
34 | | -- Create your component under the proper folder and use Go standard package |
35 | | - naming recommendations. |
36 | | -- Use a boiler-plate Makefile that just references the one at top level, ie.: |
37 | | - `include ../../Makefile.Common` - this allows you to build your component |
38 | | - with required build configurations for the contrib repo while avoiding |
39 | | - building the full repo during development. |
40 | | -- Each component has its own go.mod file. This allows custom builds of the |
41 | | - collector to take a limited sets of dependencies - so run `go mod` commands |
42 | | - as appropriate for your component. |
43 | | -- Implement the needed interface on your component by importing the appropriate |
44 | | - component from the core repo. Follow the pattern of existing components |
45 | | - regarding config and factory source files and tests. |
46 | | -- Implement your component as appropriate. Provide end-to-end tests (or mock |
47 | | - backend/client as appropriate). Target is to get 80% or more of code |
48 | | - coverage. |
49 | | -- Add a README.md on the root of your component describing its configuration |
50 | | - and usage, likely referencing some of the yaml files used in the component |
51 | | - tests. We also suggest that the yaml files used in tests have comments for |
52 | | - all available configuration settings so users can copy and modify them as |
53 | | - needed. |
54 | | -- Add a `replace` directive at the root `go.mod` file so your component is |
55 | | - included in the build of the contrib executable. |
| 43 | +- Create your component under the proper folder and use Go standard package naming recommendations. |
| 44 | +- Use a boiler-plate Makefile that just references the one at top level, ie.: `include ../../Makefile.Common` - this |
| 45 | + allows you to build your component with required build configurations for the contrib repo while avoiding building the |
| 46 | + full repo during development. |
| 47 | +- Each component has its own go.mod file. This allows custom builds of the collector to take a limited sets of |
| 48 | + dependencies - so run `go mod` commands as appropriate for your component. |
| 49 | +- Implement the needed interface on your component by importing the appropriate component from the core repo. Follow the |
| 50 | + pattern of existing components regarding config and factory source files and tests. |
| 51 | +- Implement your component as appropriate. Provide end-to-end tests (or mock backend/client as appropriate). Target is |
| 52 | + to get 80% or more of code coverage. |
| 53 | +- Add a README.md on the root of your component describing its configuration and usage, likely referencing some of the |
| 54 | + yaml files used in the component tests. We also suggest that the yaml files used in tests have comments for all |
| 55 | + available configuration settings so users can copy and modify them as needed. |
| 56 | +- Add a `replace` directive at the root `go.mod` file so your component is included in the build of the contrib |
| 57 | + executable. |
56 | 58 | - Add your component to `versions.yaml`. |
57 | | -- All components must be included in [`internal/components/`](./internal/components) |
58 | | - and in the respective testing harnesses. To align with the test goal of the project, |
59 | | - components must be testable within the framework defined within the folder. |
60 | | - If a component can not be properly tested within the existing framework, |
61 | | - it must increase the non testable components number |
62 | | - with a comment within the PR explaining as to why it can not be tested. |
| 59 | +- All components must be included in [`internal/components/`](./internal/components) and in the respective testing |
| 60 | + harnesses. To align with the test goal of the project, components must be testable within the framework defined within |
| 61 | + the folder. If a component can not be properly tested within the existing framework, it must increase the non testable |
| 62 | + components number with a comment within the PR explaining as to why it can not be tested. |
63 | 63 |
|
64 | 64 | ## General Recommendations |
65 | | -Below are some recommendations that apply to typical components. These are not |
66 | | -rigid rules and there are exceptions but in general try to follow them. |
| 65 | +Below are some recommendations that apply to typical components. These are not rigid rules and there are exceptions but |
| 66 | +in general try to follow them. |
67 | 67 |
|
68 | | -- Avoid introducing batching, retries or worker pools directly on receivers and |
69 | | - exporters. Typically, these are general cases that can be better handled via |
70 | | - processors (that also can be reused by other receivers and exporters). |
71 | | -- When implementing exporters try to leverage the exporter helpers from the |
72 | | - core repo, see [exporterhelper |
73 | | - package](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/exporterhelper). |
74 | | - This will ensure that the exporter provides |
75 | | - [zPages](https://opencensus.io/zpages/) and a standard set of metrics. |
| 68 | +- Avoid introducing batching, retries or worker pools directly on receivers and exporters. Typically, these are general |
| 69 | + cases that can be better handled via processors (that also can be reused by other receivers and exporters). |
| 70 | +- When implementing exporters try to leverage the exporter helpers from the core repo, see [exporterhelper |
| 71 | + package](https://github.com/open-telemetry/opentelemetry-collector/tree/main/exporter/exporterhelper). This will |
| 72 | + ensure that the exporter provides [zPages](https://opencensus.io/zpages/) and a standard set of metrics. |
0 commit comments