This is an automated email from the ASF dual-hosted git repository. hgruszecki pushed a commit to branch contributing-guidelines in repository https://gitbox.apache.org/repos/asf/iggy.git
commit 7d2b0d8132e13e51344eeda1cac005663762b682 Author: Hubert Gruszecki <[email protected]> AuthorDate: Wed Jan 21 23:46:03 2026 +0100 docs: update PR template and contributing guidelines --- .markdownlint.json | 3 +- .markdownlint.yml | 2 +- CONTRIBUTING.md | 141 +++++++++++++++++++++++------------------------ PULL_REQUEST_TEMPLATE | 33 ----------- PULL_REQUEST_TEMPLATE.md | 57 +++++++++++++++++++ 5 files changed, 128 insertions(+), 108 deletions(-) diff --git a/.markdownlint.json b/.markdownlint.json index 7885f5e4b..f611f8daa 100644 --- a/.markdownlint.json +++ b/.markdownlint.json @@ -5,5 +5,6 @@ }, "MD024": { "siblings_only": true - } + }, + "MD041": false } diff --git a/.markdownlint.yml b/.markdownlint.yml index 88d9d9b03..1af3ea22a 100644 --- a/.markdownlint.yml +++ b/.markdownlint.yml @@ -21,4 +21,4 @@ MD013: tables: false MD033: allowed_elements: [details, summary, img] -MD041: false # First line in file should be a top level heading +MD041: false diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8964a23e9..4316959b2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,111 +1,106 @@ -# Contributing +# Contributing to Apache Iggy -First, thank you for contributing to Iggy! The goal of this document is to provide everything you need to start contributing to Iggy. The following TOC is sorted progressively, starting with the basics and expanding into more specifics. +## Issue First -## Your First Contribution +Every new PR that introduces new functionality must link to an approved issue. +PRs without one may be closed at maintainer's discretion. -1. Ensure your change has an issue! Find an [existing issue](https://github.com/apache/iggy/issues) or open a new issue. -2. [Fork the Iggy repository](https://github.com/apache/Iggy/fork) in your own GitHub account. -3. [Create a new Git branch](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository). -4. Make your changes. -5. [Submit the branch as a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) to the master Iggy repo. An Iggy team member should comment and/or review your pull request within a few days. Although, depending on the circumstances, it may take longer. +1. Create an issue or comment under existing +2. Wait for maintainer approval (`good-first-issue` label or comment) + - Maintainer may request for more details or a different approach +3. Then code -## Workflow +## Size Limits -### Git Branches +For new contributors we require to keep PRs under 500 lines of code, unless explicitly approved by a maintainer under linked issue. -*All* changes must be made in a branch and submitted as [pull requests](#github-pull-requests). Iggy does not adopt any type of branch naming style, but please use something descriptive of your changes. +## High-Risk Areas -### GitHub Pull Requests +These require design discussion in the issue before coding: -Once your changes are ready you must submit your branch as a [pull request](https://github.com/apache/Iggy/pulls). +- Persistence (segments, indexes, state, crash recovery) +- Protocol (binary format, wire encoding) +- Concurrency (shards, inter-shard) +- Public API (HTTP, SDKs, CLI) +- Connectors -#### Title +## PR Requirements -The pull request title must follow the format outlined in the [conventional commits spec](https://www.conventionalcommits.org). [Conventional commits](https://www.conventionalcommits.org) is a standardized format for commit messages. Iggy only requires this format for commits on the `master` branch. And because Iggy squashes commits before merging branches, this means that only the pull request title must conform to this format. +### Run It Locally -The following are all good examples of pull request titles: +**If you can't run it, you can't submit it.** -```text -fix(ci): add Cross.toml for CI builds -chore(repo): add ASF license header to all the files -refactor(server): remove redundant sha1 print -chore(docs): add contributing guide -refactor(server): remove redundant sha1 print -``` - -#### Reviews & Approvals - -All pull requests should be reviewed by at least two Iggy committers. - -#### Merge Style - -All pull requests are squash merged. -We generally discourage large pull requests that are over 300–500 lines of diff. -If you would like to propose a change that is larger, we suggest -coming onto our [Discussions](https://github.com/apache/Iggy/discussions) and discussing it with us. -This way we can talk through the solution and discuss if a change that large is even needed! -This will produce a quicker response to the change and likely produce code that aligns better with our process. - -### CI - -Currently, Iggy uses GitHub Actions to run tests. The workflows are defined in `.github/workflows`. +Authors of PRs must run the code locally. "Relying on CI" is not acceptable. -## Setup +### Single Purpose -### Bring your own toolbox +One PR = one thing. Bug fix, refactor, feature - separate PRs. Mixed PRs will be closed. -Iggy is primarily a Rust project. To build Iggy, you will need to set up Rust development first. We highly recommend using [rustup](https://rustup.rs/) for the setup process. +### Quality Checks -For Linux or macOS, use the following command: +For Rust code: -```shell -curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +```bash +cargo fmt --all +cargo clippy --all-targets --all-features -- -D warnings +cargo build +cargo test +cargo machete +cargo sort --workspace ``` -For Windows, download `rustup-init.exe` from [the Windows installer](https://win.rustup.rs/x86_64) instead. +For other languages, check the README in `foreign/{language}/` (e.g., `foreign/go/`, `foreign/java/`). -Rustup will read Iggy's `Cargo.toml` and set up everything else automatically. To ensure that everything works correctly, run `cargo version` under Iggy's root directory: +### Pre-commit Hooks -```shell -$ cargo version -cargo 1.86.0 (adf9b6ad1 2025-02-28) +We use [prek](https://github.com/j178/prek): + +```bash +cargo install prek +prek install ``` -### Pre-commit Hooks (Recommended) +## Code Style -Iggy uses [prek](https://github.com/9999years/prek) for pre-commit hooks to ensure code quality before commits. Setting up hooks is optional but strongly recommended to catch issues early. +### Comments: WHY, Not WHAT -#### Setup +```rust +// Bad: Increment counter +counter += 1; -```shell -cargo install prek -prek install +// Good: Offset by 1 because segment IDs are 1-indexed in the wire protocol +counter += 1; ``` -This will install git hooks that automatically run on `pre-commit` and `pre-push` events. +Don't comment obvious code. Do explain non-obvious decisions, invariants, and constraints. -#### Manual hook execution +### Commit Messages -You can manually run specific hooks: +Format: `type(scope): subject` -```shell -# Run all pre-commit hooks -prek run +**Good examples from this repo:** -# Run specific hook -prek run cargo-fmt -prek run cargo-clippy +```none +fix(server): prevent panic when segment rotates during async persistence +fix(server): chunk vectored writes to avoid exceeding IOV_MAX limit +feat(server): add SegmentedSlab collection +refactor(server): consolidate permissions into metadata crate +chore(integration): remove streaming tests superseded by API-level coverage ``` -#### Skip hooks (when necessary) +Keep subject under 72 chars. Use body for details if needed. -If you need to skip hooks for a specific commit: +## Close Policy -```shell -git commit --no-verify -m "your message" -``` +PRs may be closed if: + +- Maintainer feels like proxy between maintainer and LLM +- No approved issue or no approval from a maintainer +- Code not ran and tested locally +- Mixed purposes or purposes not clear +- Can't answer questions about the change +- Inactivity for longer than 7 days -## How to build +## Questions? -See [Quick Start](https://github.com/apache/iggy?tab=readme-ov-file#quick-start) +[Discussions](https://github.com/apache/iggy/discussions) or [Discord](https://discord.gg/apache-iggy) diff --git a/PULL_REQUEST_TEMPLATE b/PULL_REQUEST_TEMPLATE deleted file mode 100644 index fe56a96ba..000000000 --- a/PULL_REQUEST_TEMPLATE +++ /dev/null @@ -1,33 +0,0 @@ -# **PR Submission Guidelines** - -**Please remove this entire section before submitting your PR.** -**This section is only for your reference.** - -🙌 **Thank you for contributing to `iggy`!** - -To help us incorporate your changes efficiently, please adhere to the following guidelines: - -## General Coding Remarks - -- **Code Formatting**: Run `cargo fmt` to ensure your code adheres to the project's style. -- **Code Linting**: Run `cargo clippy --all-targets --all-features -- -D warnings` to make sure your code is lint-free. -- **Unit Testing**: Write or update unit tests to cover your changes. -- **Integration Testing**: Write or update integration tests to cover your changes. -- **Project Structure**: Follow the `iggy` project's structure and coding style. -- **Build Integrity**: Ensure your code compiles and runs error-free. -- **Check unused dependencies**: Run `cargo machete` to make sure no unused dependencies made their way into your changeset. -- **Sort dependencies**: Run `cargo sort --workspace` so that the content of the toml files stay ordered. - -## Commit Message Rules - -- **Description**: Provide a concise description of the changes. -- **Style**: Use an imperative style in the subject line (e.g., "Fix bug" rather than "Fixed bug" or "Fixes bug"). -- **Brevity**: Keep the subject line under 80 characters. -- **Rationale**: Explain the 'why' and 'what' of your changes in the summary. -- **Details**: Use the body to elaborate on the 'how' of your changes. -- **Context**: Include 'before' and 'after' scenarios if applicable. -- **References**: Link any relevant issues or PRs in the message body. - -**Remember:** Your contribution is essential to the success of `iggy`. Please ensure that your PR conforms to these guidelines for a swift and smooth integration process. - -Thank you! diff --git a/PULL_REQUEST_TEMPLATE.md b/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 000000000..75b162919 --- /dev/null +++ b/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,57 @@ +## Which issue does this PR close? + +<!-- +We generally require a GitHub issue to be filed for all bug fixes and enhancements. You can link an issue to this PR using the GitHub syntax. For example `Closes #123` indicates that this PR will close issue #123. +--> + +Closes # + +## Rationale + +<!-- +Why is this change needed? If the issue explains it well, a one-liner is fine. +--> + +## What changed? + +<!-- +2-4 sentences. Problem first (before), then solution (after). + +GOOD: + +"Messages were unavailable when background message_saver committed the +journal and started async disk I/O before completion. Polling during +this window found neither journal nor disk data. + +The fix freezes journal batches in the in-flight buffer before async persist." + +GOOD: + +"When many small messages accumulate in the journal, the flush passes +thousands of IO vectors to writev(), exceeding IOV_MAX (1024 on Linux)." + +BAD: +- Walls of text +- "This PR adds..." (we can see the diff) +--> + +## Local Execution + +Not passed / passed. + +<!-- +You must run your code locally before submitting. +"Relying on CI" is not acceptable - PRs from authors who haven't run the code will be closed. +--> + +## AI Usage + +<!-- +If AI tools were used, please answer: +1. Which tools? (e.g., GitHub Copilot, Claude, ChatGPT) +2. Scope of usage? (e.g., autocomplete, generated functions, entire implementation) +3. How did you verify the generated code works correctly? +4. Can you explain every line of the code if asked? + +If no AI tools were used, write "None" or delete this section. +-->
