Skip to content

Commit 1041a0b

Browse files
authored
[chore][docs] Use consistent title hierarchy (#12272)
<!--Ex. Fixing a bug - Describe the bug and how this fixes the issue. Ex. Adding a feature - Explain what this achieves.--> #### Description <!-- Issue number if applicable --> Use h2 (hN-1) titles for h2 (hN-1) sections instead of h3 (hN)
1 parent 1dccce8 commit 1041a0b

File tree

1 file changed

+28
-28
lines changed

1 file changed

+28
-28
lines changed

docs/coding-guidelines.md

Lines changed: 28 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ for coding advice). The code must adhere to the following robustness principles
77
are important for software that runs autonomously and continuously without direct
88
interaction with a human (such as this Collector).
99

10-
### Naming convention
10+
## Naming convention
1111

1212
To keep naming patterns consistent across the project, naming patterns are enforced to make intent clear by:
1313

@@ -38,7 +38,7 @@ To keep naming patterns consistent across the project, naming patterns are enfor
3838
- `func CreateTracesExport(...) {...}`
3939
- `func CreateTracesToTracesFunc(...) {...}`
4040

41-
#### Configuration structs
41+
### Configuration structs
4242

4343
When naming configuration structs, use the following guidelines:
4444

@@ -47,7 +47,7 @@ When naming configuration structs, use the following guidelines:
4747
- 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.
4848
- Avoid redundant prefixes that are already implied by the package name. For example, use`configgrpc.ClientConfig` instead of `configgrpc.GRPCClientConfig`.
4949

50-
### Module organization
50+
## Module organization
5151

5252
As usual in Go projects, organize your code into packages grouping related functionality. To ensure
5353
that we can evolve different parts of the API independently, you should also group related packages
@@ -82,7 +82,7 @@ When adding a new module remember to update the following:
8282
1. Open a follow up PR to update pseudo-versions in all go.mod files. See [this example
8383
PR](https://github.com/open-telemetry/opentelemetry-collector/pull/11668).
8484

85-
### Enumerations
85+
## Enumerations
8686

8787
To keep naming patterns consistent across the project, enumeration patterns are enforced to make intent clear:
8888

@@ -96,7 +96,7 @@ To keep naming patterns consistent across the project, enumeration patterns are
9696
- `pmetric.MetricTypeGauge` for `pmetric.MetricType`
9797

9898

99-
### Recommended Libraries / Defaults
99+
## Recommended Libraries / Defaults
100100

101101
In order to simplify development within the project, we have made certain library recommendations that should be followed.
102102

@@ -108,13 +108,13 @@ In order to simplify development within the project, we have made certain librar
108108

109109
Within the project, there are some packages that have yet to follow the recommendations and are being addressed. However, any new code should adhere to the recommendations.
110110

111-
### Default Configuration
111+
## Default Configuration
112112

113113
To guarantee backward-compatible behavior, all configuration packages should supply a `NewDefault[config name]` functions that create a default version of the config. The package does not need to guarantee that `NewDefault[config name]` returns a usable configuration—only that default values will be set. For example, if the configuration requires that a field, such as `Endpoint` be set, but there is no valid default value, then `NewDefault[config name]` may set that value to `""` with the expectation that the user will set a valid value.
114114

115115
Users should always initialize the config struct with this function and overwrite anything as needed.
116116

117-
### Startup Error Handling
117+
## Startup Error Handling
118118

119119
Verify configuration during startup and fail fast if the configuration is invalid.
120120
This will bring the attention of a human to the problem as it is more typical for humans
@@ -126,15 +126,15 @@ explain the problem and exit with a non-zero code. It is acceptable to crash the
126126
during startup if there is no good way to exit cleanly but do your best to log and
127127
exit cleanly with a process exit code.
128128

129-
### Propagate Errors to the Caller
129+
## Propagate Errors to the Caller
130130

131131
Do not crash or exit outside the `main()` function, e.g. via `log.Fatal` or `os.Exit`,
132132
even during startup. Instead, return detailed errors to be handled appropriately
133133
by the caller. The code in packages other than `main` may be imported and used by
134134
third-party applications, and they should have full control over error handling
135135
and process termination.
136136

137-
### Do not Crash after Startup
137+
## Do not Crash after Startup
138138

139139
Do not crash or exit the Collector process after the startup sequence is finished.
140140
A running Collector typically contains data that is received but not yet exported further
@@ -143,7 +143,7 @@ process will result in losing this data since typically the receiver has
143143
already acknowledged the receipt for this data and the senders of the data will
144144
not send that data again.
145145

146-
### Bad Input Handling
146+
## Bad Input Handling
147147

148148
Do not crash on bad input in receivers or elsewhere in the pipeline.
149149
[Crash-only software](https://en.wikipedia.org/wiki/Crash-only_software)
@@ -160,7 +160,7 @@ sender. If it is elsewhere in the pipeline it may be too late to send a response
160160
to the sender (particularly in processors which are not synchronously processing
161161
data). In either case, it is recommended to keep a metric that counts bad input data.
162162

163-
### Error Handling and Retries
163+
## Error Handling and Retries
164164

165165
Be rigorous in error handling. Don't ignore errors. Think carefully about each
166166
error and decide if it is a fatal problem or a transient problem that may go away
@@ -173,7 +173,7 @@ your destination when the network is restored or the destination is recovered.
173173
[Exponential Backoff](https://github.com/cenkalti/backoff) is a good library that
174174
provides all this functionality.
175175

176-
### Logging
176+
## Logging
177177

178178
Log your component startup and shutdown, including successful outcomes (but don't
179179
overdo it, and keep the number of success messages to a minimum).
@@ -190,7 +190,7 @@ the event happens.
190190
Make log messages human readable and also include data that is needed for easier
191191
understanding of what happened and in what context.
192192

193-
### Executing External Processes
193+
## Executing External Processes
194194

195195
The components should avoid executing arbitrary external processes with arbitrary command
196196
line arguments based on user input, including input received from the network or input
@@ -208,7 +208,7 @@ The following limitations are recommended:
208208
if necessary, deriving the value from the user input. Limit as much as possible the
209209
size of the possible space of values for command line arguments.
210210

211-
### Observability
211+
## Observability
212212

213213
Out of the box, your users should be able to observe the state of your
214214
component. See [observability.md](observability.md) for more details.
@@ -293,7 +293,7 @@ builder:
293293
tsp.telemetry.ProcessorTailsamplingSamplingdecisionLatency.Record(ctx, ...)
294294
```
295295

296-
### Resource Usage
296+
## Resource Usage
297297

298298
Limit usage of CPU, RAM, and other resources that the code can use. Do not write code
299299
that consumes resources in an uncontrolled manner. For example, if you have a queue
@@ -310,7 +310,7 @@ runs out of memory. Instead have protections for these situations, e.g. when hit
310310
resource limits drop the data and record the fact that it was dropped in a metric
311311
that is exposed to users.
312312

313-
### Graceful Shutdown
313+
## Graceful Shutdown
314314

315315
Collector does not yet support graceful shutdown but we plan to add it. All components
316316
must be ready to shutdown gracefully via `Shutdown()` function that all component
@@ -319,14 +319,14 @@ and export it out of the Collector before shutdown is completed. The shutdown pr
319319
will have a maximum allowed duration so put a limit on how long your shutdown
320320
operation can take.
321321

322-
### Unit Tests
322+
## Unit Tests
323323

324324
Cover important functionality with unit tests. We require that contributions
325325
do not decrease the overall code coverage of the codebase - this is aligned with our
326326
goal to increase coverage over time. Keep track of execution time for your unit
327327
tests and try to keep them as short as possible.
328328

329-
#### Testing Library Recommendations
329+
### Testing Library Recommendations
330330

331331
To keep testing practices consistent across the project, it is advised to use these libraries under
332332
these circumstances:
@@ -336,12 +336,12 @@ these circumstances:
336336
- For mocking external resources, use `"github.com/stretchr/testify/mock"`
337337
- For validating HTTP traffic interactions, `"net/http/httptest"`
338338

339-
### Integration Testing
339+
## Integration Testing
340340

341341
Integration testing is encouraged throughout the project, container images can be used in order to facilitate
342342
a local version. In their absence, it is strongly advised to mock the integration.
343343

344-
### Using CGO
344+
## Using CGO
345345

346346
Using CGO is prohibited due to the lack of portability and complexity
347347
that comes with managing external libraries with different operating systems and configurations.
@@ -350,7 +350,7 @@ with clear instructions on how to install the required libraries.
350350
Furthermore, if your package requires CGO, it MUST be able to compile and operate in a no-op mode
351351
or report a warning back to the collector with a clear error saying CGO is required to work.
352352

353-
### Breaking changes
353+
## Breaking changes
354354

355355
Whenever possible, we adhere to [semver](https://semver.org/) as our minimum standards. Even before v1, we strive not to break compatibility
356356
without a good reason. Hence, when a change is known to cause a breaking change, it MUST be clearly marked in the
@@ -377,7 +377,7 @@ package test
377377
func DoFoo() {}
378378
```
379379

380-
#### End-user impacting changes
380+
### End-user impacting changes
381381

382382
When deprecating a feature affecting end-users, consider first deprecating the feature in one version, then hiding it
383383
behind a [feature
@@ -389,15 +389,15 @@ that each of the following steps is done in a separate version:
389389
1. Change the feature gate to disable the feature by default, deprecating the gate at the same time
390390
1. Remove the feature and the gate
391391

392-
#### Example #1 - Renaming a function
392+
### Example #1 - Renaming a function
393393

394394
1. Current version `v0.N` has `func GetFoo() Bar`
395395
1. We now decided that `GetBar` is a better name. As such, on `v0.N+1` we add a new `func GetBar() Bar` function,
396396
changing the existing `func GetFoo() Bar` to be an alias of the new function. Additionally, a log entry with a
397397
warning is added to the old function, along with an entry to the changelog.
398398
1. On `v0.N+2`, we MAY remove `func GetFoo() Bar`.
399399

400-
#### Example #2 - Changing the return values of a function
400+
### Example #2 - Changing the return values of a function
401401

402402
1. Current version `v0.N` has `func GetFoo() Foo`
403403
1. We now need to also return an error. We do it by creating a new function that will be equivalent to the existing one
@@ -406,7 +406,7 @@ that each of the following steps is done in a separate version:
406406
entry with a warning.
407407
1. On `v0.N+2`, we change `func GetFoo() Foo` to `func GetFoo() (Foo, error)`.
408408

409-
#### Example #3 - Changing the arguments of a function
409+
### Example #3 - Changing the arguments of a function
410410

411411
1. Current version `v0.N` has `func GetFoo() Foo`
412412
2. We now decide to do something that might be blocking as part of `func GetFoo() Foo`, so, we start accepting a
@@ -416,7 +416,7 @@ that each of the following steps is done in a separate version:
416416
3. On `v0.N+2`, we change `func GetFoo() Foo` to `func GetFoo(context.Context) Foo` if desired or remove it entirely if
417417
needed.
418418

419-
#### Exceptions
419+
### Exceptions
420420

421421
For changes to modules that do not have a version of `v1` or higher, we may skip the deprecation process described above
422422
for the following situations. Note that these changes should still be recorded as breaking changes in the changelog.
@@ -429,11 +429,11 @@ for the following situations. Note that these changes should still be recorded a
429429
breaking change. For this reason, the deprecation process should only be skipped when it is not expected that
430430
the function is commonly passed as a value.
431431

432-
#### Configuration changes
432+
### Configuration changes
433433

434434
See [docs/component-stability.md](component-stability.md) for more information on how to handle configuration changes.
435435

436-
### Specification Tracking
436+
## Specification Tracking
437437

438438
The [OpenTelemetry Specification](https://github.com/open-telemetry/opentelemetry-specification) can be a rapidly
439439
moving target at times. While it may seem efficient to get an early start on implementing new features or

0 commit comments

Comments
 (0)