Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: update guidelines #1882

Merged
merged 1 commit into from
Dec 31, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 35 additions & 3 deletions GUIDELINES.md
Original file line number Diff line number Diff line change
Expand Up @@ -127,8 +127,40 @@ To support this use case, you can choose one of the following options:

It is recommended to use this option when the types involved are simple and short.

3. Use `any` type, and add a comment to guide users on what type they should expect, with a link to its definition.
3. Use a [generic type](https://www.typescriptlang.org/docs/handbook/2/generics.html#generic-types) and add a comment to guide users on what type they should use, with a link to its definition.

This option will offer no typing aid to the instrumentation consumer, which will move the burden and risk of checking type correctness to the user.
This approach is useful when types have breaking changes within the versions supported and there are too many declarations to copied over.

It is recommended to implement it only if the previous options are not feasible or are too complex to use.
This option will offer typing aid to the instrumentation consumer with the same version of types is used in the instrumented application.

You may import the types package for internal use but use generics for the types you want to export.

```js
// package.json
{
"name": "@opentelemetry/instrumentation-bar",
...
"devDependencies": {
"@types/foo": "1.2.3"
},
...
}

// types.ts

export interface FooRequestInfo<BarType = any> {
bar: BarType;
}
...
```

```js
// app.ts
import { FooRequestInfo } from "@opentelemetry/instrumentation-bar";
import type { Bar } from 'foo';

const requestInfo: FooRequestInfo<Bar> = {
bar: { ... },
};
...
```
Loading