Document semantic versioning

Also updates runner to use ubuntu 22.04
apple · Oct 29, 2024 · ecd5aa3 · ecd5aa3
1 parent e8a1dec
commit ecd5aa3
Show file tree

Hide file tree

Showing 5 changed files with 85 additions and 49 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -33,7 +33,7 @@ env:
 jobs:
   swift-tests:
     timeout-minutes: 15
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     strategy:
       fail-fast: false
       matrix:
@@ -56,7 +56,7 @@ jobs:
         done
   pre-commit:
     timeout-minutes: 1
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
     - name: Install pre-commit
@@ -69,7 +69,7 @@ jobs:
         pre-commit run --all-files
   lint:
     timeout-minutes: 15
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
     - name: Cache SwiftLint
@@ -86,7 +86,7 @@ jobs:
       run: /tmp/swiftlint/SwiftLint/.build/release/swiftlint lint --strict .
   lockwood-swiftformat:
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
     - name: Cache SwiftFormat
@@ -103,7 +103,7 @@ jobs:
       run: /tmp/swiftformat/SwiftFormat/.build/release/swiftformat --strict .
   check-doc-comments:
     timeout-minutes: 5
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
     - uses: actions/checkout@v4
     - name: Check documentation comments

diff --git a/README.md b/README.md
@@ -76,14 +76,6 @@ While this *trivial PNNS* protocol satisfies the privacy and correctness require
 The PNNS implementation in Swift Homomorphic Encryption uses homomorphic encryption to improve upon the trivial PNNS protocol.
 
 ## Using Swift Homomorphic Encryption
-Swift Homomorphic Encryption requires:
-* 64-bit processor with little-endian memory representation
-* macOS or Linux operating system
-* [Swift](https://www.swift.org/) version 6.0 or later
-
-> [!NOTE]
-> Swift Homomorphic Encryption relies on [SystemRandomNumberGenerator](https://developer.apple.com/documentation/swift/systemrandomnumbergenerator) as a cryptographically secure random number generator, which may have platform-dependent behavior.
-
 Swift Homomorphic Encryption is available as a Swift Package Manager package.
 To use Swift Homomorphic Encryption, choose a [tag](https://github.com/apple/swift-homomorphic-encryption/tags).
 Then, add the following dependency in your `Package.swift`
@@ -121,22 +113,45 @@ You can then add
  ```
 to your Swift code to access the functionality in the `HomomorphicEncryption` library.
 
-See the example [Snippets](https://github.com/apple/swift-homomorphic-encryption/tree/main/Snippets) for examples of using `HomomorphicEncryption`.
-To run the `EncryptionParametersSnippet` example, run
+> [!NOTE]
+> If you are using Swift Homomorphic Encryption for research, please cite using the
+> [CITATION.cff](CITATION.cff) file.
+
+#### Examples
+See the [Snippets](https://github.com/apple/swift-homomorphic-encryption/tree/main/Snippets) for examples using `HomomorphicEncryption`.
+To run the `EncryptionParametersSnippet`, run
 ```
 swift run -c release EncryptionParametersSnippet
 ```
 
+### Supported Platforms
+Swift Homomorphic Encryption aims to support all of the platforms where Swift is supported. Currently, it is developed and tested on macOS and Linux, and is known to support 64-bit processors with little-endian memory representation and the following operating system versions:
+* Ubuntu 22.04
+* macOS 15.0 with Xcode 16.1
+
 > [!NOTE]
-> If you are using Swift Homomorphic Encryption for research, please cite using the
-> [CITATION.cff](CITATION.cff) file.
+> Swift Homomorphic Encryption relies on [SystemRandomNumberGenerator](https://developer.apple.com/documentation/swift/systemrandomnumbergenerator) as a cryptographically secure random number generator, which may have platform-dependent behavior.
+
+### Swift / Xcode versions
+The following table maps Swift Homomorphic Encryption packgae versions to required Swift and Xcode versions:
+
+Package version | Swift version | Xcode version
+----------------|---------------|-----------------------------------------
+1.0.x           | >= Swift 5.10 | >= Xcode 15.3
+main            | >= Swift 6.0  | >= Xcode 16.1
+
+### Source Stability
+Swift Homomorphic Encryption follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). Source breaking changes to the public API can only land in a new major version, with the following exception:
+
+* Adding a new `case` to a public `enum` type will require only a minor version bump. For instance, we may add a new `enum` to an [HeError](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/documentation/homomorphicencryption/heerror). To avoid breaking source code, add a  `default` case when adding a `switch` on the enum values.
+
+Future minor versions of the package may introduce changes to these rules as needed.
+
+We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump.
 
 ## Developing Swift Homomorphic Encryption
 ### Dependencies
-Building Swift Homomorphic Encryption requires:
-* [Swift](https://www.swift.org/) version 5.10 or later
-
-Additionally, developing Swift Homomorphic Encryption requires:
+Developing Swift Homomorphic Encryption requires:
 * [Nick Lockwood SwiftFormat](https://github.com/nicklockwood/SwiftFormat), v0.54.0
 * [pre-commit](https://pre-commit.com)
 * [swift-format](https://github.com/apple/swift-format), v510.1.0

diff --git a/Sources/HomomorphicEncryption/HomomorphicEncryption.docc/Examples.md b/Sources/HomomorphicEncryption/HomomorphicEncryption.docc/Examples.md
@@ -0,0 +1,30 @@
+# Examples
+
+Examples for how to use ``HomomorphicEncryption``
+
+## Basics
+We start with the basics.
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"encryption")
+
+## HE Addition and Subtraction
+Continuing from the previous example, we can also compute on the encrypted data.
+We can add a ciphertext with a ciphertext or a plaintext.
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"addition")
+
+Continuing from the previous example, we can also subtract a ciphertext by a ciphertext or a plaintext.
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"subtraction")
+
+## HE Multiplication
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/MultiplicationSnippet")
+
+## Evaluation Key
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/EvaluationKeySnippet")
+
+## Noise budget
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/NoiseBudgetSnippet")
+
+## Serialization
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/SerializationSnippet")
+
+## Encryption Parameters
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/EncryptionParametersSnippet")
diff --git a/Sources/HomomorphicEncryption/HomomorphicEncryption.docc/HomomorphicEncryption.md b/Sources/HomomorphicEncryption/HomomorphicEncryption.docc/HomomorphicEncryption.md
@@ -44,4 +44,5 @@ This scheme can be configured to support post-quantum 128-bit security.
 <!-- Snippets are defined in a different "virtual module", requiring manually linking articles here. -->
 ### Articles
 - <doc:DataFormats>
+- <doc:Examples>
 - <doc:UsingSwiftHomomorphicEncryption>
diff --git a/...morphicEncryption/HomomorphicEncryption.docc/UsingSwiftHomomorphicEncryption.md b/...morphicEncryption/HomomorphicEncryption.docc/UsingSwiftHomomorphicEncryption.md
@@ -3,13 +3,6 @@
 Get started using Swift Homomorphic Encryption.
 
 ## Overview
-Swift Homomorphic Encryption requires:
-* 64-bit processor with little-endian memory representation
-* macOS or Linux operating system
-* [Swift](https://www.swift.org/) version 6.0 or later
-
-> Note: Swift Homomorphic Encryption relies on [SystemRandomNumberGenerator](https://developer.apple.com/documentation/swift/systemrandomnumbergenerator) as a cryptographically secure random number generator, which may have platform-dependent behavior.
-
 Swift Homomorphic Encryption is available as a Swift Package Manager package.
 To use Swift Homomorphic Encryption, choose a [tag](https://github.com/apple/swift-homomorphic-encryption/tags).
 Then, add the following dependency in your `Package.swift`
@@ -50,31 +43,28 @@ to your Swift code to access the functionality in the `HomomorphicEncryption` li
 > If you are using Swift Homomorphic Encryption for research, please cite using the
 > [CITATION.cff](https://github.com/apple/swift-homomorphic-encryption/blob/main/CITATION.cff) file.
 
-### Examples
-We give a few examples for how to use ``HomomorphicEncryption``.
-#### Basics
-We start with the basics.
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"encryption")
 
-#### HE Addition and Subtraction
-Continuing from the previous example, we can also compute on the encrypted data.
-We can add a ciphertext with a ciphertext or a plaintext.
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"addition")
+### Supported Platforms
+Swift Homomorphic Encryption aims to support all of the platforms where Swift is supported. Currently, it is developed and tested on macOS and Linux, and is known to support 64-bit processors with little-endian memory representation and the following operating system versions:
+* Ubuntu 22.04
+* macOS 15.0 with Xcode 16.1
+and 64-bit processors with little-endian memory representation.
+
+> Note: Swift Homomorphic Encryption relies on [SystemRandomNumberGenerator](https://developer.apple.com/documentation/swift/systemrandomnumbergenerator) as a cryptographically secure random number generator, which may have platform-dependent behavior.
 
-Continuing from the previous example, we can also subtract a ciphertext by a ciphertext or a plaintext.
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"subtraction")
+### Swift / Xcode versions
+The following table maps Swift Homomorphic Encryption packgae versions to required Swift and Xcode versions:
 
-#### HE Multiplication
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/MultiplicationSnippet")
+Package version | Swift version | Xcode version
+----------------|---------------|-----------------------------------------
+1.0.x           | >= Swift 5.10 | >= Xcode 15.3
+main            | >= Swift 6.0  | >= Xcode 16.1
 
-#### Evaluation Key
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/EvaluationKeySnippet")
+### Source Stability
+Swift Homomorphic Encryption follows [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html). Source breaking changes to the public API can only land in a new major version, with the following exception:
 
-#### Noise budget
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/NoiseBudgetSnippet")
+* Adding a new `case` to a public `enum` type will require only a minor version bump. For instance, we may add a new `enum` to an [HeError](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/documentation/homomorphicencryption/heerror). To avoid breaking source code, add a  `default` case when adding a `switch` on the enum values.
 
-#### Serialization
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/SerializationSnippet")
+Future minor versions of the package may introduce changes to these rules as needed.
 
-#### Encryption Parameters
-@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/EncryptionParametersSnippet")
+We'd like this package to quickly embrace Swift language and toolchain improvements that are relevant to its mandate. Accordingly, from time to time, we expect that new versions of this package will require clients to upgrade to a more recent Swift toolchain release. Requiring a new Swift release will only require a minor version bump.