From 9f79061ac629c0f274abdc948a3614e1fb249978 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:03:30 -0700 Subject: [PATCH 1/9] adding explicit migration plans --- .../0003-swift-docs-proposal.md | 118 ++++++++---------- 1 file changed, 53 insertions(+), 65 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index bdf10f682..6fbd6064b 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -119,11 +119,9 @@ From a mechanical perspective, reviewers are listed in a `CODEOWNERS` file, whic For example, the structure of the catalogs above might line up to: ``` -/APIGuides.docc/* @swiftlang/language-steering-group -/ServerGuides.docc/* @swiftlang/server-workgroup -/InteropGuides.docc/* @swiftlang/cxx-interop-workgroup -/SwiftLangGuides.docc/* @swiftlang/language-steering-group -/ToolGuides.docc/* @swiftlang/platform-steering-group +/api-guidelines/* @swiftlang/language-steering-group +/ecosystem/* @swiftlang/ecosystem-steering-group +/server-guides/* @swiftlang/server-workgroup ``` If a group dissolves, any catalogs can be associated with another group, or revert to control by the Swift Core Team. @@ -166,6 +164,13 @@ Like the Swift Embedded examples repository, it benefits from close proximity be ### Migrating Jekyll to DocC content in the Swift Docs Repository Based on the existing content in Swift.org, the general goal is to migrate the majority of what is general documentation content into a DocC format, grouped into the collections below. + +All of the listed markdown files would remain in `/documentation`, with their front matter (Jekyll metadata) updated to redirect the URL requests to the new locations as content is migrated and accepted into the new docs repository. +Markdown files prefixed with `_` are typically only included in other files and not referenced by URL, and can be removed after they are migrated. + +#### Disposition Plan for files under `documentation` + + A few exceptions are detailed after the file names, to accommodate very out-of-date content, or content that's already replicated in other locations. This proposal is primarily meant to provide a guide to the structure for content as we want to see it, @@ -176,66 +181,51 @@ A full audit of the documentation for recency and relevancy is worthwhile, but b The notes of this migration are intended to be guides, and any migration process isn't expected to be done immediately and in one sweep. The migration can, and should, occur incrementally, building into the docs repository as supported by the community including content reviewers and their availability. -All of the listed markdown files would remain in `/documentation`, with their front matter (Jekyll metadata) updated to redirect the URL requests to the new locations as content is migrated and accepted into the new docs repository. -Markdown files prefixed with `_` are typically only included in other files and not referenced by URL, and can be removed after they are migrated. - -- API guidelines - - - documentation/api-design-guidelines/index.md - -- Server guides +`source` | status & destination +- | - | - +`api-design-guidelines/index.md` | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` + +`server/index.md` | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ +`server/guides/index.md` | translate, migrate to top level of `server-guides/ServerGuides.docc` +`server/guides/building.md` | +`server/guides/testing.md` | +`server/guides/memory-leaks-and-usage.md` | +`server/guides/allocations.md` | +`server/guides/linux-perf.md` | +`server/guides/performance.md` | +`server/guides/llvm-sanitizers.md` | +`server/guides/deployment.md` | +`server/guides/packaging.md` | +`server/guides/passkeys.md` | +`server/guides/libraries/log-levels.md` | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) +`server/guides/libraries/concurrency-adoption-guidelines.md`: deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) +`server/guides/deploying/aws-sam-lambda.md` | +`server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | +`server/guides/deploying/aws.md` | +`server/guides/deploying/digital-ocean.md` | +`server/guides/deploying/ubuntu.md` | +`server/guides/deploying/heroku.md` | +`server/guides/deploying/gcp.md` | +`articles/static-linux-getting-started.md` | + +`migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift3/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift4/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift4/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift4.2/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift4.2/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift5/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`migration-guide-swift5/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide +`concurrency/index.md` | redirect to content at https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety + +`documentation/articles/zero-to-swift-nvim.md` | migrate into `ecosystem/EcosystemTools.docc` +`documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` +`documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` +`articles/wasm-getting-started.md` | translate and migrate into `ecosystem - - documentation/server/index.md - - documentation/server/guides/index.md - - documentation/server/guides/building.md - - documentation/server/guides/testing.md - - documentation/server/guides/memory-leaks-and-usage.md - - documentation/server/guides/allocations.md - - documentation/server/guides/linux-perf.md - - documentation/server/guides/performance.md - - - documentation/server/guides/llvm-sanitizers.md - - documentation/server/guides/deployment.md - - documentation/server/guides/packaging.md - - documentation/server/guides/passkeys.md - - - documentation/server/guides/libraries/log-levels.md: migrate content into swift-log - - documentation/server/guides/libraries/concurrency-adoption-guidelines.md: remove content & redirect link to existing migration guide - - - documentation/server/guides/deploying/aws-sam-lambda.md - - documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.md - - documentation/server/guides/deploying/aws.md - - documentation/server/guides/deploying/digital-ocean.md - - documentation/server/guides/deploying/ubuntu.md - - documentation/server/guides/deploying/heroku.md - - documentation/server/guides/deploying/gcp.md - - documentation/articles/static-linux-getting-started.md - -- Swift Language Guides - - - migrate all of these pieces into https://github.com/swiftlang/swift-migration-guide - - documentation/articles/value-and-reference-types.md - - migration-guide-swift3/_migration-guide.md - - migration-guide-swift3/se-0107-migrate.md - - migration-guide-swift3/index.md - - migration-guide-swift4/_migration-guide.md - - migration-guide-swift4/index.md - - migration-guide-swift4.2/_migration-guide.md - - migration-guide-swift4.2/index.md - - migration-guide-swift5/_migration-guide.md - - migration-guide-swift5/index.md - - documentation/concurrency/index.md (redirect only, its content is effectively already there) - -- Tool Guides - - - documentation/articles/zero-to-swift-nvim.md - - documentation/articles/zero-to-swift-emacs.md - - documentation/articles/getting-started-with-vscode-swift.md - -- WASM - - - documentation/articles/wasm-getting-started.md +### Swift.org documentation files & directories remaining: - C/C++ Interop Guides - Doug Gregor has indicated a desire to reset and migrate this content into the Swift repository, leveraging code validation that is beyond Swift's Documentation tooling today, and to keep it closely aligned with the relvant code that provides the interop functionality. @@ -245,8 +235,6 @@ Markdown files prefixed with `_` are typically only included in other files and - documentation/cxx-interop/status/index.md - documentation/articles/wrapping-c-cpp-library-in-swift.md -### Swift.org documentation files & directories remaining: - - Remain on swift.org - documentation/core-libraries/index.md - documentation/core-libraries/_foundation.md From d90efb5299db70996236004a8f40c1cfcea4a023 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:08:43 -0700 Subject: [PATCH 2/9] table format --- .../0003-swift-docs-proposal.md | 81 +++++++++---------- 1 file changed, 39 insertions(+), 42 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index 6fbd6064b..3e1a5512f 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -181,48 +181,45 @@ A full audit of the documentation for recency and relevancy is worthwhile, but b The notes of this migration are intended to be guides, and any migration process isn't expected to be done immediately and in one sweep. The migration can, and should, occur incrementally, building into the docs repository as supported by the community including content reviewers and their availability. -`source` | status & destination -- | - | - -`api-design-guidelines/index.md` | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` - -`server/index.md` | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ -`server/guides/index.md` | translate, migrate to top level of `server-guides/ServerGuides.docc` -`server/guides/building.md` | -`server/guides/testing.md` | -`server/guides/memory-leaks-and-usage.md` | -`server/guides/allocations.md` | -`server/guides/linux-perf.md` | -`server/guides/performance.md` | -`server/guides/llvm-sanitizers.md` | -`server/guides/deployment.md` | -`server/guides/packaging.md` | -`server/guides/passkeys.md` | -`server/guides/libraries/log-levels.md` | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) -`server/guides/libraries/concurrency-adoption-guidelines.md`: deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) -`server/guides/deploying/aws-sam-lambda.md` | -`server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | -`server/guides/deploying/aws.md` | -`server/guides/deploying/digital-ocean.md` | -`server/guides/deploying/ubuntu.md` | -`server/guides/deploying/heroku.md` | -`server/guides/deploying/gcp.md` | -`articles/static-linux-getting-started.md` | - -`migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift3/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift4/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift4/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift4.2/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift4.2/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift5/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`migration-guide-swift5/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide -`concurrency/index.md` | redirect to content at https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety - -`documentation/articles/zero-to-swift-nvim.md` | migrate into `ecosystem/EcosystemTools.docc` -`documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` -`documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` -`articles/wasm-getting-started.md` | translate and migrate into `ecosystem +| `source` | status & destination | +| - | - | +| `api-design-guidelines/index.md` | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` | +| `server/index.md` | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ | +| `server/guides/index.md` | translate, migrate to top level of `server-guides/ServerGuides.docc` | +| `server/guides/building.md` | | +| `server/guides/testing.md` | | +| `server/guides/memory-leaks-and-usage.md` | | +| `server/guides/allocations.md` | | +| `server/guides/linux-perf.md` | | +| `server/guides/performance.md` | | +| `server/guides/llvm-sanitizers.md` | | +| `server/guides/deployment.md` | | +| `server/guides/packaging.md` | | +| `server/guides/passkeys.md` | | +| `server/guides/libraries/log-levels.md` | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) | +| `server/guides/libraries/concurrency-adoption-guidelines.md` | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) | +| `server/guides/deploying/aws-sam-lambda.md` | | +| `server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | | +| `server/guides/deploying/aws.md` | | +| `server/guides/deploying/digital-ocean.md` | | +| `server/guides/deploying/ubuntu.md` | | +| `server/guides/deploying/heroku.md` | | +| `server/guides/deploying/gcp.md` | | +| `articles/static-linux-getting-started.md` | | +| `migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift3/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift4/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift4/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift4.2/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift4.2/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift5/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `migration-guide-swift5/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| `concurrency/index.md` | redirect to content at https://www.swift.org/migration/documentation/| |swift-6-concurrency-migration-guide/enabledataracesafety | +| `documentation/articles/zero-to-swift-nvim.md` | migrate into `ecosystem/EcosystemTools.docc` | +| `documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` | +| `documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` | +| `articles/wasm-getting-started.md` | translate and migrate into `ecosystem | ### Swift.org documentation files & directories remaining: From 27207780022d4313b1a9f341d27e6b9e28eb3471 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:15:58 -0700 Subject: [PATCH 3/9] incremental add --- .../0003-swift-docs-proposal.md | 46 ++++++------------- 1 file changed, 15 insertions(+), 31 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index 3e1a5512f..aa6bed79f 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -220,49 +220,33 @@ The migration can, and should, occur incrementally, building into the docs repos | `documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` | | `documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` | | `articles/wasm-getting-started.md` | translate and migrate into `ecosystem | - +| `continuous-integration/index.md` | migrate content to github.com/swiftlang/project-operations repository | +| `source-compatibility/index.md` | migrate to github.com/swiftlang/project-operations repository (referencess to swift source compatibility project) | +| `source-code/index.md` | migrate to github.com/swiftlang/project-operations repository (partial list to existing source code that goes into toolchain, needs updating if kept) | ### Swift.org documentation files & directories remaining: -- C/C++ Interop Guides - - Doug Gregor has indicated a desire to reset and migrate this content into the Swift repository, leveraging code validation that is beyond Swift's Documentation tooling today, and to keep it closely aligned with the relvant code that provides the interop functionality. - - documentation/cxx-interop/index.md +- Remain on swift.org + - documentation/cxx-interop/index.md (Doug Gregor has indicated a desire to reset and migrate this content into the Swift repository) - documentation/cxx-interop/safe-interop/index.md - documentation/cxx-interop/project-build-setup/index.md - documentation/cxx-interop/status/index.md - documentation/articles/wrapping-c-cpp-library-in-swift.md - -- Remain on swift.org - documentation/core-libraries/index.md - documentation/core-libraries/_foundation.md - documentation/core-libraries/_libdispatch.md - documentation/core-libraries/_swift-testing.md - documentation/core-libraries/_xctest.md - -- documentation/package-manager/index.md - (currently redirects to https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/) - -- documentation/articles/value-and-reference-types.md - -- documentation/tspl/index.md (stays as is, references into TSPL and links to translations) - -- documentation/lldb/index.md: migrate to github.com/swiftlang/swift:`userdocs/` - - documentation/lldb/_playground-support.md - -- documentation/swift-compiler/index.md: migrate to github.com/swiftlang/swift:`userdocs/` - - documentation/swift-compiler/_compiler-architecture.md - -- documentation/standard-library/index.md - - documentation/standard-library/_preview-package.md - - documentation/standard-library/_stdlib-design.md - -- documentation/source-compatibility/index.md: migrate to github.com/swiftlang/project-operations repository - (referencess to swift source compatibility project) - -- documentation/source-code/index.md: migrate to github.com/swiftlang/project-operations repository - (partial list to existing source code that goes into toolchain, needs updating if kept) - -- documentation/continuous-integration/index.md: migrate to github.com/swiftlang/project-operations repository + - documentation/package-manager/index.md (currently redirects to https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/) + - documentation/articles/value-and-reference-types.md + - documentation/tspl/index.md + - documentation/lldb/index.md + - documentation/lldb/_playground-support.md + - documentation/swift-compiler/index.md + - documentation/swift-compiler/_compiler-architecture.md + - documentation/standard-library/index.md + - documentation/standard-library/_preview-package.md + - documentation/standard-library/_stdlib-design.md ## Alternatives Considered From 77822b0ae04c1512700a7afeb3add82baad311c6 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:18:17 -0700 Subject: [PATCH 4/9] updating tree example --- .../0003-swift-docs-proposal.md | 34 ++++++++++--------- 1 file changed, 18 insertions(+), 16 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index aa6bed79f..39fb25947 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -85,25 +85,27 @@ but don't reflect all the possible future content we might create. An example `tree` view of such a repository: ``` -├── APIGuidelines -│   └── APIGuideliness.docc +├── api-guidelines +│   └── APIGuidelines.docc +│   ├── DocComment.md │   ├── Documentation.md -│   ├── ... +│   ├── include-words-to-avoid-ambiguity.md +│   ├── name-according-to-roles.md +│   ├── omit-needless-words.md +│   └── weak-type-information.md ├── CODEOWNERS -├── README.md -├── Server -│   └── ServerGuides.docc -│   └── Documentation.md -├── SwiftLangGuides -│   └── SwiftLangGuides.docc +├── ecosystem +│   ├── EcosystemTools.docc +│   │   ├── Documentation.md +│   │   ├── getting-started-with-vscode-swift.md +│   │   ├── zero-to-swift-emacs.md +│   │   └── zero-to-swift-nvim.md +│   └── WASM.docc │   └── Documentation.md -│ ├── ... -├── Tools -│ └── ToolsAndEditors.docc -│ ├── Documentation.md -│ ├── ... -└── WASM -    └── WASM.docc +├── README.md +└── server-guides + └── ServerGuides.docc + └── Documentation.md ``` The directories for each catalog residing at the root can host another DocC catalog (a directory ending with .docc), to host the markdown content in a typical DocC fashion. From 6f61462a5ec9b99d8eb1a4d80d06b2b960132d3a Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:31:01 -0700 Subject: [PATCH 5/9] initial assessment swag --- .../0003-swift-docs-proposal.md | 49 +++++++++---------- 1 file changed, 24 insertions(+), 25 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index 39fb25947..1c13eede3 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -78,9 +78,8 @@ but don't reflect all the possible future content we might create. - API guidelines - moderated/reviewed by the Language Steering Group. - Server guides - moderated/reviewed by the SSWG. - - Swift Migration guides - moderated by lang/platforms. - - Tools Guides - moderated/reviewed by platform & ecosystem. - - WASM - moderated/reviewed by platform steering group. + - Ecosystem Tools Guides - moderated/reviewed by ecosystem steering group. + - WASM - moderated/reviewed by ecosystem steering group. An example `tree` view of such a repository: @@ -188,26 +187,26 @@ The migration can, and should, occur incrementally, building into the docs repos | `api-design-guidelines/index.md` | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` | | `server/index.md` | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ | | `server/guides/index.md` | translate, migrate to top level of `server-guides/ServerGuides.docc` | -| `server/guides/building.md` | | -| `server/guides/testing.md` | | -| `server/guides/memory-leaks-and-usage.md` | | -| `server/guides/allocations.md` | | -| `server/guides/linux-perf.md` | | -| `server/guides/performance.md` | | -| `server/guides/llvm-sanitizers.md` | | -| `server/guides/deployment.md` | | -| `server/guides/packaging.md` | | -| `server/guides/passkeys.md` | | +| `server/guides/building.md` | update to swift 6 references, but otherwise migrate as is | +| `server/guides/testing.md` | update to swift 6 references, but otherwise migrate as is | +| `server/guides/memory-leaks-and-usage.md` | migrate as is | +| `server/guides/allocations.md` | migrate as is, add reference to package-benchmark to help measure allocations | +| `server/guides/linux-perf.md` | migrate as is, add reference to swift-performance-profiler, package-benchmark | +| `server/guides/performance.md` | revise to reference swift-performance-profiler, package-benchmark | +| `server/guides/llvm-sanitizers.md` | migrate as is | +| `server/guides/packaging.md` | update content - reference Container & swift-container-plugin | +| `server/guides/passkeys.md` | migrate content into article within https://github.com/swift-server/webauthn-swift.git | | `server/guides/libraries/log-levels.md` | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) | | `server/guides/libraries/concurrency-adoption-guidelines.md` | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) | -| `server/guides/deploying/aws-sam-lambda.md` | | -| `server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | | -| `server/guides/deploying/aws.md` | | -| `server/guides/deploying/digital-ocean.md` | | -| `server/guides/deploying/ubuntu.md` | | -| `server/guides/deploying/heroku.md` | | -| `server/guides/deploying/gcp.md` | | -| `articles/static-linux-getting-started.md` | | +| `server/guides/deployment.md` | migrate as is - guide to deploying | +| `server/guides/deploying/aws-sam-lambda.md` | migrate as is - slightly outdated | +| `server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | migrate as is - slightly outdated | +| `server/guides/deploying/aws.md` | migrate as is - slightly outdated | +| `server/guides/deploying/digital-ocean.md` | migrate as is - slightly outdated | +| `server/guides/deploying/ubuntu.md` | migrate as is - slightly outdated | +| `server/guides/deploying/heroku.md` | migrate as is - slightly outdated| +| `server/guides/deploying/gcp.md` | migrate as is - slightly outdated | +| `articles/static-linux-getting-started.md` | migrate as is | | `migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift3/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | @@ -221,10 +220,10 @@ The migration can, and should, occur incrementally, building into the docs repos | `documentation/articles/zero-to-swift-nvim.md` | migrate into `ecosystem/EcosystemTools.docc` | | `documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` | | `documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` | -| `articles/wasm-getting-started.md` | translate and migrate into `ecosystem | -| `continuous-integration/index.md` | migrate content to github.com/swiftlang/project-operations repository | -| `source-compatibility/index.md` | migrate to github.com/swiftlang/project-operations repository (referencess to swift source compatibility project) | -| `source-code/index.md` | migrate to github.com/swiftlang/project-operations repository (partial list to existing source code that goes into toolchain, needs updating if kept) | +| `articles/wasm-getting-started.md` | translate and migrate into `ecosystem/WASM.docc` | +| `continuous-integration/index.md` | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository | +| `source-compatibility/index.md` | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) | +| `source-code/index.md` | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) | ### Swift.org documentation files & directories remaining: From 7f7c95fc5296831e8b44e652c8509501c09eb94a Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:44:06 -0700 Subject: [PATCH 6/9] adding source links --- .../0003-swift-docs-proposal.md | 70 +++++++++---------- 1 file changed, 35 insertions(+), 35 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index 1c13eede3..c62864f73 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -184,46 +184,46 @@ The migration can, and should, occur incrementally, building into the docs repos | `source` | status & destination | | - | - | -| `api-design-guidelines/index.md` | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` | -| `server/index.md` | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ | -| `server/guides/index.md` | translate, migrate to top level of `server-guides/ServerGuides.docc` | -| `server/guides/building.md` | update to swift 6 references, but otherwise migrate as is | -| `server/guides/testing.md` | update to swift 6 references, but otherwise migrate as is | -| `server/guides/memory-leaks-and-usage.md` | migrate as is | -| `server/guides/allocations.md` | migrate as is, add reference to package-benchmark to help measure allocations | -| `server/guides/linux-perf.md` | migrate as is, add reference to swift-performance-profiler, package-benchmark | -| `server/guides/performance.md` | revise to reference swift-performance-profiler, package-benchmark | -| `server/guides/llvm-sanitizers.md` | migrate as is | -| `server/guides/packaging.md` | update content - reference Container & swift-container-plugin | -| `server/guides/passkeys.md` | migrate content into article within https://github.com/swift-server/webauthn-swift.git | -| `server/guides/libraries/log-levels.md` | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) | -| `server/guides/libraries/concurrency-adoption-guidelines.md` | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) | -| `server/guides/deployment.md` | migrate as is - guide to deploying | -| `server/guides/deploying/aws-sam-lambda.md` | migrate as is - slightly outdated | -| `server/guides/deploying/aws-copilot-fargate-vapor-mongo.md` | migrate as is - slightly outdated | -| `server/guides/deploying/aws.md` | migrate as is - slightly outdated | -| `server/guides/deploying/digital-ocean.md` | migrate as is - slightly outdated | -| `server/guides/deploying/ubuntu.md` | migrate as is - slightly outdated | -| `server/guides/deploying/heroku.md` | migrate as is - slightly outdated| -| `server/guides/deploying/gcp.md` | migrate as is - slightly outdated | -| `articles/static-linux-getting-started.md` | migrate as is | +| [`api-design-guidelines/index.md`](https://www.swift.org/documentation/api-design-guidelines/) | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` | +| [`server/index.md`](https://www.swift.org/documentation/server/index.html) | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ | +| [`server/guides/index.md`](https://www.swift.org/documentation/server/guides/index.html) | translate, migrate to top level of `server-guides/ServerGuides.docc` | +| [`server/guides/building.md`](https://www.swift.org/documentation/server/guides/building.html) | update to swift 6 references, but otherwise migrate as is | +| [`server/guides/testing.md`](https://www.swift.org/documentation/server/guides/testing.html) | update to swift 6 references, but otherwise migrate as is | +| [`server/guides/memory-leaks-and-usage.md`](https://www.swift.org/documentation/server/guides/memory-leaks-and-usage.html) | migrate as is | +| [`server/guides/allocations.md`](https://www.swift.org/documentation/server/guides/allocations.html) | migrate as is, add reference to package-benchmark to help measure allocations | +| [`server/guides/linux-perf.md`](https://www.swift.org/documentation/server/guides/linux-perf.html) | migrate as is, add reference to swift-performance-profiler, package-benchmark | +| [`server/guides/performance.md`](https://www.swift.org/documentation/server/guides/performance.html) | revise to reference swift-performance-profiler, package-benchmark | +| [`server/guides/llvm-sanitizers.md`](https://www.swift.org/documentation/server/guides/llvm-sanitizers.html) | migrate as is | +| [`server/guides/packaging.md`](https://www.swift.org/documentation/server/guides/packaging.html) | update content - reference Container & swift-container-plugin | +| [`server/guides/passkeys.md`](https://www.swift.org/documentation/server/guides/passkeys.html) | migrate content into article within https://github.com/swift-server/webauthn-swift.git | +| [`server/guides/libraries/log-levels.md`](https://www.swift.org/documentation/server/guides/libraries/log-levels.html) | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) | +| [`server/guides/libraries/concurrency-adoption-guidelines.md`](https://www.swift.org/documentation/server/guides/libraries/concurrency-adoption-guidelines.html) | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) | +| [`server/guides/deployment.md`](https://www.swift.org/documentation/server/guides/deployment.html) | migrate as is - guide to deploying | +| [`server/guides/deploying/aws-sam-lambda.md`](https://www.swift.org/documentation/server/guides/deploying/aws-sam-lambda.html) | migrate as is - slightly outdated | +| [`server/guides/deploying/aws-copilot-fargate-vapor-mongo.md`](https://www.swift.org/documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.html) | migrate as is - slightly outdated | +| [`server/guides/deploying/aws.md`](https://www.swift.org/documentation/server/guides/deploying/aws.html) | migrate as is - slightly outdated | +| [`server/guides/deploying/digital-ocean.md`](https://www.swift.org/documentation/server/guides/deploying/digital-ocean.html) | migrate as is - slightly outdated | +| [`server/guides/deploying/ubuntu.md`](https://www.swift.org/documentation/server/guides/deploying/ubuntu.html) | migrate as is - slightly outdated | +| [`server/guides/deploying/heroku.md`](https://www.swift.org/documentation/server/guides/deploying/heroku.html) | migrate as is - slightly outdated| +| [`server/guides/deploying/gcp.md`](https://www.swift.org/documentation/server/guides/deploying/gcp.html) | migrate as is - slightly outdated | +| [`articles/static-linux-getting-started.md`](https://www.swift.org/documentation/articles/static-linux-getting-started.html) | migrate as is | | `migration-guide-swift3/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift3/se-0107-migrate.md` | migrate into https://github.com/swiftlang/swift-migration-guide | -| `migration-guide-swift3/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| [`migration-guide-swift3/index.md`](https://www.swift.org/migration-guide-swift3/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift4/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | -| `migration-guide-swift4/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| [`migration-guide-swift4/index.md`](https://www.swift.org/migration-guide-swift4/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift4.2/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | -| `migration-guide-swift4.2/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | +| [`migration-guide-swift4.2/index.md`](https://www.swift.org/migration-guide-swift4.2/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide | | `migration-guide-swift5/_migration-guide.md` | migrate into https://github.com/swiftlang/swift-migration-guide | -| `migration-guide-swift5/index.md` | migrate into https://github.com/swiftlang/swift-migration-guide | -| `concurrency/index.md` | redirect to content at https://www.swift.org/migration/documentation/| |swift-6-concurrency-migration-guide/enabledataracesafety | -| `documentation/articles/zero-to-swift-nvim.md` | migrate into `ecosystem/EcosystemTools.docc` | -| `documentation/articles/zero-to-swift-emacs.md` | migrate into `ecosystem/EcosystemTools.docc` | -| `documentation/articles/getting-started-with-vscode-swift.md` | migrate into `ecosystem/EcosystemTools.docc` | -| `articles/wasm-getting-started.md` | translate and migrate into `ecosystem/WASM.docc` | -| `continuous-integration/index.md` | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository | -| `source-compatibility/index.md` | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) | -| `source-code/index.md` | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) | +| [`migration-guide-swift5/index.md`](https://www.swift.org/migration-guide-swift5/index.html) | migrate into https://github.com/swiftlang/swift-migration-guide | +| [`concurrency/index.md`](https://www.swift.org/documentation/concurrency/index.html) | redirect to content at https://www.swift.org/migration/documentation/| |swift-6-concurrency-migration-guide/enabledataracesafety | +| [`articles/zero-to-swift-nvim.md`](https://www.swift.org/documentation/articles/zero-to-swift-nvim.html) | migrate into `ecosystem/EcosystemTools.docc` | +| [`articles/zero-to-swift-emacs.md`](https://www.swift.org/documentation/articles/zero-to-swift-emacs.html) | migrate into `ecosystem/EcosystemTools.docc` | +| [`articles/getting-started-with-vscode-swift.md`](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html) | migrate into `ecosystem/EcosystemTools.docc` | +| [`articles/wasm-getting-started.md`](https://www.swift.org/documentation/articles/wasm-getting-started.html) | translate and migrate into `ecosystem/WASM.docc` | +| [continuous-integration/index.md`](https://www.swift.org/documentation/continuous-integration/index.html) | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository | +| [`source-compatibility/index.md`](https://www.swift.org/documentation/source-compatibility/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) | +| [`source-code/index.md`](https://www.swift.org/documentation/source-code/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) | ### Swift.org documentation files & directories remaining: From c46e0b19e26b0814e3f546feb22fbecd60669825 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 13:52:46 -0700 Subject: [PATCH 7/9] fixing link, changing header --- _info-architecture/0003-swift-docs-proposal.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index c62864f73..c4e03a0df 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -169,8 +169,7 @@ Based on the existing content in Swift.org, the general goal is to migrate the m All of the listed markdown files would remain in `/documentation`, with their front matter (Jekyll metadata) updated to redirect the URL requests to the new locations as content is migrated and accepted into the new docs repository. Markdown files prefixed with `_` are typically only included in other files and not referenced by URL, and can be removed after they are migrated. -#### Disposition Plan for files under `documentation` - +## Migration Plan for files under `documentation` A few exceptions are detailed after the file names, to accommodate very out-of-date content, or content that's already replicated in other locations. @@ -221,7 +220,7 @@ The migration can, and should, occur incrementally, building into the docs repos | [`articles/zero-to-swift-emacs.md`](https://www.swift.org/documentation/articles/zero-to-swift-emacs.html) | migrate into `ecosystem/EcosystemTools.docc` | | [`articles/getting-started-with-vscode-swift.md`](https://www.swift.org/documentation/articles/getting-started-with-vscode-swift.html) | migrate into `ecosystem/EcosystemTools.docc` | | [`articles/wasm-getting-started.md`](https://www.swift.org/documentation/articles/wasm-getting-started.html) | translate and migrate into `ecosystem/WASM.docc` | -| [continuous-integration/index.md`](https://www.swift.org/documentation/continuous-integration/index.html) | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository | +| [`continuous-integration/index.md`](https://www.swift.org/documentation/continuous-integration/index.html) | migrate content to [project-operations](https://github.com/swiftlang/project-operations) repository | | [`source-compatibility/index.md`](https://www.swift.org/documentation/source-compatibility/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) | | [`source-code/index.md`](https://www.swift.org/documentation/source-code/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) | From 59201ad000727c473ddca0d7dc09b8e1874f1e70 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Mon, 13 Oct 2025 14:01:27 -0700 Subject: [PATCH 8/9] tweaks --- .../0003-swift-docs-proposal.md | 59 +++++++++---------- 1 file changed, 29 insertions(+), 30 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index c4e03a0df..f38361c1d 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -169,17 +169,17 @@ Based on the existing content in Swift.org, the general goal is to migrate the m All of the listed markdown files would remain in `/documentation`, with their front matter (Jekyll metadata) updated to redirect the URL requests to the new locations as content is migrated and accepted into the new docs repository. Markdown files prefixed with `_` are typically only included in other files and not referenced by URL, and can be removed after they are migrated. -## Migration Plan for files under `documentation` +## Migration Plan -A few exceptions are detailed after the file names, to accommodate very out-of-date content, or content that's already replicated in other locations. - -This proposal is primarily meant to provide a guide to the structure for content as we want to see it, -and isn't meant to provide a full and discrete audit of all existing content. -Nevertheless, a few examples stand out and have been discussed previously within the community as needing updates, or removal and relevant links redirected to more up-to-date and recent content. +This proposal is primarily meant to provide a guide to the structure for content as we want to see it. +In the process of establishing this new repository and structure of DocC catalogs, the following files from swift.org are intended to be migrated. A full audit of the documentation for recency and relevancy is worthwhile, but beyond the scope of this proposal. -The notes of this migration are intended to be guides, and any migration process isn't expected to be done immediately and in one sweep. +This list is intended to be a guide, with additional potential updates from the relevant reviewing team, and is not expected to be complete in a single sweep. The migration can, and should, occur incrementally, building into the docs repository as supported by the community including content reviewers and their availability. +The migration process itself will be tracked by pull requests and within an issue or issues housed at https://github.com/swiftlang/swift-org-website/, with the issues and tracking to be started if the proposal is approved. + +Files under the `documentation` directory on Swift.org: | `source` | status & destination | | - | - | @@ -224,29 +224,28 @@ The migration can, and should, occur incrementally, building into the docs repos | [`source-compatibility/index.md`](https://www.swift.org/documentation/source-compatibility/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (referencess to swift source compatibility project) | | [`source-code/index.md`](https://www.swift.org/documentation/source-code/index.html) | migrate to [project-operations](https://github.com/swiftlang/project-operations) repository (partial list to existing source code that goes into toolchain, needs updating if kept) | -### Swift.org documentation files & directories remaining: - -- Remain on swift.org - - documentation/cxx-interop/index.md (Doug Gregor has indicated a desire to reset and migrate this content into the Swift repository) - - documentation/cxx-interop/safe-interop/index.md - - documentation/cxx-interop/project-build-setup/index.md - - documentation/cxx-interop/status/index.md - - documentation/articles/wrapping-c-cpp-library-in-swift.md - - documentation/core-libraries/index.md - - documentation/core-libraries/_foundation.md - - documentation/core-libraries/_libdispatch.md - - documentation/core-libraries/_swift-testing.md - - documentation/core-libraries/_xctest.md - - documentation/package-manager/index.md (currently redirects to https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/) - - documentation/articles/value-and-reference-types.md - - documentation/tspl/index.md - - documentation/lldb/index.md - - documentation/lldb/_playground-support.md - - documentation/swift-compiler/index.md - - documentation/swift-compiler/_compiler-architecture.md - - documentation/standard-library/index.md - - documentation/standard-library/_preview-package.md - - documentation/standard-library/_stdlib-design.md +### Swift.org documentation remaining and untouched: + +- documentation/cxx-interop/index.md (Doug Gregor indicated a desire to reset and migrate this content into the Swift repository in the future) +- documentation/cxx-interop/safe-interop/index.md +- documentation/cxx-interop/project-build-setup/index.md +- documentation/cxx-interop/status/index.md +- documentation/articles/wrapping-c-cpp-library-in-swift.md +- documentation/core-libraries/index.md + - documentation/core-libraries/_foundation.md + - documentation/core-libraries/_libdispatch.md + - documentation/core-libraries/_swift-testing.md + - documentation/core-libraries/_xctest.md +- documentation/package-manager/index.md (currently redirects to https://docs.swift.org/swiftpm/documentation/packagemanagerdocs/) +- documentation/articles/value-and-reference-types.md +- documentation/tspl/index.md +- documentation/lldb/index.md + - documentation/lldb/_playground-support.md +- documentation/swift-compiler/index.md + - documentation/swift-compiler/_compiler-architecture.md +- documentation/standard-library/index.md + - documentation/standard-library/_preview-package.md + - documentation/standard-library/_stdlib-design.md ## Alternatives Considered From 0304b1ca963c65e0fdfa9f7deea3b470d0d0d234 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 17 Oct 2025 13:05:06 -0700 Subject: [PATCH 9/9] revised based on deeper review --- _info-architecture/0003-swift-docs-proposal.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/_info-architecture/0003-swift-docs-proposal.md b/_info-architecture/0003-swift-docs-proposal.md index f38361c1d..d5307f7a3 100644 --- a/_info-architecture/0003-swift-docs-proposal.md +++ b/_info-architecture/0003-swift-docs-proposal.md @@ -186,18 +186,18 @@ Files under the `documentation` directory on Swift.org: | [`api-design-guidelines/index.md`](https://www.swift.org/documentation/api-design-guidelines/) | translate to docc, break into multiple articles in `api-guidelines/APIGuidelines.docc` | | [`server/index.md`](https://www.swift.org/documentation/server/index.html) | deprecate & redirect to https://www.swift.org/get-started/cloud-services/ | | [`server/guides/index.md`](https://www.swift.org/documentation/server/guides/index.html) | translate, migrate to top level of `server-guides/ServerGuides.docc` | -| [`server/guides/building.md`](https://www.swift.org/documentation/server/guides/building.html) | update to swift 6 references, but otherwise migrate as is | -| [`server/guides/testing.md`](https://www.swift.org/documentation/server/guides/testing.html) | update to swift 6 references, but otherwise migrate as is | +| [`server/guides/building.md`](https://www.swift.org/documentation/server/guides/building.html) | refine/update to provide examples of building, add section for debug vs. release and swift tooling, link to SwiftPM docs on building, add section about building in Linux using containers, add section on building with devContainers, add detail on static linux SDK, break out some content to a CI related article | +| [`server/guides/testing.md`](https://www.swift.org/documentation/server/guides/testing.html) | heavily outdated - update to swift 6, swift-testing, break out some content into a "CI" focused article - focus on unit testing, leave room for functional, integration testing as sep articles | | [`server/guides/memory-leaks-and-usage.md`](https://www.swift.org/documentation/server/guides/memory-leaks-and-usage.html) | migrate as is | | [`server/guides/allocations.md`](https://www.swift.org/documentation/server/guides/allocations.html) | migrate as is, add reference to package-benchmark to help measure allocations | -| [`server/guides/linux-perf.md`](https://www.swift.org/documentation/server/guides/linux-perf.html) | migrate as is, add reference to swift-performance-profiler, package-benchmark | -| [`server/guides/performance.md`](https://www.swift.org/documentation/server/guides/performance.html) | revise to reference swift-performance-profiler, package-benchmark | -| [`server/guides/llvm-sanitizers.md`](https://www.swift.org/documentation/server/guides/llvm-sanitizers.html) | migrate as is | -| [`server/guides/packaging.md`](https://www.swift.org/documentation/server/guides/packaging.html) | update content - reference Container & swift-container-plugin | +| [`server/guides/linux-perf.md`](https://www.swift.org/documentation/server/guides/linux-perf.html) | migrate as is, update examples to use container and latest versions, break out a separate flame-graph article | +| [`server/guides/performance.md`](https://www.swift.org/documentation/server/guides/performance.html) | revise to guidepints for understand performance, reference swift-performance-profiler, package-benchmark, break out flamegraph (what they are, how to read) into it's own article - include perf profiler flamegraphs tool references | +| [`server/guides/llvm-sanitizers.md`](https://www.swift.org/documentation/server/guides/llvm-sanitizers.html) | merge content into 'build' and 'test' articles, deprecate/remove | +| [`server/guides/packaging.md`](https://www.swift.org/documentation/server/guides/packaging.html) | add new overview of options, incl static-binary, container. reference runtime dependencies with static compilation options, example of docker w/ 2-stage build and using published docker binaries, break out distroless into it's own article | | [`server/guides/passkeys.md`](https://www.swift.org/documentation/server/guides/passkeys.html) | migrate content into article within https://github.com/swift-server/webauthn-swift.git | | [`server/guides/libraries/log-levels.md`](https://www.swift.org/documentation/server/guides/libraries/log-levels.html) | migrate content into swift-log (https://github.com/apple/swift-log/pull/370) | | [`server/guides/libraries/concurrency-adoption-guidelines.md`](https://www.swift.org/documentation/server/guides/libraries/concurrency-adoption-guidelines.html) | deprecate and redirect to https://www.swift.org/migration/documentation/swift-6-concurrency-migration-guide/enabledataracesafety (https://github.com/swiftlang/swift-org-website/pull/1186) | -| [`server/guides/deployment.md`](https://www.swift.org/documentation/server/guides/deployment.html) | migrate as is - guide to deploying | +| [`server/guides/deployment.md`](https://www.swift.org/documentation/server/guides/deployment.html) | migrate as is - guide to deploying, revise as guidepost article | | [`server/guides/deploying/aws-sam-lambda.md`](https://www.swift.org/documentation/server/guides/deploying/aws-sam-lambda.html) | migrate as is - slightly outdated | | [`server/guides/deploying/aws-copilot-fargate-vapor-mongo.md`](https://www.swift.org/documentation/server/guides/deploying/aws-copilot-fargate-vapor-mongo.html) | migrate as is - slightly outdated | | [`server/guides/deploying/aws.md`](https://www.swift.org/documentation/server/guides/deploying/aws.html) | migrate as is - slightly outdated |