Skip to content

update: README.md and CONTRIBUTING.md #149

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

update: README.md and CONTRIBUTING.md #149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 64 additions & 22 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All great detail, and we should include a PR template that specifically asks for this detail as well

- **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
Expand All @@ -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).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tried the whole sequence with act and really struggled to get it working with anything OTHER than docker-desktop - I love the concept of describing this and providing a means to check the workflows locally, but it was particularly cranky for me.

I'm not immediately clear on what other options there might be, or how to make that process work a bit more smoothly - say for example, using container instead of docker and what might need to exist to arrange that. That's probably beyond the scope of this edit though.

- 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!
11 changes: 6 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).

Expand All @@ -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].

Expand All @@ -21,19 +23,18 @@ 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
```

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
Loading