mirror of
https://github.com/apple/swift-log
synced 2026-11-22 03:40:39 +00:00
I updated the `CONTRIBUTING.md` documentation to fix the outdated name for the benchmarking plugin. The instructions now reference the `benchmark` plugin instead of the previously outdated `package-benchmark` plugin, and associated links and descriptions have been updated accordingly. Previously these were leading to `404 Not Found` errors. No code changes were made in this PR. Fixes: #510 --------- Co-authored-by: Vladimir Kukushkin <kukushechkin@mac.com>
116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
## Legal
|
|
|
|
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](https://github.com/nektos/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 [`benchmark`](https://github.com/ordo-one/benchmark) plugin.
|
|
On Swift versions prior to 6.3 Benchmarks depends on the [`jemalloc`](https://jemalloc.net) memory allocation library, which is used by `benchmark` to capture memory allocation statistics.
|
|
An installation guide can be found in the [Getting Started article](https://swiftpackageindex.com/ordo-one/benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) of `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 `benchmark`](https://swiftpackageindex.com/ordo-one/benchmark/documentation/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](Sources/Logging/Docs.docc/Proposals/Proposals.md) 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.
|
|
2. 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](https://github.com/apple/swift-temporal-sdk/blob/main/.github/workflows/README.md) for details.
|