CONTRIBUTING.md

April 28, 2026 ยท View on GitHub

By submitting a pull request, 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 Apache 2.0 license (see LICENSE.txt).

How to submit a bug report

Please ensure to specify the following:

  • SwiftLog commit hash
  • Contextual information (e.g. what you were trying to achieve with SwiftLog)
  • Simplest possible steps to reproduce
    • More complex the steps are, lower the priority will be.
    • A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description.
  • Anything that might be relevant in your opinion, such as:
    • Swift version or the output of swift --version
    • OS version and the output of uname -a
    • Network configuration

Example

SwiftLog commit hash: 4fe877816ad82627602377f415b6a66850214824

Context:
While testing my application that uses with SwiftLog, I noticed that ...

Steps to reproduce:
1. ...
2. ...
3. ...
4. ...

$ swift --version
Swift version 4.0.2 (swift-4.0.2-RELEASE)
Target: x86_64-unknown-linux-gnu

Operating system: Ubuntu Linux 16.04 64-bit

$ uname -a
Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 2017 x86_64 x86_64 x86_64 GNU/Linux

My system has IPv6 disabled.

Make sure Tests work on Linux

SwiftLog uses Swift Testing to run tests on all supported platforms.

Run CI checks locally

You can run the Github Actions workflows locally using act. To run all the jobs that run on a pull request, use the following command:

% act pull_request

To run just a single job, use workflow_call -j <job>, and specify the inputs the job expects. For example, to run just shellcheck:

% act workflow_call -j soundness --input shell_check_enabled=true

To bind-mount the working directory to the container, rather than a copy, use --bind. For example, to run just the formatting, and have the results reflected in your working directory:

% act --bind workflow_call -j soundness --input format_check_enabled=true

If you'd like act to always run with certain flags, these can be be placed in an .actrc file either in the current working directory or your home directory, for example:

--container-architecture=linux/amd64
--remote-name upstream
--action-offline-mode

Benchmarks

Benchmarks for swift-log are in a separate Swift Package in the Benchmarks subfolder of this repository. They use the package-benchmark plugin. Benchmarks depends on the jemalloc memory allocation library, which is used by package-benchmark to capture memory allocation statistics. An installation guide can be found in the Getting Started article of package-benchmark. Afterwards you can run the benchmarks from CLI by going to the Benchmarks subfolder (e.g. cd Benchmarks) and invoking:

swift package benchmark

For more information please refer to swift package benchmark --help or the documentation of package-benchmark.

How to contribute your work

For non-trivial changes that affect the public API, it is good practice to have a discussion phase before writing code. Please follow the proposal process to gather feedback and align on the approach with other contributors.

  1. Prepare your change, keeping in mind that a good patch is:
  • Concise, and contains as few changes as needed to achieve the end result.
  • Tested, ensuring that any tests provided failed before the patch and pass after it.
  • Documented, adding API documentation as needed to cover new functions and properties.
  • Accompanied by a great commit message.
  1. Open a pull request at https://github.com/apple/swift-log and wait for code review by the maintainers.

Automated release process

This repository uses automated releases based on semantic versioning labels. See the Auto Release Workflow documentation for details.