From 1ed06b5ab961c6fbfd2b88ab609e80492c7198cc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 23:41:27 +0000 Subject: [PATCH 1/4] Initial plan From b7abf5d9dd4764d54d3f1b4966577564b05fdcf2 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Tue, 11 Nov 2025 23:55:55 +0000 Subject: [PATCH 2/4] Add guidance for plugins vs config options in emitters Added a new section in the emitters-basics documentation explaining when to use plugins versus configuration options. This includes: - Clear definitions of plugins (composable visitor sets for specific scenarios) - When to use config options (independent toggleable features) - Best practices for avoiding unnecessary configuration - Practical examples to help emitter authors make the right choice Co-authored-by: JoshLove-msft <54595583+JoshLove-msft@users.noreply.github.com> --- .../extending-typespec/emitters-basics.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/website/src/content/docs/docs/extending-typespec/emitters-basics.md b/website/src/content/docs/docs/extending-typespec/emitters-basics.md index 15d06f5a43d..30dbd33e007 100644 --- a/website/src/content/docs/docs/extending-typespec/emitters-basics.md +++ b/website/src/content/docs/docs/extending-typespec/emitters-basics.md @@ -132,6 +132,36 @@ Example: The general guideline is to use a decorator when the customization is intrinsic to the API itself. In other words, when all uses of the TypeSpec program would use the same configuration. This is not the case for `outputFilename` because different users of the API might want to emit the files in different locations depending on how their code generation pipeline is set up. +#### Plugins vs. config options + +When adding configurability to an emitter, you should consider whether to use plugins or configuration options: + +**Plugins** are composable sets of visitors or components that are targeted towards a specific scenario. Use plugins when: + +- You have a cohesive set of transformations or behaviors that work together to achieve a particular goal +- The functionality represents a distinct use case or workflow (e.g., client generation, server generation, documentation generation) +- Users would typically enable or disable the entire feature set as a unit +- The plugin encapsulates a set of related behaviors that may need to be shared or reused across different emitters + +**Configuration options** are flags that can be mixed and matched independently. Use config options when: + +- You have individual features that users may want to enable or disable independently +- The option controls a specific behavior or output characteristic (e.g., file format, naming conventions, feature flags) +- Users might want different combinations of these flags for different scenarios +- The option is a simple toggle or value that doesn't require complex logic + +**Best practice:** Whenever possible, enable features by default without requiring configuration. Only add configuration when: + +- Different users have genuinely different needs or preferences +- The feature has trade-offs that different users might evaluate differently +- Backward compatibility requires making a change opt-in + +For example, if you're adding support for generating additional utility functions, consider whether this should be: + +- A plugin (if it's a comprehensive feature set for a specific scenario like "client utilities") +- A config option (if it's a simple toggle like `generate-utility-functions: true`) +- Always enabled (if it's a clear improvement with no downsides) + ## Emitting TypeSpec types to assets on disk One of the main tasks of an emitter is to identify types to emit. There are three primary methods: From 32c629332dd5690719b0e1e0004a8f6800a1e5ce Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 12 Nov 2025 00:05:44 +0000 Subject: [PATCH 3/4] Remove example section from plugins vs config options guidance As requested in PR feedback, removed the example section (lines 159-163) that didn't provide clear guidance on which route to take. Co-authored-by: JoshLove-msft <54595583+JoshLove-msft@users.noreply.github.com> --- .../content/docs/docs/extending-typespec/emitters-basics.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/website/src/content/docs/docs/extending-typespec/emitters-basics.md b/website/src/content/docs/docs/extending-typespec/emitters-basics.md index 30dbd33e007..dd4771cdb3f 100644 --- a/website/src/content/docs/docs/extending-typespec/emitters-basics.md +++ b/website/src/content/docs/docs/extending-typespec/emitters-basics.md @@ -156,12 +156,6 @@ When adding configurability to an emitter, you should consider whether to use pl - The feature has trade-offs that different users might evaluate differently - Backward compatibility requires making a change opt-in -For example, if you're adding support for generating additional utility functions, consider whether this should be: - -- A plugin (if it's a comprehensive feature set for a specific scenario like "client utilities") -- A config option (if it's a simple toggle like `generate-utility-functions: true`) -- Always enabled (if it's a clear improvement with no downsides) - ## Emitting TypeSpec types to assets on disk One of the main tasks of an emitter is to identify types to emit. There are three primary methods: From 7da3f14270a77212ebf697fbf3b4239bda8a161b Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Wed, 12 Nov 2025 00:09:30 +0000 Subject: [PATCH 4/4] Remove vague "trade-offs" guidance line Removed the unclear "trade-offs" line from best practices as it didn't provide actionable guidance. Co-authored-by: JoshLove-msft <54595583+JoshLove-msft@users.noreply.github.com> --- .../src/content/docs/docs/extending-typespec/emitters-basics.md | 1 - 1 file changed, 1 deletion(-) diff --git a/website/src/content/docs/docs/extending-typespec/emitters-basics.md b/website/src/content/docs/docs/extending-typespec/emitters-basics.md index dd4771cdb3f..81eb06c525f 100644 --- a/website/src/content/docs/docs/extending-typespec/emitters-basics.md +++ b/website/src/content/docs/docs/extending-typespec/emitters-basics.md @@ -153,7 +153,6 @@ When adding configurability to an emitter, you should consider whether to use pl **Best practice:** Whenever possible, enable features by default without requiring configuration. Only add configuration when: - Different users have genuinely different needs or preferences -- The feature has trade-offs that different users might evaluate differently - Backward compatibility requires making a change opt-in ## Emitting TypeSpec types to assets on disk