This is an automated email from the ASF dual-hosted git repository.
gkoszyk pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iggy.git
The following commit(s) were added to refs/heads/master by this push:
new 6e3a6d132 docs: update PR template and contributing guidelines (#2601)
6e3a6d132 is described below
commit 6e3a6d132a4aa7375959b436c552c100b2002455
Author: Hubert Gruszecki <[email protected]>
AuthorDate: Tue Jan 27 13:31:12 2026 +0100
docs: update PR template and contributing guidelines (#2601)
See https://github.com/apache/iggy/discussions/2602.
Co-authored-by: Maciej Modzelewski <[email protected]>
---
.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.
+-->
