Add Swift Package Manager docs #10827

loic-sharma · 2024-06-28T23:42:17Z

Flutter iOS/macOS is migrating to Swift Package Manager for native dependencies. This is an experimental feature this isn't ready yet for app developers. However, plugin authors should add Swift Package Manager support to their packages.

The faster plugin authors add SwiftPM support, the sooner we can drop CocoaPods (and make it easier to install Flutter iOS!). There's ~10K Flutter iOS plugins that'll need to migrate, so we really need the plugin migration docs to be as easy to follow as possible. Any and all feedback is appreciated! :)

This is based off @vashworth's guide.

Question for reviewers: What do you think of the doc structure? Should we rearrange things to make it clearer that some sections are to be followed when things go wrong? Or is the current structure clear enough?

Preview URLs:

Part of flutter/flutter#126005

Presubmit checklist

This PR is marked as draft with an explanation if not meant to land until a future stable release.
This PR doesn’t contain automatically generated corrections (Grammarly or similar).
This PR follows the Google Developer Documentation Style Guidelines — for example, it doesn’t use i.e. or e.g., and it avoids I and we (first person).
This PR uses semantic line breaks of 80 characters or fewer.

flutter-website-bot · 2024-06-28T23:46:22Z

Visit the preview URL for this PR (updated for commit 32a0c1c):

https://flutter-docs-prod--pr10827-spm-compatibility-ilxd3b00.web.app

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

loic-sharma · 2024-06-29T21:06:59Z

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

+Package Manager yet.
+:::
+
+## How to disable Swift Package Manager


Ideally app developers enable SwiftPM and never disable it.

However, plugin developers need to enable/disable SwiftPM to test their plugin works with both package managers.

loic-sharma · 2024-06-29T21:13:42Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+
+[flutter#146957]: https://github.com/flutter/flutter/issues/146957
+
+## How to add Swift Package Manager integration to a project manually


Our hope is that the automatic migration will migrate most projects. Most users shouldn't need to follow these steps.

However, users might have modified their project in a way that breaks out automatic migration. Ideally these users would let us know about these modifications so that we can improve our automatic migration.

Question for reviewers: Is it clear that most people can skip these steps?

suggestion: Remove manually. If the reader is doing something, then it's manual by definition.

Suggested change

## How to add Swift Package Manager integration to a project manually

## How to add Swift Package Manager integration to a project

~~I removed manually from the section header but clarified the section intro to clarify these steps are only necessary if the automatic migration fails.~~

Edit: After feedback from Seth, I restructured the page and re-added the manually qualifier. See: #10827 (comment)

loic-sharma · 2024-06-29T21:15:37Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+{% endtab %}
+{% endtabs %}
+
+## How to use a Swift Package Manager Flutter plugin that requires a higher OS version


This is a new kind of error that users can hit when using SwiftPM.

loic-sharma · 2024-06-29T21:16:40Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+image:"development/packages-and-plugins/swift-package-manager/minimum-deployments.png",
+caption:"The target's Minimum Deployments setting" %}
+
+## How to add Swift Package Manager integration to a custom target


This is for less common scenarios where users have heavily modified their project. Most users won't need these steps. Please let me know if there's a better way to call out this special case without making the "manual migration" docs overly convoluted.

Maybe "to a custom Xcode target" and then explain what that means in the first sentence?

loic-sharma · 2024-06-29T21:17:36Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+
+In Step 2, list item 6 use your custom target instead of the Flutter target.
+
+## How to remove Swift Package Manager integration


In theory no one needs to do these steps unless there's a horrible bug in our SwiftPM integration. If you want to use CocoaPods to download native dependencies, you can disable the SwiftPM feature (the SwiftPM integration will still be there but it won't add any native dependencies to your project).

src/content/packages-and-plugins/swift-package-manager/for-plugin-authors.md

sethladd · 2024-07-01T16:43:21Z

src/content/packages-and-plugins/swift-package-manager/for-plugin-authors.md

+It is currently only available on the [`master` channel][].
+Flutter will continue to support CocoaPods until further notice.
+
+Swift Package Manager adoption will be gradual.


if we don't know how the qualify this, not sure we need to say this. I get the sense we want to migrate the ecosystem faster than slower (but, not recklessly)

Ah did you read this as: "Feel free to take your time, no rush on this migration"?

The intent behind this sentence was slightly different: plugin authors should not make plugins that only support SwiftPM. This would break users that haven't updated their projects yet. Plugin should support both CocoaPods and SwiftPM until further notice.

I'll rephrase to make this clearer :)

I tweaked this intro, let me know if it's clearer now.

sethladd · 2024-07-01T16:43:38Z

src/content/packages-and-plugins/swift-package-manager/for-plugin-authors.md

+Swift Package Manager adoption will be gradual.
+
+Flutter recommends that Flutter plugins support _both_ Swift Package Manager
+and CocoaPods until further notice.


if that's not easy to do, should we link to guidance for how to support both?

This guidance does make your plugin support both package managers. I'll add a blurb to clarify this.

I tweaked this intro, let me know if it's clearer now.

src/content/packages-and-plugins/swift-package-manager/index.md

sfshaza2

Hi, @loic-sharma! Thanks so much for this PR. I have reviewed a chunk of it, but some pages have the same text (and therefore require the same edits). Let me know when you are ready for me to take another look.

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

sfshaza2 · 2024-07-01T18:16:15Z

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

+:::note
+Flutter will fallback to CocoaPods for dependencies that do not support Swift
+Package Manager yet.
+:::


Suggested change

:::note

Flutter will fallback to CocoaPods for dependencies that do not support Swift

Package Manager yet.

:::

:::secondary Plugin authors

A Flutter app can have a dependencies from both CocoaPods and

SwiftPM at the same time. However, mixing dependencies from both

package managers can cause issues so, ideally, all iOS plugin authors

add SwiftPM support ASAP.

:::

This isn't quite right. A Flutter app can have a dependencies from both CocoaPods and SwiftPM at the same time. However, mixing dependencies from both package managers can cause issues so ideally everyone adds SwiftPM support ASAP.

Additional context: an app could have a dependency that only supports SwiftPM and another dependency that only supports CocoaPods. We have to use both package managers in this scenario.

I defer to you on the wording...

src/_includes/docs/swift-package-manager/migrate-macos-project-manually.md

jmagman

Thank you so much for tackling this!

jmagman · 2024-07-15T22:12:25Z

src/_data/sidenav.yml

+        - title: For app developers
+          permalink: /packages-and-plugins/swift-package-manager/for-app-developers


I'm not sure app developers would think to go into Packages & plugins
Maybe this should move into Platform integration? Though it would make sense under iOS and macOS, and we don't have a shared category. Whatever you and the tech writers think works best.

oh, good idea!

Sorry for the slow response, I'd like to test if I can link to this page twice: once from the packages & plugin section and once from the platform integration section. Will loop back soon!

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

sethladd · 2024-07-15T22:23:53Z

src/_includes/docs/swift-package-manager/migrate-ios-project-manually.md

@@ -0,0 +1,84 @@
+Once you [turn on Swift Package Manager][] support, the Flutter CLI tries to
+migrate your project to add Swift Package Manager integration.
+This makes your project download the Swift packages that your Flutter


maybe a bit more clear to say "the Flutter tooling downloads the Swift packages" ?

I agree this sentence is a little opaque. I was hoping to hand-wavy explain why your project needs to be migrated without going too deep in the weeds. I'll see if I can add a little more detail here.

Swift packages are downloaded by Xcode, not the Flutter tool.

The process is roughly:

The Flutter tool downloads pub packages

The Flutter tool generates a Swift package that depends on each iOS/macOS plugin

Xcode's build step resolves packages. This starts with the generated Swift package, and then downloads each iOS/macOS plugin's dependencies.

The "Swift Package Manager integration" is your project's dependency on the Swift package that is generated by step 2. The Flutter tool migrates your Xcode project to add this dependency.

sethladd · 2024-07-15T22:24:27Z

src/_includes/docs/swift-package-manager/migrate-ios-project-manually.md

+This makes your project download the Swift packages that your Flutter
+plugins depend on.
+
+However, the Flutter CLI might be unable to migrate your project if you've


Do we mean "even if you've modified it significantly" ?

Note: "even" here?

We can migrate projects unless they've received heavy modifications.

We match do "match and replace" in your Xcode project to migrate it. This should work fine if your project is based off Flutter's templates. However, our matching logic can break if you've modified your Xcode project. The bigger your modifications, the more likely our matching logic breaks.

I guess I'm wondering if we need the "significantly" qualifier?

ideas:

"The Flutter CLI attempts to migrate your project to Swift Package Manager, even if you have made changes to . If the Flutter CLI tool is unable to migrate your project (for example, if there are unexpected modifications to Foo or Bar), then the Flutter CLI tool will ."

Ah gotcha, I dropped the "significantly" qualifier and switched to wording similar to what you suggested.

src/_includes/docs/swift-package-manager/migrate-macos-project-manually.md

atsansone

@loic-sharma : I suggested changes to one file. Review and accept/decline and apply those you accept to the other pages. Thanks!

atsansone · 2024-07-15T22:08:58Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+Flutter is migrating to [Swift Package Manager][] to manage iOS and macOS native
+dependencies.
+This is an experimental feature that might change in the future.
+It is currently only available on the [`main` channel][].
+Flutter will continue to support CocoaPods until further notice.


issue: Condition, then instruction per GSG.
Keep the documentation timeless per GSG.

Suggested change

Flutter is migrating to [Swift Package Manager][] to manage iOS and macOS native

dependencies.

This is an experimental feature that might change in the future.

It is currently only available on the [`main` channel][].

Flutter will continue to support CocoaPods until further notice.

To manage iOS and macOS native dependencies,

Flutter is migrating to [Swift Package Manager][] .

Flutter's support of SPM as described in this guide is under development.

The implementation might change in the future.

SPM support can be found on the [`main` channel][] only.

Flutter continues to support CocoaPods.

Normally I agree that "condition, then instruction" is better, but I think it makes the first sentence choppy. I personally prefer the original first sentence. How strongly do you feel about this?

I updated the remaining sentences!

atsansone · 2024-07-15T22:12:26Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+   macOS.
+
+If you find a bug in Flutter's Swift Package Manager support,
+please [open an issue][].


issue: Remove please per GSG.

Suggested change

please [open an issue][].

[open an issue][].

This feels curt to me, but updated :(

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

atsansone · 2024-07-15T22:14:20Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+
+[flutter#146957]: https://github.com/flutter/flutter/issues/146957
+
+## How to add Swift Package Manager integration to a project manually


suggestion: Remove manually. If the reader is doing something, then it's manual by definition.

Suggested change

## How to add Swift Package Manager integration to a project manually

## How to add Swift Package Manager integration to a project

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

atsansone · 2024-07-15T22:35:39Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+1. **Access to the Swift package ecosystem**.
+   Flutter plugins can use the growing ecosystem of [Swift packages][]! 
+2. **Simplifies Flutter installation**.
+   Swift Package Manager is bundled with Xcode.
+   In the future, you won’t need to install Ruby and CocoaPods to target iOS or
+   macOS.


issue:

Use parallel structure in your list sentences.

Remove the exclamation point per GSG.

Keep the documentation timeless.

Use present tense.

Suggested change

1. **Access to the Swift package ecosystem**.

Flutter plugins can use the growing ecosystem of [Swift packages][]!

2. **Simplifies Flutter installation**.

Swift Package Manager is bundled with Xcode.

In the future, you won’t need to install Ruby and CocoaPods to target iOS or

macOS.

1. **Provides access to the Swift package ecosystem**.

Flutter plugins can use the growing ecosystem of [Swift packages][]!

1. **Simplifies Flutter installation**.

Xcode includes Swift Package Manager.

Targeting iOS or macOS doesn't require Ruby and CocoaPods.

This sounds good but I tweaked the last sentence:

- Targeting iOS or macOS doesn't require Ruby and CocoaPods. + You don't need to install Ruby and CocoaPods if your project uses + Swift Package Manager.

Let me know what you think!

stuartmorgan · 2024-07-16T14:10:52Z

src/content/packages-and-plugins/swift-package-manager/for-plugin-authors.md

+Plugins that don't support CocoaPods won't be usable by projects that haven't
+migrated to Swift Package Manager yet.
+Plugins that don't support Swift Package Manager can cause problems for projects
+that have migrated.


It might be nice to explicitly say here that we expect to remove support for CocoaPods at some point in the future, so adding SPM support will future-proof plugins. That will make it more clear why a plugin author should do this work.

Agreed.

@atsansone What would be the best way to state this while following the timeless GSG?

Flutter expects to remove support for CocoaPods. Adding Swift Package Manager support future-proofs your plugins.

I think this would be a valuable sentence to add, but it goes against the GSG guidance.

sethladd · 2024-07-16T15:34:59Z

src/_data/sidenav.yml

+        - title: For app developers
+          permalink: /packages-and-plugins/swift-package-manager/for-app-developers


oh, good idea!

src/_includes/docs/swift-package-manager/how-to-enable-disable.md

sethladd · 2024-07-16T15:38:04Z

src/_includes/docs/swift-package-manager/migrate-ios-project-manually.md

+This makes your project download the Swift packages that your Flutter
+plugins depend on.
+
+However, the Flutter CLI might be unable to migrate your project if you've


I guess I'm wondering if we need the "significantly" qualifier?

ideas:

"The Flutter CLI attempts to migrate your project to Swift Package Manager, even if you have made changes to . If the Flutter CLI tool is unable to migrate your project (for example, if there are unexpected modifications to Foo or Bar), then the Flutter CLI tool will ."

sethladd · 2024-07-16T15:42:04Z

src/content/packages-and-plugins/swift-package-manager/for-app-developers.md

+
+{% include docs/swift-package-manager/how-to-enable-disable.md %}
+
+## How to add Flutter to an existing app (add-to-app)


this was a surprising header in this file, and it was surprising to see this first before "how to add SPM to a project".

Consider:

How to add SPM to a full Flutter app

How to migrate to SPM for a Flutter add-to-app scenario

Not yet supported, follow this bug, etc...

In this way, the headers rhyme and are clear about their scenarios. WDYT?

This is excellent feedback. The guide was misleading: hopefully no one needs to do the manual steps. I restructured the page and added a guide dedicated to the auto migration. I also renamed these headers to align better. See: #10827 (comment)

johnpryan

LGTM - i was able to get the pedometer sample up and running with these instructions.

loic-sharma · 2024-07-16T20:15:42Z

@sfshaza2 @atsansone @sethladd Hey there, I re-structured the "For app developers page":

Summary of changes:

I added a new How to add Swift Package Manager Integration section. I moved other existing guides to this section (the add-to-app guide, and the manual process guide)
I created a new guide How to add Swift Package Manager Integration > Add to a Flutter app. This section is entirely new content that covers the automatic migration to add SPM integration to a Flutter app.

This was in response to Seth's comment here: #10827 (comment)

Please let me know what you think!

sethladd

lgtm - thank you!

sfshaza2 · 2024-07-16T22:45:47Z

@loic-sharma, thanks for all of these updates and hanging in there! I'm going to land this. If there are further tweaks, they can be handled in another PR.

loic-sharma added 11 commits June 28, 2024 10:31

Begin import

f1cba09

Use tabs for migration guides

cfe87b4

Work

ce19db0

Formatting

a0d9321

Work

936154e

Work

78a1617

Work

3c6f68d

Work

1eeb04a

Start importing images

43fbe63

Import more images

b1f8285

Yay I can write diff files by hand now

58fb5f7

hellohuanlin reviewed Jun 29, 2024

View reviewed changes

src/_includes/docs/swift-package-manager/how-to-enable-disable.md Outdated Show resolved Hide resolved

sfshaza2 self-assigned this Jun 29, 2024

loic-sharma commented Jun 29, 2024

View reviewed changes

sethladd reviewed Jul 1, 2024

View reviewed changes

atsansone added the review.copy Awaiting Copy Review label Jul 1, 2024

loic-sharma marked this pull request as ready for review July 1, 2024 17:11

loic-sharma requested review from sfshaza2, atsansone, parlough, domesticmouse and MaryaBelanger as code owners July 1, 2024 17:11

loic-sharma added 2 commits July 1, 2024 11:52

Link to SPM docs

9c12c3c

Feedback

790e5a0

sfshaza2 reviewed Jul 1, 2024

View reviewed changes

loic-sharma added 8 commits July 12, 2024 14:56

Tony feedback

115e353

Tony feedback

3d6076f

Tony feedback: use fewer warning blocks

1e3dd40

Tony feedback: use contractions

1f7ed78

Tony feedback: hemingway pass

ef3be5b

Tony feedback: replace enable/disable with turn on/off

dbde679

Tony feedback: replace enable/disable with turn on/off

0460798

Tony feedback: replace enable/disable with turn on/off

1ed8131

domesticmouse approved these changes Jul 14, 2024

View reviewed changes

jmagman approved these changes Jul 15, 2024

View reviewed changes

sethladd reviewed Jul 15, 2024

View reviewed changes

atsansone reviewed Jul 15, 2024

View reviewed changes

loic-sharma added 2 commits July 15, 2024 17:18

Seth feedback

677ae4a

Start Tony feedback; TODO double check I didn't miss anything

e861981

stuartmorgan reviewed Jul 16, 2024

View reviewed changes

sethladd reviewed Jul 16, 2024

View reviewed changes

loic-sharma added 5 commits July 16, 2024 09:27

Fix link

33bad77

Tony feedback

7406fbe

Clarify this content is only if the auto migration fails

46f40d5

Tony feedback

ec32096

Seth feedback

d34aeca

johnpryan approved these changes Jul 16, 2024

View reviewed changes

loic-sharma added 3 commits July 16, 2024 12:59

Restructure for app developers page ; add auto migration docs

b50fdf5

Seth feedback

874206f

Tony feedback

32a0c1c

sethladd approved these changes Jul 16, 2024

View reviewed changes

sfshaza2 merged commit e762902 into flutter:main Jul 16, 2024
9 checks passed

sfshaza2 mentioned this pull request Jul 18, 2024

Add info on how to support both CocoaPods and Swift Package Manager for iOS plugins #10806

Closed

1 task


		[flutter#146957]: https://github.com/flutter/flutter/issues/146957

		## How to add Swift Package Manager integration to a project manually


		In Step 2, list item 6 use your custom target instead of the Flutter target.

		## How to remove Swift Package Manager integration

-:::note
-Flutter will fallback to CocoaPods for dependencies that do not support Swift
-Package Manager yet.
-:::
+:::secondary Plugin authors
+A Flutter app can have a dependencies from both CocoaPods and
+SwiftPM at the same time. However, mixing dependencies from both
+package managers can cause issues so, ideally, all iOS plugin authors
+add SwiftPM support ASAP.
+:::

		- title: For app developers
		permalink: /packages-and-plugins/swift-package-manager/for-app-developers

-Flutter is migrating to [Swift Package Manager][] to manage iOS and macOS native
-dependencies.
-This is an experimental feature that might change in the future.
-It is currently only available on the [`main` channel][].
-Flutter will continue to support CocoaPods until further notice.
+To manage iOS and macOS native dependencies,
+Flutter is migrating to [Swift Package Manager][] .
+Flutter's support of SPM as described in this guide is under development.
+The implementation might change in the future.
+SPM support can be found on the [`main` channel][] only.
+Flutter continues to support CocoaPods.


		{% include docs/swift-package-manager/how-to-enable-disable.md %}

		## How to add Flutter to an existing app (add-to-app)

Add Swift Package Manager docs #10827

Add Swift Package Manager docs #10827

Conversation

loic-sharma commented Jun 28, 2024 • edited Loading

Presubmit checklist

flutter-website-bot commented Jun 28, 2024 • edited Loading

loic-sharma Jun 29, 2024 • edited Loading

Choose a reason for hiding this comment

loic-sharma Jun 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-sharma Jul 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-sharma Jun 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-sharma Jun 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sfshaza2 left a comment

Choose a reason for hiding this comment

sfshaza2 Jul 1, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-sharma Jul 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jmagman left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

loic-sharma Jul 15, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

atsansone left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

johnpryan left a comment • edited Loading

Choose a reason for hiding this comment

loic-sharma commented Jul 16, 2024 • edited Loading

sethladd left a comment

Choose a reason for hiding this comment

sfshaza2 commented Jul 16, 2024

loic-sharma commented Jun 28, 2024 •

edited

Loading

flutter-website-bot commented Jun 28, 2024 •

edited

Loading

loic-sharma Jun 29, 2024 •

edited

Loading

loic-sharma Jun 29, 2024 •

edited

Loading

loic-sharma Jul 16, 2024 •

edited

Loading

loic-sharma Jun 29, 2024 •

edited

Loading

loic-sharma Jun 29, 2024 •

edited

Loading

sfshaza2 Jul 1, 2024 •

edited

Loading

loic-sharma Jul 3, 2024 •

edited

Loading

loic-sharma Jul 15, 2024 •

edited

Loading

johnpryan left a comment •

edited

Loading

loic-sharma commented Jul 16, 2024 •

edited

Loading