Skip to content

Commit

Permalink
[pkg/ottl] Added 'Adding new functions/converters' guidelines (#33117)
Browse files Browse the repository at this point in the history
**Description:** 
As discussed
[here](#32433 (comment))
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 <jaglows3@gmail.com>
  • Loading branch information
4 people authored Jun 14, 2024
1 parent 71bb4b0 commit 69e9141
Showing 1 changed file with 21 additions and 0 deletions.
21 changes: 21 additions & 0 deletions pkg/ottl/ottlfuncs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

0 comments on commit 69e9141

Please sign in to comment.