Contributing to Relay.swift

So far, Relay.swift is mostly developed by Matt Moriarity. But if you're interested, you are welcome to contribute too! This page is intended to help you get up to speed on how to develop on Relay.swift.

Building and testing

Swift code

You can generally using any SwiftPM tooling to develop on the Relay.swift package. This includes the swift CLI as well as Xcode's built-in support for opening SwiftPM packages as projects.

There are currently four source targets in the package:

• Relay: the core code to implement Relay, independent of UI framework
• RelaySwiftUI: SwiftUI-specific support for Relay
• RelayTestHelpers: shared code that is used by tests for both Relay and RelaySwiftUI
• find-graphql-tags: a CLI tool that is packaged with the relay-compiler JS plugin to discover GraphQL tagged strings in sources

The first two source targets also have corresponding test targets. You can run these tests either in Xcode or with swift test.

There are also three example apps which demonstrate how to use RelaySwiftUI in practice. These apps are contained in the RelayExamples.xcodeproj Xcode project. This project is configured to use the Relay.swift package in the working copy.

TypeScript code

Relay.swift also contains a plugin for the relay-compiler to allow it to generate Swift code. This is an npm package in the relay-compiler-language-swift directory.

The package includes Jest tests that can be run using npm test in that directory.

To build a production version of the compiler plugin, run npm run build. In addition to compiling and bundling the TypeScript code, this will also build the find-graphql-tags CLI tool and copy it into the dist directory alongside the compiled JavaScript. This tool is needed when running the Relay compiler.

While developing changes to the compiler plugin, run npm start to watch for changes and rebuild a development version when you edit sources.

Running npm start first cleans the dist directory, so once it's up and running, you'll also need to run npm run prepublishOnly to build and copy find-graphql-tags into the dist directory in order for the compiler to actually work with your local copy of the plugin.

The RelayTestHelpers package and the example apps all include code that is generated by the Relay compiler. If you change the compiler plugin, you should also regenerate this code by running npm run relay in the root of the Relay.swift package. If you forget to do this, don't worry: a GitHub action will detect this and automatically commit any necessary changes.

Working on the compiler plugin (specifically building find-graphql-tags) requires either Xcode 11.4 or Xcode 11.5, due to the pinned version of SwiftSyntax that we are using. If this is not your default Xcode version, you can set the DEVELOPER_DIR environment variable when working on the compiler plugin to override it. If you build with the wrong Xcode version, the Relay compiler will fail at runtime.

Releasing a new version

note

This section needs to updated based on the new Docusaurus-based website.

This isn't currently something that other contributors besides Matt can do, but it's documented here anyway for completeness.

Before releasing a new version, prepare a new page for it under Release Notes that is tagged as "Unreleased". You can take your time preparing the notes.

Once the notes are ready, the process for releasing a new version is largely automated:

• Go to the Release action on GitHub and click the "Run worklow" button
• Enter the new version number that is going to be released
• Wait for the action to:
  • Publish the new compiler plugin to npm
  • Commit and tag the change under the new version
  • Push the tag
• When the tag is pushed, another action should trigger that creates a new GitHub release for the tag. Edit the release to include a link to the version's release notes page on Notion
• Remove the "Unreleased" tag from the version's release notes page
• Set the "Release date" for the page to the current date
• Lock the page so it can't be changed
• Update the "Latest version:" on Relay.swift to point to the new version's page
• Announce it!