You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+64-22Lines changed: 64 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -5,22 +5,27 @@ your contribution to Apple and the community, and agree by submitting the patch
5
5
that your contributions are licensed under the Apache 2.0 license (see
6
6
`LICENSE.txt`).
7
7
8
-
## How to submit a bug report
8
+
## How to Contribute
9
9
10
-
Please ensure to specify the following:
10
+
Contributions to this project are welcome. You can help by opening an issue to report a bug or suggest a feature, or by submitting a pull request with code changes.
11
11
12
-
* swift-prometheus commit hash
13
-
* Contextual information (e.g. what you were trying to achieve with swift-prometheus)
14
-
* Simplest possible steps to reproduce
15
-
* More complex the steps are, lower the priority will be.
16
-
* A pull request with failing test case is preferred, but it's just fine to paste the test case into the issue description.
17
-
* Anything that might be relevant in your opinion, such as:
18
-
* Swift version or the output of `swift --version`
19
-
* OS version and the output of `uname -a`
20
-
* Network configuration
12
+
For security concerns, please follow the private disclosure process outlined in the [SECURITY.md](SECURITY.md) file instead of opening a public issue.
21
13
14
+
### Reporting Bugs or Requesting Features
22
15
23
-
### Example
16
+
A great bug report or feature request is specific and actionable. Before submitting a new issue, please check if a similar one already exists.
17
+
18
+
When you create a bug report, please provide the following:
19
+
20
+
-**swift-prometheus commit hash** you are using.
21
+
-**Context**: What were you trying to achieve?
22
+
-**Steps to Reproduce**: Provide the simplest possible steps. A pull request with a failing test case is ideal.
2. **Create a Branch**: Create a descriptive branch for your changes (e.g., `fix/counter-overflow` or `feature/new-exporter`).
67
+
68
+
```bash
69
+
git checkout -b fix/counter-overflow
70
+
```
71
+
72
+
3. **Write Code & Tests**: Make your changes. All new code must be accompanied by tests to prevent regressions. For changes that are performance-critical or security-sensitive, we also strongly encourage adding new benchmarks or fuzz tests.
73
+
74
+
4. **Run Checks Locally**: Before pushing, validate your changes by running the project's automated checks on your local machine.
75
+
- **Run Unit Tests**: This is the most fundamental check to ensure your changes haven't broken existing functionality.
76
+
77
+
```bash
78
+
swift test
79
+
```
80
+
81
+
- **Check Code Formatting**: We use `swift-format` to maintain a consistent code style. Run the following command to verify your code is formatted correctly.
- **Simulate CI Workflows (Optional)**: For a more comprehensive check, you can run the full GitHub Actions workflows locally using [act](https://github.com/nektos/act). This is useful forcatching issues that only appearin the CI environment.
88
+
- For detailed setup instructions, see the Swift project's guide on [Running Workflows Locally](https://github.com/swiftlang/github-workflows?tab=readme-ov-file#running-workflows-locally).
89
+
- You can run an entire workflow or target a specific job. For example, to run only the `soundness` check:
90
+
```bash
91
+
act pull_request --job soundness
92
+
```
93
+
- You can find the names of all available jobs to target in our [pull_request.yml](.github/workflows/pull_request.yml) file.
51
94
52
-
A good swift-prometheus patch is:
95
+
5. **Commit & Push**: Write a clear commit message following the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) standard, then push your branch to your fork.
53
96
54
-
1. Concise, and contains as few changes as needed to achieve the end result.
55
-
2. Tested, ensuring that any tests provided failed before the patch and pass after it.
56
-
3. Documented, adding API documentation as needed to cover new functions and properties.
57
-
4. Accompanied by a great commit message, using our commit message template.
97
+
6. **Open a Pull Request**: Open a PR against the `main` branch. Link any relevant issues in your PR description (e.g., `Fixes #123`).
58
98
59
-
###Run CI checks locally
99
+
#### Pull Request Guidelines
60
100
61
-
You can run the GitHub Actions workflows locally using [act](https://github.com/nektos/act). For detailed steps on how to do this please see [https://github.com/swiftlang/github-workflows?tab=readme-ov-file#running-workflows-locally](https://github.com/swiftlang/github-workflows?tab=readme-ov-file#running-workflows-locally).
101
+
For a smooth review process, your PR should be:
62
102
63
-
## How to contribute your work
103
+
- **Atomic**: Address a single, focused issue or feature.
104
+
- **Tested**: Include tests that prove your change works.
105
+
- **Documented**: Add DocC comments for any new public APIs.
64
106
65
-
Please open a pull request at https://github.com/swift-server/swift-prometheus. Make sure the CI passes, and then wait for code review.
107
+
Once submitted, a maintainer will review your code, provide feedback, and merge it once it's approved. Thank you for your contribution!
[](https://swiftpackageindex.com/swift-server/swift-prometheus)
A Swift client library for [Prometheus Monitoring System](https://github.com/prometheus/prometheus).
7
9
@@ -11,7 +13,7 @@ This can also be used a backend implementation for [Swift Metrics](https://githu
11
13
12
14
## Installation and Usage
13
15
14
-
Please refer to the [Documentation][Documentation] for installation, usage instructions, and implementation details including Prometheus standards compliance.
16
+
Please see the `swift-prometheus`[DocC Documentation][Documentation] for details on installation, usage, implementation, and Prometheus standards compliance.
15
17
16
18
For general Prometheus guidance, see [Prometheus Monitoring System][prometheus-docs].
17
19
@@ -21,19 +23,18 @@ Please see [SECURITY.md](SECURITY.md) for details on the security process.
21
23
22
24
## Contributing
23
25
24
-
We welcome all contributions to `swift-prometheus`! For feature requests or bug reports, please [create an issue](https://github.com/swift-server/swift-prometheus/issues/new) with detailed information including Swift version, platform, and reproduction steps. To contribute code, [fork this repo](https://github.com/swift-server/swift-prometheus/fork) and submit a pull request with tests and documentation updates.
26
+
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) to learn how you can help, or browse our [open issues](https://github.com/swift-server/swift-prometheus/issues) to find a place to start.
25
27
26
28
## Benchmarks
27
29
28
-
Benchmarks are located in the [Benchmarks](/Benchmarks/) subfolder and use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin. See the [Benchmarks Getting Started]((https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support)) guide for installation instructions. Run benchmarks by navigating to Benchmarks and executing:
30
+
Benchmarks are located in the [Benchmarks](/Benchmarks/) subfolder and use the [`package-benchmark`](https://github.com/ordo-one/package-benchmark) plugin. See the [Benchmarks Getting Started](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark/gettingstarted#Installing-Prerequisites-and-Platform-Support) guide for installation instructions. Run benchmarks by navigating to Benchmarks and executing:
29
31
30
32
```
31
33
swift package benchmark
32
34
```
33
35
34
36
For more information please refer to `swift package benchmark --help` or the [`package-benchmark` Documentation](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark).
0 commit comments