# Instructions for AI Agents

## Overview

This is a Swift 6+ [client library](https://www.rabbitmq.com/client-libraries) for RabbitMQ heavily
inspired by Bunny (Ruby), Pika (Python), amqprs (Rust) and the .NET RabbitMQ client 7.x.


## Build and Test

```bash
swift build

swift-format format --recursive --in-place Sources Tests

swift test
```

To filter tests:

```bash
swift test --filter "TestClassName/testMethodName"
```

### Test Node Configuration

Test suites require a RabbitMQ node running on `localhost:5672` with default credentials (`guest`/`guest`).

RabbitMQ 4.x deprecates transient non-exclusive queues (`transient_nonexcl_queues`). Declaring a queue
with `durable: false` and `exclusive: false` causes the broker to close the connection with a protocol
error. Always use `durable: true`, `exclusive: true`, or `temporaryQueue()` in tests.


## Repository Layout

 * `Sources`: contains the Swift source code
 * `Tests`: contains tests
 * `tutorials`: a port of [executable RabbitMQ tutorials](http://github.com/rabbitmq/rabbitmq-tutorials)


## Code Style

 * Target Swift 6, iOS 18, iPad OS 18, macOS Sonoma
 * Use top-level `import` statements, never function-local imports
 * At the end of each task, format the entire codebase using [`swift-format`](https://github.com/swiftlang/swift-format)
 * Single line code comments go above the line being commented on, not at the end of the line

## Tests

Tests should be descriptive and easy to read. Use property-based tests for edge cases
in addition to unit tests.


## Comments

 * Only add important comments that express the non-obvious intent, both in tests and in the implementation
 * Keep the comments short
 * Pay attention to the grammar of your comments, including punctuation, full stops, articles, and so on
 * Do not add `()` to function names or references: use `VersionVector.decode` and not `VersionVector.decode()`


## Change Log

If asked to perform change log updates, consult and modify `CHANGELOG.md` and stick to its
existing writing style.


## Releases

### How to Roll (Produce) a New Release

Suppose the current development version in `CHANGELOG.md` has
a `## 0.N.0 (in development)` section at the top.

To produce a new release:

 1. Update the changelog: replace `(in development)` with today's date, e.g. `(Feb 20, 2026)`. Make sure all notable changes since the previous release are listed
 2. Commit with the message `0.N.0` (just the version number, nothing else)
 3. Tag the commit: `git tag 0.N.0`
 4. Bump the dev version: back on `main`, add a new `## 0.(N+1).0 (in development)` section to `CHANGELOG.md` with `No changes yet.` underneath
 5. Commit with the message `Bump dev version`
 6. Push: `git push && git push --tags`


## Git Instructions

 * Do not commit changes automatically without an explicit permission to do so
 * Never add yourself to the list of commit co-authors
 * Never mention yourself in commit messages in any way (no "Generated by", no AI tool links, etc)


## Style Guide

 * Never add full stops to Markdown list items


## After Completing a Task

After completing a task, look very carefully for gaps in the implementation, the test coverage,
missed opportunities to use modern Swift idioms, meaningful optimizations on the common code paths,
and more ways to lean on the Swift's expressive type system for additional safety.

Reducing duplication is good unless it makes the codebase more complex.

"There's nothing meaningful to improve" is an acceptable answer.