From a4cf2c29e26b66b1bb28a548d6bad598f7ae38ee Mon Sep 17 00:00:00 2001 From: Nikita Vasilev Date: Sat, 13 Dec 2025 12:07:39 +0400 Subject: [PATCH 1/5] chore: update `README.md` --- README.md | 326 ++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 294 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index 5bc9d39..5fedb4e 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -![Typhoon: a service for retry policies](https://raw.githubusercontent.com/space-code/typhoon/dev/Resources/typhoon.png) +![A powerful retry policy service for Swift](./Resources/typhoon.png)

typhoon

@@ -6,25 +6,96 @@ License Swift Compatibility Platform Compatibility -CI +CI

## Description -`Typhoon` is a service for retry policies. +Typhoon is a modern, lightweight Swift framework that provides elegant and robust retry policies for asynchronous operations. Built with Swift's async/await concurrency model, it helps you handle transient failures gracefully with configurable retry strategies. + +## Features + +โœจ **Multiple Retry Strategies** - Constant, exponential, and exponential with jitter +โšก **Async/Await Native** - Built for modern Swift concurrency +๐ŸŽฏ **Type-Safe** - Leverages Swift's type system for compile-time safety +๐Ÿ”ง **Configurable** - Flexible retry parameters for any use case +๐Ÿ“ฑ **Cross-Platform** - Works on iOS, macOS, tvOS, watchOS, and visionOS +โšก **Lightweight** - Minimal footprint with zero dependencies +๐Ÿงช **Well Tested** - Comprehensive test coverage + +## Table of Contents -- [Usage](#usage) - [Requirements](#requirements) - [Installation](#installation) +- [Quick Start](#quick-start) +- [Usage](#usage) + - [Retry Strategies](#retry-strategies) + - [Constant Strategy](#constant-strategy) + - [Exponential Strategy](#exponential-strategy) + - [Exponential with Jitter Strategy](#exponential-with-jitter-strategy) +- [Common Use Cases](#common-use-cases) +- [Error Handling](#error-handling) - [Communication](#communication) - [Contributing](#contributing) + - [Development Setup](#development-setup) - [Author](#author) - [License](#license) +## Requirements + +| Platform | Minimum Version | +|-----------|----------------| +| iOS | 13.0+ | +| macOS | 10.15+ | +| tvOS | 13.0+ | +| watchOS | 6.0+ | +| visionOS | 1.0+ | +| Xcode | 15.3+ | +| Swift | 5.10+ | + +## Installation + +### Swift Package Manager + +Add the following dependency to your `Package.swift`: + +```swift +dependencies: [ + .package(url: "https://github.com/space-code/typhoon.git", from: "1.3.0") +] +``` + +Or add it through Xcode: + +1. File > Add Package Dependencies +2. Enter package URL: `https://github.com/space-code/typhoon.git` +3. Select version requirements + +## Quick Start + +```swift +import Typhoon + +let retryService = RetryPolicyService( + strategy: .constant(retry: 3, duration: .seconds(1)) +) + +do { + let result = try await retryService.retry { + try await fetchDataFromAPI() + } + print("โœ… Success: \(result)") +} catch { + print("โŒ Failed after retries: \(error)") +} +``` + ## Usage -`Typhoon` provides three retry policy strategies: +### Retry Strategies + +Typhoon provides three powerful retry strategies to handle different failure scenarios: ```swift /// A retry strategy with a constant number of attempts and fixed duration between retries. @@ -34,60 +105,251 @@ case constant(retry: Int, duration: DispatchTimeInterval) case exponential(retry: Int, multiplier: Double = 2.0, duration: DispatchTimeInterval) /// A retry strategy with exponential increase in duration between retries and added jitter. -case exponentialWithJitter(retry: Int, jitterFactor: Double = 0.1, maxInterval: UInt64? = 60, multiplier: Double = 2.0, duration: DispatchTimeInterval) +case exponentialWithJitter( + retry: Int, + jitterFactor: Double = 0.1, + maxInterval: UInt64? = 60, + multiplier: Double = 2.0, + duration: DispatchTimeInterval +) ``` -Create a `RetryPolicyService` instance and pass a desired strategy like this: +### Constant Strategy + +Best for scenarios where you want predictable, fixed delays between retries: ```swift import Typhoon -let retryPolicyService = RetryPolicyService(strategy: .constant(retry: 10, duration: .seconds(1))) +// Retry up to 5 times with 2 seconds between each attempt +let service = RetryPolicyService( + strategy: .constant(retry: 5, duration: .seconds(2)) +) do { - _ = try await retryPolicyService.retry { - // Some logic here ... - } + let data = try await service.retry { + try await URLSession.shared.data(from: url) + } } catch { - // Catch an error here ... + print("Failed after 5 attempts") } ``` -## Requirements +**Retry Timeline:** +- Attempt 1: Immediate +- Attempt 2: After 2 seconds +- Attempt 3: After 2 seconds +- Attempt 4: After 2 seconds +- Attempt 5: After 2 seconds -- iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+ -- Xcode 15.3 -- Swift 5.10 +### Exponential Strategy -## Installation -### Swift Package Manager +Ideal for avoiding overwhelming a failing service by progressively increasing wait times: -The [Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the `swift` compiler. It is in early development, but `typhoon` does support its use on supported platforms. +```swift +import Typhoon -Once you have your Swift package set up, adding `typhoon` as a dependency is as easy as adding it to the `dependencies` value of your `Package.swift`. +// Retry up to 4 times with exponentially increasing delays +let service = RetryPolicyService( + strategy: .exponential( + retry: 4, + multiplier: 2.0, + duration: .seconds(1) + ) +) + +do { + let response = try await service.retry { + try await performNetworkRequest() + } +} catch { + print("Request failed after exponential backoff") +} +``` + +**Retry Timeline:** +- Attempt 1: Immediate +- Attempt 2: After 1 second (1 ร— 2โฐ) +- Attempt 3: After 2 seconds (1 ร— 2ยน) +- Attempt 4: After 4 seconds (1 ร— 2ยฒ) + +### Exponential with Jitter Strategy + +The most sophisticated strategy, adding randomization to prevent thundering herd problems: ```swift -dependencies: [ - .package(url: "https://github.com/space-code/typhoon.git", .upToNextMajor(from: "1.3.0")) -] +import Typhoon + +// Retry with exponential backoff, jitter, and maximum interval cap +let service = RetryPolicyService( + strategy: .exponentialWithJitter( + retry: 5, + jitterFactor: 0.2, // Add ยฑ20% randomization + maxInterval: 30, // Cap at 30 seconds + multiplier: 2.0, + duration: .seconds(1) + ) +) + +do { + let result = try await service.retry { + try await connectToDatabase() + } +} catch { + print("Connection failed after sophisticated retry attempts") +} +``` + +**Benefits of Jitter:** +- Prevents multiple clients from retrying simultaneously +- Reduces load spikes on recovering services +- Improves overall system resilience + +## Common Use Cases + +### Network Requests + +```swift +import Typhoon + +class APIClient { + private let retryService = RetryPolicyService( + strategy: .exponential(retry: 3, duration: .milliseconds(500)) + ) + + func fetchUser(id: String) async throws -> User { + try await retryService.retry { + let (data, _) = try await URLSession.shared.data( + from: URL(string: "https://api.example.com/users/\(id)")! + ) + return try JSONDecoder().decode(User.self, from: data) + } + } +} +``` + +### Database Operations + +```swift +import Typhoon + +class DatabaseManager { + private let retryService = RetryPolicyService( + strategy: .exponentialWithJitter( + retry: 5, + jitterFactor: 0.15, + maxInterval: 60, + duration: .seconds(1) + ) + ) + + func saveRecord(_ record: Record) async throws { + try await retryService.retry { + try await database.insert(record) + } + } +} +``` + +### File Operations + +```swift +import Typhoon + +class FileService { + private let retryService = RetryPolicyService( + strategy: .constant(retry: 3, duration: .milliseconds(100)) + ) + + func writeFile(data: Data, to path: String) async throws { + try await retryService.retry { + try data.write(to: URL(fileURLWithPath: path)) + } + } +} +``` + +### Third-Party Service Integration + +```swift +import Typhoon + +class PaymentService { + private let retryService = RetryPolicyService( + strategy: .exponential( + retry: 4, + multiplier: 1.5, + duration: .seconds(2) + ) + ) + + func processPayment(amount: Decimal) async throws -> PaymentResult { + try await retryService.retry { + try await paymentGateway.charge(amount: amount) + } + } +} +``` + +## Error Handling + +Typhoon preserves the original error from your operation after all retry attempts are exhausted: + +```swift +import Typhoon + +let service = RetryPolicyService( + strategy: .constant(retry: 3, duration: .seconds(1)) +) + +do { + try await service.retry { + throw NetworkError.serverUnavailable + } +} catch let error as NetworkError { + // Handle specific error type + print("Network error: \(error)") +} catch { + // Handle other errors + print("Unexpected error: \(error)") +} ``` ## Communication -- If you **found a bug**, open an issue. -- If you **have a feature request**, open an issue. -- If you **want to contribute**, submit a pull request. + +- ๐Ÿ› **Found a bug?** [Open an issue](https://github.com/space-code/typhoon/issues/new) +- ๐Ÿ’ก **Have a feature request?** [Open an issue](https://github.com/space-code/typhoon/issues/new) +- โ“ **Questions?** [Start a discussion](https://github.com/space-code/typhoon/discussions) +- ๐Ÿ”’ **Security issue?** Email nv3212@gmail.com ## Contributing -Bootstrapping development environment -``` +We love contributions! Please feel free to help out with this project. If you see something that could be made better or want a new feature, open up an issue or send a Pull Request. + +### Development Setup + +Bootstrap the development environment: + +```bash make bootstrap ``` -Please feel free to help out with this project! If you see something that could be made better or want a new feature, open up an issue or send a Pull Request! - ## Author -Nikita Vasilev, nv3212@gmail.com + +**Nikita Vasilev** +- Email: nv3212@gmail.com +- GitHub: [@ns-vasilev](https://github.com/ns-vasilev) ## License -typhoon is available under the MIT license. See the LICENSE file for more info. + +Typhoon is released under the MIT license. See [LICENSE](https://github.com/space-code/typhoon/blob/main/LICENSE) for details. + +--- + +
+ +**[โฌ† back to top](#typhoon)** + +Made with โค๏ธ by [space-code](https://github.com/space-code) + +
\ No newline at end of file From b357c5a015ff8b4a3240081622754c6d7e04e2fa Mon Sep 17 00:00:00 2001 From: Nikita Vasilev Date: Sat, 13 Dec 2025 15:23:52 +0400 Subject: [PATCH 2/5] docs: add DocC documentation --- CODE_OF_CONDUCT.md | 151 +++-- CONTRIBUTING.md | 537 ++++++++++++++++-- Package.swift | 1 - Package@swift-5.10.swift | 1 - Package@swift-6.0.swift | 1 - Package@swift-6.1.swift | 1 - README.md | 6 +- .../Articles/advanced-retry-strategies.md | 381 +++++++++++++ .../Typhoon.docc/Articles/best-practices.md | 363 ++++++++++++ Sources/Typhoon.docc/Articles/installation.md | 19 + Sources/Typhoon.docc/Articles/quick-start.md | 191 +++++++ Sources/Typhoon.docc/Info.plist | 48 ++ Sources/Typhoon.docc/Overview.md | 23 + .../IRetryPolicyService.swift | 6 +- .../RetryPolicyService.swift | 8 +- 15 files changed, 1641 insertions(+), 96 deletions(-) create mode 100644 Sources/Typhoon.docc/Articles/advanced-retry-strategies.md create mode 100644 Sources/Typhoon.docc/Articles/best-practices.md create mode 100644 Sources/Typhoon.docc/Articles/installation.md create mode 100644 Sources/Typhoon.docc/Articles/quick-start.md create mode 100644 Sources/Typhoon.docc/Info.plist create mode 100644 Sources/Typhoon.docc/Overview.md diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 56c1661..e940fc4 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -2,73 +2,132 @@ ## Our Pledge -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to creating a positive environment -include: +Examples of behavior that contributes to a positive environment for our +community include: -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior by participants include: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery and unwelcome sexual attention or -advances -* Trolling, insulting/derogatory comments, and personal or political attacks +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission +* Publishing others' private information, such as a physical or email address, + without their explicit permission * Other conduct which could reasonably be considered inappropriate in a professional setting -## Our Responsibilities +## Enforcement Responsibilities -Project maintainers are responsible for clarifying the standards of acceptable -behavior and are expected to take appropriate and fair corrective action in -response to any instances of unacceptable behavior. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. -Project maintainers have the right and responsibility to remove, edit, or -reject comments, commits, code, wiki edits, issues, and other contributions -that are not aligned to this Code of Conduct, or to ban temporarily or -permanently any contributor for other behaviors that they deem inappropriate, -threatening, offensive, or harmful. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies both within project spaces and in public spaces -when an individual is representing the project or its community. Examples of -representing a project or community include using an official project e-mail -address, posting via an official social media account, or acting as an appointed -representative at an online or offline event. Representation of a project may be -further defined and clarified by project maintainers. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting one of the project maintainers https://github.com/orgs/space-code/people. All -complaints will be reviewed and investigated and will result in a response that -is deemed necessary and appropriate to the circumstances. The project team is -obligated to maintain confidentiality with regard to the reporter of an incident. -Further details of specific enforcement policies may be posted separately. +reported to the community leaders responsible for enforcement at +nv3212@gmail.com. + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning -Project maintainers who do not follow or enforce the Code of Conduct in good -faith may face temporary or permanent repercussions as determined by other -members of the project's leadership. +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, -available at [http://contributor-covenant.org/version/1/4][version] +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -[homepage]: http://contributor-covenant.org -[version]: http://contributor-covenant.org/version/1/4/ \ No newline at end of file +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 07f9cbd..43b90f4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,61 +1,518 @@ -# Contributing Guidelines +# Contributing to Typhoon -This document contains information and guidelines about contributing to this project. -Please read it before you start participating. +First off, thank you for considering contributing to Typhoon! It's people like you that make Typhoon such a great tool. -**Topics** +## Table of Contents -* [Reporting Issues](#reporting-issues) -* [Submitting Pull Requests](#submitting-pull-requests) -* [Developers Certificate of Origin](#developers-certificate-of-origin) -* [Code of Conduct](#code-of-conduct) +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) + - [Development Setup](#development-setup) + - [Project Structure](#project-structure) +- [How Can I Contribute?](#how-can-i-contribute) + - [Reporting Bugs](#reporting-bugs) + - [Suggesting Features](#suggesting-features) + - [Improving Documentation](#improving-documentation) + - [Submitting Code](#submitting-code) +- [Development Workflow](#development-workflow) + - [Branching Strategy](#branching-strategy) + - [Commit Guidelines](#commit-guidelines) + - [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) + - [Swift Style Guide](#swift-style-guide) + - [Code Quality](#code-quality) + - [Testing Requirements](#testing-requirements) +- [Community](#community) -## Reporting Issues +## Code of Conduct -A great way to contribute to the project is to send a detailed issue when you encounter a problem. We always appreciate a well-written, thorough bug report. +This project and everyone participating in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to nv3212@gmail.com. -Check that the project issues database doesn't already include that problem or suggestion before submitting an issue. If you find a match, feel free to vote for the issue by adding a reaction. Doing this helps prioritize the most common problems and requests. +## Getting Started -When reporting issues, please fill out our issue template. The information the template asks for will help us review and fix your issue faster. +### Development Setup -## Submitting Pull Requests +1. **Fork the repository** + ```bash + # Click the "Fork" button on GitHub + ``` -You can contribute by fixing bugs or adding new features. For larger code changes, we recommend first discussing your ideas on our [GitHub Discussions](https://github.com/space-code/typhoon/discussions). When submitting a pull request, please add relevant tests and ensure your changes don't break any existing tests. +2. **Clone your fork** + ```bash + git clone https://github.com/YOUR_USERNAME/typhoon.git + cd typhoon + ``` -## Developer's Certificate of Origin 1.1 +3. **Set up the development environment** + ```bash + # Bootstrap the project + make bootstrap + ``` -By making a contribution to this project, I certify that: +4. **Create a feature branch** + ```bash + git checkout -b feature/your-feature-name + ``` -- (a) The contribution was created in whole or in part by me and I - have the right to submit it under the open source license - indicated in the file; or +5. **Open the project in Xcode** + ```bash + open Package.swift + ``` -- (b) The contribution is based upon previous work that, to the best - of my knowledge, is covered under an appropriate open source - license and I have the right under that license to submit that - work with modifications, whether created in whole or in part - by me, under the same open source license (unless I am - permitted to submit under a different license), as indicated - in the file; or +## How Can I Contribute? -- (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified - it. +### Reporting Bugs -- (d) I understand and agree that this project and the contribution - are public and that a record of the contribution (including all - personal information I submit with it, including my sign-off) is - maintained indefinitely and may be redistributed consistent with - this project or the open source license(s) involved. +Before creating a bug report, please check the [existing issues](https://github.com/space-code/typhoon/issues) to avoid duplicates. -## Code of Conduct +When creating a bug report, include: + +- **Clear title** - Describe the issue concisely +- **Reproduction steps** - Detailed steps to reproduce the bug +- **Expected behavior** - What you expected to happen +- **Actual behavior** - What actually happened +- **Environment** - OS, Xcode version, Swift version +- **Code samples** - Minimal reproducible example +- **Error messages** - Complete error output if applicable + +**Example:** +```markdown +**Title:** ExponentialWithJitter strategy returns incorrect delay + +**Steps to reproduce:** +1. Create RetryPolicyService with exponentialWithJitter strategy +2. Set maxInterval to 30 seconds +3. Observe delays exceeding maxInterval + +**Expected:** Delays should never exceed 30 seconds +**Actual:** Delays can reach 60+ seconds + +**Environment:** +- iOS 16.0 +- Xcode 15.3 +- Swift 5.10 + +**Code:** +\`\`\`swift +let service = RetryPolicyService( + strategy: .exponentialWithJitter( + retry: 5, + maxInterval: .seconds(30), + duration: .seconds(1) + ) +) +\`\`\` +``` + +### Suggesting Features + +We love feature suggestions! When proposing a new feature, include: + +- **Problem statement** - What problem does this solve? +- **Proposed solution** - How should it work? +- **Alternatives** - What alternatives did you consider? +- **Use cases** - Real-world scenarios +- **API design** - Example code showing usage +- **Breaking changes** - Will this break existing code? + +**Example:** +```markdown +**Feature:** Add adaptive retry strategy + +**Problem:** Current strategies are static. Applications need dynamic adjustment based on error patterns. + +**Solution:** Add `.adaptive()` strategy that adjusts backoff based on success/failure rates. + +**API:** +\`\`\`swift +let service = RetryPolicyService( + strategy: .adaptive( + minRetry: 2, + maxRetry: 10, + adaptiveFactor: 1.5 + ) +) +\`\`\` + +**Use case:** Mobile app that needs aggressive retries on good connections but conservative retries on poor connections. +``` + +### Improving Documentation + +Documentation improvements are always welcome: + +- **Code comments** - Add/improve inline documentation +- **DocC documentation** - Enhance documentation articles +- **README** - Fix typos, add examples +- **Guides** - Write tutorials or how-to guides +- **API documentation** - Document public APIs + +### Submitting Code + +1. **Check existing work** - Look for related issues or PRs +2. **Discuss major changes** - Open an issue for large features +3. **Follow coding standards** - See [Coding Standards](#coding-standards) +4. **Write tests** - All code changes require tests +5. **Update documentation** - Keep docs in sync with code +6. **Create a pull request** - Use clear description -The Code of Conduct governs how we behave in public or in private -whenever the project will be judged by our actions. -We expect it to be honored by everyone who contributes to this project. +## Development Workflow -See [CODE_OF_CONDUCT.md](https://github.com/space-code/typhoon/blob/master/CODE_OF_CONDUCT.md) for details. +### Branching Strategy + +We use a simplified branching model: + +- **`main`** - Main development branch (all PRs target this) +- **`feature/*`** - New features +- **`fix/*`** - Bug fixes +- **`docs/*`** - Documentation updates +- **`refactor/*`** - Code refactoring +- **`test/*`** - Test improvements + +**Branch naming examples:** +```bash +feature/adaptive-retry-strategy +fix/exponential-jitter-calculation +docs/update-quick-start-guide +refactor/simplify-delay-calculation +test/add-retry-sequence-tests +``` + +### Commit Guidelines + +We use [Conventional Commits](https://www.conventionalcommits.org/) for clear, structured commit history. + +**Format:** +``` +(): + + + +