From eee55ae5c2f7d0e1615df06882bd6b4ee7adfe66 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 25 Feb 2026 16:19:15 -0800 Subject: [PATCH 01/13] initial stub of a best practice template for ESG --- .../templates/0000-best-practice-template.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 ecosystem-tools/templates/0000-best-practice-template.md diff --git a/ecosystem-tools/templates/0000-best-practice-template.md b/ecosystem-tools/templates/0000-best-practice-template.md new file mode 100644 index 000000000..253e9e7ca --- /dev/null +++ b/ecosystem-tools/templates/0000-best-practice-template.md @@ -0,0 +1,47 @@ +# (ESG-0000) best practice title + + + +{{ A single sentence abstract that describes what the best practice covers, expanding upon title. }} + +## Overview + +🟢 - lead sentence details the core of what the good practice is. The overview in general should be concise and to the point. + +Extend the overview with an additional paragraph providing more background if needed, preferring to link to external specifications, documentation, etc as needed instead of providing it inline. + + + +### Example + +Provide a clear, complete, ideally "real" example of the best practice. If describing an API pattern, show both the implementation side and "call site" usage to illustrate it. + +If there's supporting tasks for the best practice, include the specifics of how to enable them in further H3 sections. Write The H3 section headings as imperative verb phrases that describe what the example is showing and what you should do for the best practice. + +## Alternatives Considered + +Lead with a 🟠 yellow/orange stoplight emoji to indicate alternates with tradeoffs. Explain when/why you might need to fall back and not use the best practice. + +Lead with a 🔴 red stoplight emoji to indicate an anti-pattern and what not to do. Explain why or the impact of not following the best practice. + +## History + + + +| Last updated | Swift Versions | +| ---- | ---- | +| February 2026 | Swift >= 6.0+ | From 7afb1fef505dcd542d73e8997f4c0ebbae669e85 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 2 Mar 2026 08:25:22 -0600 Subject: [PATCH 02/13] adding Snippet suggestion for code reference blocks to verify compiilation --- ecosystem-tools/templates/0000-best-practice-template.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/ecosystem-tools/templates/0000-best-practice-template.md b/ecosystem-tools/templates/0000-best-practice-template.md index 253e9e7ca..6bc414898 100644 --- a/ecosystem-tools/templates/0000-best-practice-template.md +++ b/ecosystem-tools/templates/0000-best-practice-template.md @@ -7,7 +7,7 @@ - Once approved, ***never rename***, only deprecate or remove. --> -{{ A single sentence abstract that describes what the best practice covers, expanding upon title. }} +{{ Replace with a single sentence abstract that describes what the best practice covers and expands upon title. }} ## Overview @@ -29,6 +29,13 @@ Provide a clear, complete, ideally "real" example of the best practice. If descr If there's supporting tasks for the best practice, include the specifics of how to enable them in further H3 sections. Write The H3 section headings as imperative verb phrases that describe what the example is showing and what you should do for the best practice. + + ## Alternatives Considered Lead with a 🟠 yellow/orange stoplight emoji to indicate alternates with tradeoffs. Explain when/why you might need to fall back and not use the best practice. From b5e20f47700a466b472615dc12cdadaea16d9dfe Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 13 Mar 2026 13:17:50 -0700 Subject: [PATCH 03/13] adding article that describes how to assemble a best practice, using the template provided. Adds structure to host best practices in the future --- .../EcosystemTools.docc/Documentation.md | 6 +- .../best-practices/best-practice-content.md | 63 +++++++++++++++++++ .../best-practices/best-practices.md | 9 +++ 3 files changed, 77 insertions(+), 1 deletion(-) create mode 100644 ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md create mode 100644 ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practices.md diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md index e92873a08..98a06371f 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md @@ -2,4 +2,8 @@ @Metadata { @DisplayName("Tools and Editors") -} \ No newline at end of file +} + +## Topics + +- diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md new file mode 100644 index 000000000..191033181 --- /dev/null +++ b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md @@ -0,0 +1,63 @@ +# Contribute a Swift Server best practice for internal adopters + +Create clear guidance with examples for best practice documentation. + +## Overview + +A best practice article provides practical advice from experienced Swift practitioners, solving common problems, or providing support to others doing the same. +These articles use a specific naming scheme to enable consistent URLs when they're published, so that those URLs can be referenced, or shared, from a variety of places. + +### Create a guidance article + +Use the [template provided in the Ecosystem docs repository](https://github.com/swiftlang/docs/blob/main/ecosystem-tools/templates/0000-best-practice-template.md) to create guidance. +Use a numbered filename to contain the content. +Prefix guidelines from the ecosystem group with `ESG-` and using the next number available. +When published with DocC, the filename of the article becomes a component in the URL and provides a consistent reference point. +Don't rename an existing article, or re-use a number from other guides that have been merged. + +### Create an a title and abstract for the article + +Provide a title and abstract that provides a high level, skimmable overview of the guidance. +The title should by a high level summary, and the abstract should work with the title to provide additional detail on where or how the guidance applies. + +### Make an overview + +Add an explicit `## Overview` section to provide an a concise introduction that cuts to the heart of the guidance and why it's important. The overview should: +- Identify the problem this guide solves, or what issues it avoids. +- Provide a concise summary (one to three sentences, not a paragraph or more) of why the problem is an issue and what benefits you get following the guidance. +- Identify the scope of the guidance: how or where it pertains, if the guidance isn't generally applicable. + +### Provide an example of the guidance + +Add a section header with an imperative title that provides the guidance. +Prefix the content with a green sphere (🟢), which uses a stop-light metaphor, so the reader can easily visually identify the preferred guidance. + +Provide code examples that illustrate the guidance, using DocC's snippets feature to ensure that the example compiles: + + - For anything other than trivial code examples, create and use a snippet Swift file to verify that code samples compile. + - To use a snippet, create a Swift file in the Snippets directory and reference the snippet in this template. + - Reference the snippet in the best practice using the @Snippet directive. For example, if you create a snippet file named `ESG-0005.swift` in the Snippets directory, use the directive reference: `@Snippet(path: "EcosystemTools/Snippets/ESG-0005")` + +### Share alternatives considered + +Add the section `### Alternatives Considered` for a section to highlight lessor guidance. +For example, to illustrate patterns that work but aren't ideal, or express anti-patterns to avoid. +Any additional content in this section should provide detail as to why the pattern is suboptimal or one to avoid. + + - Use a yellow sphere (🟠) to highlight suboptimal advice or patterns that may be required, but is not as good a solution as the primary guidance. + + - Use a red sphere (🛑) to highlight antipatterns or specifics to avoid. + +### Identify the recency and applicability of the article + +At that bottom of the document, include a "History" section to share relevant to specific versions of swift, and recen +cy of the guidance. +The following example shows a history block last updated in March, 2026 and with content relevant to Swift 6.0 or earlier: + +``` +### History + +| Last updated | Swift Versions | +| ---- | ---- | +| March 2026 | Swift >= 6.0+ | +``` \ No newline at end of file diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practices.md b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practices.md new file mode 100644 index 000000000..2c3de52fa --- /dev/null +++ b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practices.md @@ -0,0 +1,9 @@ +# Guidelines and Best Practices + +## Overview + +## Topics + +### Reviews + +- \ No newline at end of file From badbe3b8349697eb1a1408016052f4cae650635e Mon Sep 17 00:00:00 2001 From: Joseph Heck Date: Thu, 9 Apr 2026 08:37:29 -0700 Subject: [PATCH 04/13] Apply suggestions from code review Co-authored-by: Franz Busch --- .../best-practices/best-practice-content.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md index 191033181..c5ddfa02c 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md @@ -1,4 +1,4 @@ -# Contribute a Swift Server best practice for internal adopters +# Contribute a Swift best practice Create clear guidance with examples for best practice documentation. @@ -11,7 +11,7 @@ These articles use a specific naming scheme to enable consistent URLs when they' Use the [template provided in the Ecosystem docs repository](https://github.com/swiftlang/docs/blob/main/ecosystem-tools/templates/0000-best-practice-template.md) to create guidance. Use a numbered filename to contain the content. -Prefix guidelines from the ecosystem group with `ESG-` and using the next number available. +Prefix guidelines from the ecosystem group with `BSP-` and using the next number available. When published with DocC, the filename of the article becomes a component in the URL and provides a consistent reference point. Don't rename an existing article, or re-use a number from other guides that have been merged. From aaeacfe48aaa912fae8dcb89b89d32057535ad93 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 9 Apr 2026 08:39:43 -0700 Subject: [PATCH 05/13] consolidating on BSP- as prefix --- .../EcosystemTools.docc/best-practices/best-practice-content.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md index c5ddfa02c..381a1293f 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md @@ -36,7 +36,7 @@ Provide code examples that illustrate the guidance, using DocC's snippets featur - For anything other than trivial code examples, create and use a snippet Swift file to verify that code samples compile. - To use a snippet, create a Swift file in the Snippets directory and reference the snippet in this template. - - Reference the snippet in the best practice using the @Snippet directive. For example, if you create a snippet file named `ESG-0005.swift` in the Snippets directory, use the directive reference: `@Snippet(path: "EcosystemTools/Snippets/ESG-0005")` + - Reference the snippet in the best practice using the @Snippet directive. For example, if you create a snippet file named `BSP-0005.swift` in the Snippets directory, use the directive reference: `@Snippet(path: "EcosystemTools/Snippets/BSP-0005")` ### Share alternatives considered From f756f8d0f3211eea479eacd8dd0e83d61158e8c4 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 9 Apr 2026 09:01:39 -0700 Subject: [PATCH 06/13] add section on ESG setup, not public/open yet - and apply grammar and sspelling fixes across the two files --- .../best-practices/best-practice-content.md | 36 ++++++++++--------- .../templates/0000-best-practice-template.md | 6 ++-- 2 files changed, 23 insertions(+), 19 deletions(-) diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md index 381a1293f..b6e51d164 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/best-practices/best-practice-content.md @@ -1,28 +1,33 @@ -# Contribute a Swift best practice +# Contributing a Swift best practice Create clear guidance with examples for best practice documentation. ## Overview -A best practice article provides practical advice from experienced Swift practitioners, solving common problems, or providing support to others doing the same. -These articles use a specific naming scheme to enable consistent URLs when they're published, so that those URLs can be referenced, or shared, from a variety of places. +A best practice article provides practical advice that solves common problems and supports others doing the same. +These articles use a specific naming scheme to enable consistent URLs when published, so that people can reference or share those URLs from many places. + +The [Ecosystem steering group](https://www.swift.org/ecosystem-steering-group/) develops and approves these practices. +Contributions to best practice content require coordination with the Ecosystem steering group. +The group is establishing review processes and building an initial set of guides before broadening participation. + ### Create a guidance article Use the [template provided in the Ecosystem docs repository](https://github.com/swiftlang/docs/blob/main/ecosystem-tools/templates/0000-best-practice-template.md) to create guidance. Use a numbered filename to contain the content. -Prefix guidelines from the ecosystem group with `BSP-` and using the next number available. +Prefix guidelines from the ecosystem group with `BSP-` and use the next number available. When published with DocC, the filename of the article becomes a component in the URL and provides a consistent reference point. -Don't rename an existing article, or re-use a number from other guides that have been merged. +Don't rename an existing article or reuse a number from other guides that have been merged. -### Create an a title and abstract for the article +### Create a title and abstract for the article -Provide a title and abstract that provides a high level, skimmable overview of the guidance. -The title should by a high level summary, and the abstract should work with the title to provide additional detail on where or how the guidance applies. +Provide a title and abstract that provide a high-level, skimmable overview of the guidance. +The title should be a high-level summary, and the abstract should work with the title to provide additional detail on where or how the guidance applies. ### Make an overview -Add an explicit `## Overview` section to provide an a concise introduction that cuts to the heart of the guidance and why it's important. The overview should: +Add an explicit `## Overview` section to provide a concise introduction that cuts to the heart of the guidance and why it's important. The overview should: - Identify the problem this guide solves, or what issues it avoids. - Provide a concise summary (one to three sentences, not a paragraph or more) of why the problem is an issue and what benefits you get following the guidance. - Identify the scope of the guidance: how or where it pertains, if the guidance isn't generally applicable. @@ -40,24 +45,23 @@ Provide code examples that illustrate the guidance, using DocC's snippets featur ### Share alternatives considered -Add the section `### Alternatives Considered` for a section to highlight lessor guidance. +Add the section `### Alternatives Considered` for a section to highlight lesser guidance. For example, to illustrate patterns that work but aren't ideal, or express anti-patterns to avoid. -Any additional content in this section should provide detail as to why the pattern is suboptimal or one to avoid. +Any additional content in this section should provide detail on why the pattern is suboptimal or one to avoid. - - Use a yellow sphere (🟠) to highlight suboptimal advice or patterns that may be required, but is not as good a solution as the primary guidance. + - Use a yellow sphere (🟠) to highlight suboptimal advice or patterns that may work but don't match the primary guidance. - Use a red sphere (🛑) to highlight antipatterns or specifics to avoid. ### Identify the recency and applicability of the article -At that bottom of the document, include a "History" section to share relevant to specific versions of swift, and recen -cy of the guidance. -The following example shows a history block last updated in March, 2026 and with content relevant to Swift 6.0 or earlier: +At the bottom of the document, include a "History" section to share the recency and relevance to specific versions of Swift. +The following example shows a history block last updated in March 2026, with content relevant to Swift 6.0 and later: ``` ### History | Last updated | Swift Versions | | ---- | ---- | -| March 2026 | Swift >= 6.0+ | +| March 2026 | Swift >= 6.0 | ``` \ No newline at end of file diff --git a/ecosystem-tools/templates/0000-best-practice-template.md b/ecosystem-tools/templates/0000-best-practice-template.md index 6bc414898..9d0297a3b 100644 --- a/ecosystem-tools/templates/0000-best-practice-template.md +++ b/ecosystem-tools/templates/0000-best-practice-template.md @@ -11,7 +11,7 @@ ## Overview -🟢 - lead sentence details the core of what the good practice is. The overview in general should be concise and to the point. +🟢 - Summarize the core guidance in a lead sentence. Keep the overview concise and to the point. Extend the overview with an additional paragraph providing more background if needed, preferring to link to external specifications, documentation, etc as needed instead of providing it inline. @@ -27,7 +27,7 @@ Extend the overview with an additional paragraph providing more background if ne Provide a clear, complete, ideally "real" example of the best practice. If describing an API pattern, show both the implementation side and "call site" usage to illustrate it. -If there's supporting tasks for the best practice, include the specifics of how to enable them in further H3 sections. Write The H3 section headings as imperative verb phrases that describe what the example is showing and what you should do for the best practice. +If there's supporting tasks for the best practice, include the specifics of how to enable them in further H3 sections. Write the H3 section headings as imperative verb phrases that describe what the example shows and what to do for the best practice. ## Alternatives Considered