From 1aee24bdf61d097436178115bd1c4093a465e730 Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Sat, 18 May 2024 17:28:01 +0200 Subject: [PATCH 1/9] Added 'Adding new functions/converters' guidelines --- pkg/ottl/ottlfuncs/README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 4abbb3ea9508..e204d7d82704 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1308,3 +1308,25 @@ 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 Functions/Converters + +Before raising a PR with a new function or converter, raise a PR to verify its acceptance. While acceptance is strongly specific to a specific use case, consider these guidelines for early assessment. + +You're more than welcome to open an issue 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` should aim for readability first. This means: +- Using short, meaningful, and descriptive names, +- Ensuring naming consistency across functions and converters, +- Avoiding deep nesting to achieve desired transformations, +- Ensuring functions and converters have a single responsibility, +- Following the DRY principle, avoiding multiple functions doing the same thing. \ No newline at end of file From 271d81c8b28945e04ff8afc2a885ff73b032b181 Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 24 May 2024 14:01:32 +0200 Subject: [PATCH 2/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index e204d7d82704..6953d80c1579 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1309,7 +1309,7 @@ Functions should be named and formatted according to the following standards. - 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 Functions/Converters +## Adding New Editors/Converters Before raising a PR with a new function or converter, raise a PR to verify its acceptance. While acceptance is strongly specific to a specific use case, consider these guidelines for early assessment. From c17208d29d74d2cd08e07a50193a8a75eb69c9db Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 24 May 2024 14:01:40 +0200 Subject: [PATCH 3/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 6953d80c1579..50c131bb8428 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1313,7 +1313,7 @@ Functions should be named and formatted according to the following standards. Before raising a PR with a new function or converter, raise a PR to verify its acceptance. While acceptance is strongly specific to a specific use case, consider these guidelines for early assessment. -You're more than welcome to open an issue if: +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. From 3b7b1c5a15522d483927a590fa53e4d99782248e Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 24 May 2024 14:01:46 +0200 Subject: [PATCH 4/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 50c131bb8428..4fd2299e0c77 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1326,7 +1326,7 @@ Your proposal likely won't be accepted if: As with code, `ottl` should aim for readability first. This means: - Using short, meaningful, and descriptive names, -- Ensuring naming consistency across functions and converters, +- Ensuring naming consistency across Editors and Converters, - Avoiding deep nesting to achieve desired transformations, - Ensuring functions and converters have a single responsibility, - Following the DRY principle, avoiding multiple functions doing the same thing. \ No newline at end of file From 81a5a4a7daecf8e598b9849a9de8b1bf18d4f56b Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 24 May 2024 14:01:53 +0200 Subject: [PATCH 5/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 4fd2299e0c77..8a583d2499d5 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1328,5 +1328,5 @@ As with code, `ottl` should aim 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 functions and converters have a single responsibility, +- Ensuring Editors and Converters have a single responsibility, - Following the DRY principle, avoiding multiple functions doing the same thing. \ No newline at end of file From 255931472840a85c43d12ad3517bf12757d3a9e5 Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Fri, 24 May 2024 14:02:50 +0200 Subject: [PATCH 6/9] Update README.md --- pkg/ottl/ottlfuncs/README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 8a583d2499d5..c3833ff486ae 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1328,5 +1328,4 @@ As with code, `ottl` should aim 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, -- Following the DRY principle, avoiding multiple functions doing the same thing. \ No newline at end of file +- Ensuring Editors and Converters have a single responsibility. From 040600cb229f8ba7dbf2e89335c1ea026cc1e3bc Mon Sep 17 00:00:00 2001 From: Tyler Helmuth <12352919+TylerHelmuth@users.noreply.github.com> Date: Wed, 29 May 2024 16:34:01 -0600 Subject: [PATCH 7/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Daniel Jaglowski --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 040c206e7175..9dbc7d050029 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1356,7 +1356,7 @@ Functions should be named and formatted according to the following standards. ## Adding New Editors/Converters -Before raising a PR with a new function or converter, raise a PR to verify its acceptance. While acceptance is strongly specific to a specific use case, consider these guidelines for early assessment. +Before raising a PR with a new function 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, From 124e00f80acb9b59e493b851ba4c72af4948d48d Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Thu, 13 Jun 2024 17:12:29 +0200 Subject: [PATCH 8/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 4789647355bf..241d49a56da2 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1403,7 +1403,7 @@ Functions should be named and formatted according to the following standards. ## Adding New Editors/Converters -Before raising a PR with a new function 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. +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, From 10035baf044748ce631f8ac35e7e0127fe1715bf Mon Sep 17 00:00:00 2001 From: Michal Pristas Date: Thu, 13 Jun 2024 17:12:37 +0200 Subject: [PATCH 9/9] Update pkg/ottl/ottlfuncs/README.md Co-authored-by: Evan Bradley <11745660+evan-bradley@users.noreply.github.com> --- pkg/ottl/ottlfuncs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/ottl/ottlfuncs/README.md b/pkg/ottl/ottlfuncs/README.md index 241d49a56da2..993f9d34ce2f 100644 --- a/pkg/ottl/ottlfuncs/README.md +++ b/pkg/ottl/ottlfuncs/README.md @@ -1416,7 +1416,7 @@ 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` should aim for readability first. This means: +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,