Skip to content

Latest commit

 

History

History
199 lines (143 loc) · 6.58 KB

CONTRIBUTING.md

File metadata and controls

199 lines (143 loc) · 6.58 KB
Raw

Contributing to swift-testing

There are many ways to contribute to this project. If you are making changes that do not materially affect the user-facing semantics of swift-testing, such as fixing bugs or writing documentation, feel free to open a pull request (PR) directly.

Larger changes that do materially change the semantics of swift-testing, such as new APIs or modifications to existing APIs, must undergo community discussion prior to being accepted.

Important

Since this package is currently experimental, a formal process for proposing and reviewing significant changes has not yet been established. Until that happens, please start a new discussion thread on the Swift forums about any such changes prior to submitting a PR.

To learn how to write tests using the testing library, rather than how to contribute to the testing library itself, see Getting Started.

Reporting issues

Issues are tracked using the testing library's GitHub Issue Tracker.

Fill in the fields of the relevant template form offered on that page when creating new issues. For bug report issues, please include a minimal example which reproduces the issue. Where possible, attach the example as a Swift package, or include a URL to the package hosted on GitHub or another public hosting service.

Setting up the development environment

First, clone the swift-testing repository from https://github.com/apple/swift-testing.

If you are preparing to make a contribution, you should fork the repository first and clone the fork which will make opening PRs easier.

Using Xcode (easiest)

  1. Install the latest beta or release Xcode from https://developer.apple.com/xcode.
  2. Open the Package.swift file from the cloned swift-testing repository in Xcode.
  3. Select the swift-testing-Package scheme (if not already selected) and the "My Mac" run destination.
  4. Use Xcode to inspect, edit, build, or test the code.

Using the command line

If you are using macOS and have Xcode installed, you can use Swift from the command line immediately.

If you are not using macOS or do not have Xcode installed, you need to download and install a toolchain.

Installing a toolchain

  1. Download a toolchain. A recent trunk development snapshot toolchain is required to build the testing library. Visit swift.org and download the most recent toolchain from the section titled Snapshots — Trunk Development (main).

    Be aware that development snapshot toolchains are not intended for day-to-day development and may contain defects that affect the programs built with them.

  2. Install the toolchain and confirm it can be located successfully:

    macOS with Xcode installed:

    $> export TOOLCHAINS=swift
$> xcrun --find swift
/Library/Developer/Toolchains/swift-latest.xctoolchain/usr/bin/swift

    Non-macOS or macOS without Xcode:

    $> export PATH=/path/to/swift-toolchain/usr/bin:"${PATH}"
$> which swift
/path/to/swift-toolchain/usr/bin/swift

Local development

With a Swift toolchain installed and the swift-testing repository cloned, you are ready to make changes and test them locally.

Building

$> swift build

Testing

$> swift test

Using Docker on macOS to test for Linux

  1. Install Docker Desktop for Mac.

  2. Run the following command from the root of this repository to build the Docker image:

    $> docker build -t swift-testing:latest .

  3. Run the following command to run the test suite:

    $> docker run -v "$(pwd)":/swift-testing -w /swift-testing swift-testing swift test --skip-update

  4. To interactively run the test suite or do other development, first log into the container with:

    $> docker run -i -t -v "$(pwd)":/swift-testing swift-testing /bin/bash

    And then run swift test or other commands within the container:

    $> cd /swift-testing
$> swift test

Creating Pull Requests (PRs)

  1. Fork https://github.com/apple/swift-testing.
  2. Clone a working copy of your fork.
  3. Create a new branch.
  4. Make your code changes.
  5. Commit your changes. Include a description of the changes in the commit message, followed by the GitHub Issue ID or Apple Radar link if there is one.
  6. Push your changes to your fork.
  7. Create a PR from the branch on your fork targeting the main branch of the original repository.
  8. Follow the PR template to provide information about the motivation and details of the changes.

Reviewers will be automatically added to the PR once it is created. The PR will be merged by the maintainers after it passes continuous integration (CI) testing and receives approval from one or more reviewers. Merge timing may be impacted by release schedule considerations.

By submitting a PR, you represent that you have the right to license your contribution to Apple and the community, and agree by submitting the patch that your contributions are licensed under the Swift license.

Continuous integration

swift-testing uses the swift-ci infrastructure for its continuous integration (CI) testing. The bots can be triggered on PRs if you have commit access. Otherwise, ask one of the code owners to trigger them for you.

To request CI, add a comment in the PR containing:

@swift-ci test

Code style

Code should use two spaces for indentation. Block comments including markup should be limited to 80 columns.

Refer to the testing library's documentation style guide for more information.

Community and support

To connect with the Swift community:

Additional resources