Skip to content

Commit 9fc5f56

Browse files
authored
Add pull-request title guideline (open-telemetry#7752)
* Rewrap contributing guidelines Signed-off-by: Juraci Paixão Kröhling <juraci@kroehling.de>
1 parent 519ea7f commit 9fc5f56

File tree

1 file changed

+57
-60
lines changed

1 file changed

+57
-60
lines changed

CONTRIBUTING.md

Lines changed: 57 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,75 +1,72 @@
11
# Contributing
22

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
613

714
## Adding New Components
815

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:
1019

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.
1428

1529

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.
2133

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.
2637

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.
3342

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.
5658
- 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.
6363

6464
## 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.
6767

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

Comments
 (0)