Introduce Package Best Practices

[0xTim]

Introduces a package best practices page from the ESG to help packages in the ecosystem follow a consistent set of guidelines.

cc @FranzBusch

[shahmishal]

cc: @swiftlang/ecosystem-steering-group

[MahdiBM]

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".

[heckj]

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)

[heckj]

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.

[heckj]

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)

[heckj]

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.

[heckj]

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)

[daveverwer]

I wonder if this page is the correct place to address package naming, if not with guidance then at least with an explanation.

Both the apple and swift-lang organisations name many (although not all) of their open source packages with a swift- prefix. This had led to many community-developed packages also adopting the naming pattern.

I know I’m not alone in not really understanding this naming pattern and I’m sure that some members of the community are following it primarily because apple and swift-lang do it, rather than for any other reason.

We run the risk of having the Swift package ecosystem be full of packages that (unnecessarily, in my opinion) start with the word swift. I’m sure there’s a reason this naming convention started, and this document might be a good place to talk about package naming, documenting that reason if there is one, or assuring people that’s not a naming convention, if it’s not.

[FranzBusch]

I would like us to take a step back here and define a more formal setup for best practices. Potentially similar to swift-evolution or Google AIPs. From a high level I was thinking of:

• Use DocC for maintaining them
• Have a template that each best practice needs to follow
• Have each best practice referencable e.g. have a static URL with a defined numbering scheme

This is something that I think the ESG should setup as part of their charter to create a flourishing ecosystem.

[MahdiBM]

@daveverwer

Both the apple and swift-lang organisations name many (although not all) of their open source packages with a swift- prefix. This had led to many community-developed packages also adopting the naming pattern.

I'm not sure if this is the best place for a discussion, this PR seems to already be getting a lot of feedback, but I want to mention that Swift is not the first language that has come across package naming "problems", so we can take a look at other language's experiences.

For example one of Rust's current recommendations is:

Crate names should not use -rs or -rust as a suffix or prefix. Every crate is Rust! It serves no purpose to remind users of this constantly.

A few years ago the Rust Foundation was trying to somehow reserve those prefix/suffixes for official crates/packages, but that was met with community backlash (related tweet, see the comments) so I'd assume that's why their current guidelines only recommend to not do that, instead of trying to prohibit it.