From 69e914151e74435361a4ec0ebe3a01043c96a5b6 Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 14 Jun 2024 04:33:05 +0200 Subject: [PATCH] [pkg/ottl] Added 'Adding new functions/converters' guidelines (#33117) **Description:** As discussed [here](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/32433#issuecomment-2117931670) we should agree on some guidelines when it comes to creating proposals for new functions and converters cc @TylerHelmuth **Link to tracking Issue:** - **Testing:** - **Documentation:** - --------- Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> Co-authored-by: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> Co-authored-by: Daniel Jaglowski --- pkg/ottl/ottlfuncs/README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index cf39931f489e..993f9d34ce2f 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1400,3 +1400,24 @@ Functions should be named and formatted according to the following standards. - Functions that interact with multiple items MUST have plurality in the name. Ex: `truncate_all`, `keep_keys`, `replace_all_matches`. - Functions that interact with a single item MUST NOT have plurality in the name. If a function would interact with multiple items due to a condition, like `where`, it is still considered singular. Ex: `set`, `delete`, `replace_match`. - Functions that change a specific target MUST set the target as the first parameter. + +## Adding New Editors/Converters + +Before raising a PR with a new Editor or Converter, raise an issue to verify its acceptance. While acceptance is strongly specific to a specific use case, consider these guidelines for early assessment. + +Your proposal likely will be accepted if: +- The proposed functionality is missing, +- The proposed solution significantly improves user experience and readability for very common use cases, +- The proposed solution is more performant in cases where it is possible to achieve the same result with existing options. + +It will be up for discussion if your proposal solves an issue that can be achieved in another way but does not improve user experience or performance. + +Your proposal likely won't be accepted if: +- User experience is worse and assumes a highly technical user, +- The performance of your proposal very negatively affects the processing pipeline. + +As with code, OTTL aims for readability first. This means: +- Using short, meaningful, and descriptive names, +- Ensuring naming consistency across Editors and Converters, +- Avoiding deep nesting to achieve desired transformations, +- Ensuring Editors and Converters have a single responsibility.