diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fbeead..bb6886c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,22 +5,27 @@ 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 +## How to Contribute -Please ensure to specify the following: +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. -* swift-prometheus commit hash -* Contextual information (e.g. what you were trying to achieve with swift-prometheus) -* 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 +For security concerns, please follow the private disclosure process outlined in the [SECURITY.md](SECURITY.md) file instead of opening a public issue. +### Reporting Bugs or Requesting Features -### Example +A great bug report or feature request is specific and actionable. Before submitting a new issue, please check if a similar one already exists. + +When you create a bug report, please provide the following: + +- **swift-prometheus commit hash** you are using. +- **Context**: What were you trying to achieve? +- **Steps to Reproduce**: Provide the simplest possible steps. A pull request with a failing test case is ideal. +- **Environment Details**: + - Swift version (`swift --version`) + - OS version (`uname -a`) + - Any other relevant configuration. + +#### Example ``` swift-prometheus commit hash: 22ec043dc9d24bb011b47ece4f9ee97ee5be2757 @@ -47,19 +52,56 @@ Linux beefy.machine 4.4.0-101-generic #124-Ubuntu SMP Fri Nov 10 18:29:59 UTC 20 My system has IPv6 disabled. ``` -## Writing a Patch +### Submitting Code Contributions + +#### The Development Workflow + +1. **Fork & Clone**: Fork the repository and clone it to your local machine. + + ```bash + git clone https://github.com/YOUR_USERNAME/swift-prometheus.git + cd swift-prometheus + ``` + +2. **Create a Branch**: Create a descriptive branch for your changes (e.g., `fix/counter-overflow` or `feature/new-exporter`). + + ```bash + git checkout -b fix/counter-overflow + ``` + +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. + +4. **Run Checks Locally**: Before pushing, validate your changes by running the project's automated checks on your local machine. + - **Run Unit Tests**: This is the most fundamental check to ensure your changes haven't broken existing functionality. + + ```bash + swift test + ``` + + - **Check Code Formatting**: We use `swift-format` to maintain a consistent code style. Run the following command to verify your code is formatted correctly. + + ```bash + curl -s --retry 3 https://raw.githubusercontent.com/swiftlang/github-workflows/refs/heads/main/.github/workflows/scripts/check-swift-format.sh | bash + ``` + + - **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 for catching issues that only appear in the CI environment. + - 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). + - You can run an entire workflow or target a specific job. For example, to run only the `soundness` check: + ```bash + act pull_request --job soundness + ``` + - You can find the names of all available jobs to target in our [pull_request.yml](.github/workflows/pull_request.yml) file. -A good swift-prometheus patch is: +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. -1. Concise, and contains as few changes as needed to achieve the end result. -2. Tested, ensuring that any tests provided failed before the patch and pass after it. -3. Documented, adding API documentation as needed to cover new functions and properties. -4. Accompanied by a great commit message, using our commit message template. +6. **Open a Pull Request**: Open a PR against the `main` branch. Link any relevant issues in your PR description (e.g., `Fixes #123`). -### Run CI checks locally +#### Pull Request Guidelines -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). +For a smooth review process, your PR should be: -## How to contribute your work +- **Atomic**: Address a single, focused issue or feature. +- **Tested**: Include tests that prove your change works. +- **Documented**: Add DocC comments for any new public APIs. -Please open a pull request at https://github.com/swift-server/swift-prometheus. Make sure the CI passes, and then wait for code review. +Once submitted, a maintainer will review your code, provide feedback, and merge it once it's approved. Thank you for your contribution! diff --git a/README.md b/README.md index 73e0349..5f7101e 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,9 @@ # Swift Prometheus [![sswg:sandbox](https://img.shields.io/badge/sswg-sandbox-yellow.svg)][SSWG-Incubation] -[![Documentation](http://img.shields.io/badge/read_the-docs-2196f3.svg)][Documentation] +[![Documentation](http://img.shields.io/badge/read_the-docs-2196f3.svg)][Documentation] +[![Supported Swift Versions](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fswift-server%2Fswift-prometheus%2Fbadge%3Ftype%3Dswift-versions)](https://swiftpackageindex.com/swift-server/swift-prometheus) +[![Supported Platforms](https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fswift-server%2Fswift-prometheus%2Fbadge%3Ftype%3Dplatforms)](https://swiftpackageindex.com/swift-server/swift-prometheus) A Swift client library for [Prometheus Monitoring System](https://github.com/prometheus/prometheus). @@ -11,7 +13,7 @@ This can also be used a backend implementation for [Swift Metrics](https://githu ## Installation and Usage -Please refer to the [Documentation][Documentation] for installation, usage instructions, and implementation details including Prometheus standards compliance. +Please see the `swift-prometheus` [DocC Documentation][Documentation] for details on installation, usage, implementation, and Prometheus standards compliance. For general Prometheus guidance, see [Prometheus Monitoring System][prometheus-docs]. @@ -21,11 +23,11 @@ Please see [SECURITY.md](SECURITY.md) for details on the security process. ## Contributing -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. +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. ## Benchmarks -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: +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: ``` swift package benchmark @@ -33,7 +35,6 @@ swift package benchmark For more information please refer to `swift package benchmark --help` or the [`package-benchmark` Documentation](https://swiftpackageindex.com/ordo-one/package-benchmark/documentation/benchmark). - [Documentation]: https://swiftpackageindex.com/swift-server/swift-prometheus/documentation/prometheus [prometheus-docs]: https://prometheus.io/docs/introduction/overview/ [SSWG-Incubation]: https://www.swift.org/sswg/incubation-process.html