Skip to content

11 ‐ How to make release of Swift Package

Jump to bottom
Pierre-Yves Lapersonne edited this page Nov 11, 2025 · 10 revisions

Steps

Here are all the steps to follow when releasing a new version of OUDS iOS.

Make earlier release (alpha, beta, release candidate)

You must comply with semantic versioning rules. Choose the type of early release you want:

  • If you think the current develop code base will be almost equal to the next release make a release candidate (prefered)
  • If your users need a beta version and ask for it, make a beta release
  • If your users need an alpha version and ask for it, make a alpha release

These tags must be done on develop branch.

Tip

For example, given a future x.y.z. version 1.2.3, a release candidate n°1 will be tagged 1.2.3-rc.1, a beta n°1 will be tagged 1.2.3-beta.1, an alpha n°1 will be tagged 1.2.3-alpha.1

The snapshot tag (x.y.z-SNAPSHOT) is not used in this project.

The actions to do are:

  • update the SBOM
  • update the online documentation if relevant
  • define the tag on develop branch depending to what should be the next release

Caution

These notions of alpha and beta releases are not the same as the alpha builds (i.e. build a feature branch without tags) and the beta builds (i.e. in OUDS context nightly builds tagged with "ci" and "Test_Flight" sufixes). alpha and beta builds are for the design system toolbox app

Prepare release

Tip

We use here CLI for Git operations, but of course you are free to use GUI tools. Below are explained the steps and main things to do.

  • Create a branch named prepare-release to prepare the new release for OUDS iOS version X.Y.Z.

    git checkout -b prepare-release develop

  • Switch to this branch and apply following changes:

    • Update the changelog.
    \## [Unreleased]\(https://github.com/Orange-OpenSource/ouds-ios/compare/P.Q.R...develop)

    to

     \## [X.Y.Z]\(https://github.com/Orange-OpenSource/ouds-ios/compare/P.Q.R...X.Y.Z) - YYYY-MM-dd

    where P.Q.R is the previous version tag, X.Y.Z the version we are releasing, and YYYY-MM-dd the date.

    • Update the SBOM
    bundle exec fastlane update_sbom

Important

Keeping up-to-date the SBOM and check for vulnerabilities is important for both software quality, users trust and legal obligations like the Cyber Resilience Act or NIS2.

  • Update also the displayed versions of themes and components

    # You should be in "scripts" folder
./updateTokensLibraryVersion.sh

  • Verify the changes mentioned above, then commit and push.

  • Create a new pull request named Prepare release X.Y.Z on GitHub to merge your branch into develop.

  • Review and merge this pull request on GitHub using squash and merge commits strategy. Delete your old temporary branch.

Release

Update Git main branch

  • Create a new pull request named Release X.Y.Z on GitHub to merge develop into main. Add in the description the CHANGELOG for this new version. Thus GitHub will automatically make the links and display the PR in the mentioned issues.

  • Review and merge this pull request on GitHub. The merge strategy must be a simple merge without squash of commits, i.e. "create a merge commit".

Note

In fact rebase should be used to align feature branches with default one, and squash should be used when needed for work branches.

In the merge commit message add the changelog, the authors and the details. Thus GitHub makes links automatically between commits, PR and GitHub issues. To do that, copy/paste the content of the changelog (after the version line) and uncomment (i.e. remove # symbols) lines. Thus if in the commit message body any issue is referenced, it will appear in the associated issue. Do not forget also to add people as co-authors if needed. Remember, do not squash nor rebase but only merge commit.

Below is an example of what should be a merge commit in main branch for a release (ignore of course // lines, see this commit for example):

Version 0.17.0 (#113) // [DO NOT ADD THIS COMMENT] <--- Commit title, #113 is PR nummber, GitHub suggests it

// [DO NOT ADD THIS LINE] Below is commit body, keep an empty line
Release of version 0.17.0
Embeds token libraries:
- Core OUDS version: 1.3.0
- Core Orange version: 1.1.0
- Brand Orange version: 1.3.0
- Core Sosh version: 1.1.0
- Brand Sosh version: 1.3.0
- Core Wireframe version: 1.0.0
- Brand Wireframe version: 1.1.0
- Brand Orange Business Tools version: 1.3.0

See below the full CHANGELOG details.

// [DO NOT ADD THIS LINE] Keep also an empty line above
// [DO NOT ADD THIS LINE] And copy/paste changelog without #
Added:
- [Tests] Add UI regression tests using snapshot comparisons with *swift-snapshot-testing* tool ([#78](#78))
- [DesignToolbox] Display fake components for elevation rendering tests

Changed:
- [Library] Split raws, semantics and components tokens definitions and also values, composites and type aliases
- [DesignToolbox] Improve Fastlane alpha build notifications

Removed:
- [Library] Remove Z Index tokens for elevations ([#109](#109))

Fixed:
- [Library] Fix some typos in documentation ([#89](#89))

// [DO NOT ADD THIS LINE] Add in co authors anyone working on the commits being merged, add the ones who contributed (copy-paste if too lazy, use the ones you need)
Co-authored-by: Benoit Suzanne <[email protected]>
Co-authored-by: Pierre-Yves Lapersonne <[email protected]>
Co-authored-by: Ludovic Pinel <[email protected]>
Co-authored-by: Tayeb Sedraia <[email protected]>
Co-authored-by: boosted-bot <[email protected]>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>

You can also look inside this commit for example.

  • Generate documentation: from Xcode build the documentation, export each doccarchive in your downlaods folder (9 modules), then run the script ; it will update online version and generate a ZIP file in /tmp

    ./generateWebDocumentation.sh --libversion=X.Y.Z --usegit

Publish release to GitHub

Caution

Prefer creating a tag locally to cryptographically sign it (if you used for example GPG). Keep in mind the project uses GitHub immutable release: when the release is done the tag will be blocked and the associated release won't be editable. The tag won't be usable then.

  • Define the ZIP archive of the documentation by compressing all doccarchives files into one ZIP, and add it in artifact. The doccarchives to compress must be exported from the Xcode pane after documentation build. Name the archive ouds-doccarchive.zip.

  • (optional but recommended) Sign the archive with GPG to get the ouds-doccarchive.zip.asc file

gpg --armor --detach-sign ouds-doccarchive.zip
# Or if you have several keys, choose the one you need
# gpg --local-user KEY_ID --armor --detach-sign ouds-doccarchive.zip

  • Export from documentation build the tutorial and renamed to Tutorial.doccarchive.zip

  • (optional but recommended) Sign the archive with GPG to get the Tutorial.doccarchive.zip.asc file

gpg --armor --detach-sign Tutorial.doccarchive.zip.zip
# Or if you have several keys, choose the one you need
# gpg --local-user KEY_ID --armor --detach-sign Tutorial.doccarchive.zip

  • Download the GitHub Page branch content as zip, rename it to ouds-ios-gh-pages.zip

  • (optional but recommended) Sign the archive with GPG to get the ouds-ios-gh-pages.zip.asc file

gpg --armor --detach-sign ouds-ios-gh-pages.zip
# Or if you have several keys, choose the one you need
# gpg --local-user KEY_ID --armor --detach-sign ouds-ios-gh-pages.zip
gpg --armor --detach-sign ouds-ios.wiki.zip
# Or if you have several keys, choose the one you need
# gpg --local-user KEY_ID --armor --detach-sign ouds-ios.wiki.zip

  • From previous release get wiki assets first, then sign it like wiki archive (optional but recommended)

  • Go to GitHub Releases.

  • Click on Draft a new release.

  • Chose a previously cryptographically signed Git tag (X.Y.Z), or if not create new one (following semantic versioning principles)

  • Add release notes and verify using the preview tab. Use git-cliff to build the release note to copy/paste in the release description

    # Where X is the previous tag and Y the new freshly created tag or HEAD
# Run in main branch of course.
git-cliff --config .github/cliff.toml --output RELEASE_NOTE.md X..Y

Tip

X can be a commit hash or the last tag for example. Y should be HEAD or the new tag if it exists Run this command on main branch.

  • Upload all artifacts (zips and .asc files)

  • Publish the release

A bit lost? Quite simple: look this release and do the same thing.

Important

You must make a release of the OUDS Swift Package before this release so as to make the app point to the stable tag

Prepare next release

  • Create a branch named prepare-new-release to prepare the new release for OUDS iOS version U.V.W.

  • Switch to this branch and apply following changes:

    • Update the changelog.

    Add a section like:

    \## [Unreleased]\(https://github.com/Orange-OpenSource/ouds-ios/compare/X.Y.Z...develop)
    • Commit your modifications
    • Push them to the repository
    • Create a new pull request named Update release U.V.W on GitHub to merge your branch into develop
    • Review and merge this pull request on GitHub using merge + squash strategy

Update wiki

Some pages of the wiki may need to be updated:

About documentation

The documentation tool in use is Swift DocC ; we use the swift-docc-plugin to produce documentation from the codebase and generate HTML assets for static websites. Of course the doccarchives can be created from Xcode.

To update the online documentation run the script generateWebDocumentation.sh. The swift package generate-documentation will be called, assets generated, and everything sent to GitHub Pages (if --usegit option used).

# You should be in "scripts" folder

# To show the help:
./generateWebDocumentation.sh --help

# To build the doc and push to GitHub:
# VERSION will be added in the Git commits
# --usegit make the script upload sources to GitHub
./generateWebDocumentation.sh --libversion=VERSION --usegit

# If you don't want the ZIP to be computed:
./generateWebDocumentation.sh --libversion=VERSION --usegit --nozip

Keep in mind everything is stored in /tmp folder with the execution timestamp, thus if you asked for a ZIP archive or want to get the generated files, look for files named "ouds-docs".

The plugin produces a lot of files, a lot. For example for our v0.14.0, more than 27,000 files have been created for a ZIP archive of about +120 MB. Thus, keeping all versions of the documentation is a non-sense, no one will read it and it will increase the size of the branch in our VCS tool, consuming a lot of bandwidth, and reaching limits of Git to handle large amounts of file. We would like to avoid to force developers to define a specific Git configuration to handle such massive branch.

We prefer to build ZIP documentation and Xcode doccarchives to add as artifacts of releases. Thus, the online version of the documentation is for the last release, and each release in GitHub contains doccarchive files generated through Xcode and ZIP of HTML files picked from the gh-pages.

Clone this wiki locally