Skip to content

Introduce Package Best Practices #1101

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Introduce Package Best Practices #1101

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions packages/best-practices/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
---
layout: page-wide
title: Package Best Practices
---

Swift Packages should follow a similar set of best practices across the ecosystem. This helps package users know what to expect when using packages and provides package authors some guidelines to follow when creating packages.

## Version Support

Swift Packages should support the latest version of Swift and the previous tro minor versions. For example, if the latest version Swift is 6.1, packages should also support Swift 6.0 and Swift 5.10. This provides a balance between keeping up with the latest language features and maintaining compatibility with older versions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Swift Packages should support the latest version of Swift and the previous tro minor versions. For example, if the latest version Swift is 6.1, packages should also support Swift 6.0 and Swift 5.10. This provides a balance between keeping up with the latest language features and maintaining compatibility with older versions.
Swift Packages should support the latest version of Swift and the previous two prior minor versions.
For example, if the latest version Swift is 6.1, packages should also support Swift 6.0 and Swift 5.10.
This provides a balance between keeping up with the latest language features and maintaining compatibility with older language versions.

(fix typo and break into a sentence per line to make it easier to read in the PR)


New packages that are released can target only the latest version of Swift at the time of release if they choose to do so to make use of the latest language features and improvements.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
New packages that are released can target only the latest version of Swift at the time of release if they choose to do so to make use of the latest language features and improvements.
New packages that you release can target only the latest version of Swift at the time of release if you choose to do so to make use of the latest language features and improvements.
As that package evolves, grow into supporting two prior minor versions over time.

I suggest that the "new package" exception still call out that over time, they should follow the 2 prior minor version pattern. Also - I changed the wording to avoid passive voice.


## SemVer Versioning

Swift Package Manager relies on [Semantic Versioning](https://semver.org/) to manage package versions. Packages should follow the SemVer guidelines, to ensure that dependency resolution works as expected and provides a good experience for consumers of packages.

This includes:

- Using [major, minor, and patch versioning](https://semver.org/#spec-item-2) to indicate breaking changes, new features, and bug fixes.
- Using [pre-release versions](https://semver.org/#spec-item-9) for offering early access to new features or changes that are not yet stable.
- Ensuring only breaking changes are introduced in major versions.
- Only releasing major versions when necessary, to avoid unnecessary churn in the ecosystem and provide a stable experience for package users.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this would greatly benefit from a warning note to not assume that a tag with "1.0" is sufficient for SwiftPM. Maybe it should be, but in practice if you give it the short form tag (assumed "1.0" being equivalent to "1.0.0" - it doesn't fly and causes all sorts of hassle for the package/library author)

## CI and Testing

Packages should include continuous integration (CI) and testing to ensure that the package works as expected across different versions of Swift and platforms. This helps catch issues early and provides confidence to package users that the package is reliable.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Packages should include continuous integration (CI) and testing to ensure that the package works as expected across different versions of Swift and platforms. This helps catch issues early and provides confidence to package users that the package is reliable.
Include and use continuous integration (CI) and testing to ensure that the package works as expected across multiple versions of Swift and platforms. This helps catch issues early and provides confidence to package users that the package is reliable.

(pedant nit: packages doesn't provide CI, you do)


Swiftlang offers a number of [GitHub Actions](https://github.com/swiftlang/github-workflows) that can be used to set up CI for different Swift versions and platforms. There are also workflows for ensuring packages follow community standards and don't introduce breaking changes.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is https://github.com/swiftlang/github-workflows supposed to be used outside the swiftlang org/projects? Last I heard the answer was a no. The README also says this:

This repository will contain reusable workflows to minimize redundant workflows across the organization. This effort will also facilitate the standardization of testing processes while empowering repository code owners to customize their testing plans as needed. The repository will contain workflows to support different types of repositories, such as Swift Package and Swift Compiler.

Is the "recommendation" going to change to "https://github.com/swiftlang/github-workflows is for everyone to use!"? I'd like that although there will be questions about how to properly maintain that effort of "Swift GitHub Actions workflows standardization".

Or I guess alternatively you can change the sentence to refer to https://github.com/swiftlang/github-workflows as "sample workflows" instead of sounding like "what you should use".

5 changes: 5 additions & 0 deletions packages/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,8 @@ The [Swift Package Index](https://swiftpackageindex.com/) is a community-run pac
- [Have compatibility with both iOS and macOS platforms](https://swiftpackageindex.com/search?query=swiftui+platform:ios,macos)
- [Include an executable helper or tool](https://swiftpackageindex.com/search?query=swiftui+product:executable)
- [Have been created by a specific author](https://swiftpackageindex.com/search?query=author:apple)


## Best Practices

The [Ecosystem Steering Group](/ecosystem-steering-group/) maintains a set of best practices for package authors in the Swift ecosystem that cover things like version support, documentation and CI. You can find them [here](/packages/best-practices/).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The [Ecosystem Steering Group](/ecosystem-steering-group/) maintains a set of best practices for package authors in the Swift ecosystem that cover things like version support, documentation and CI. You can find them [here](/packages/best-practices/).
The [Ecosystem Steering Group](/ecosystem-steering-group/) maintains a set of best practices for package authors in the Swift ecosystem that cover things like version support, documentation and CI. You can find them within [package best practices](/packages/best-practices/).

Using "here" is horrible for SEO, and makes the resulting best practices that you're documenting FAR harder to be be found. Name it and reference it, and map that name through so it's re-inforced.