IGNITE-29201 Add RFC on public API changes by anton-vinogradov · Pull Request #13740 · apache/ignite

anton-vinogradov · 2026-10-23T19:54:02Z

Adds the first RFC defining public API scope and the review process for API, protocol, and storage changes. The RFC needs approval from three Ignite committers; the RFC and implementation are then merged together in one PR and one commit per ticket.

One RFC can cover several implementation tickets. It is merged with the first implementation PR, and linked tickets track the remaining work. The document also explains why protocol and storage changes need review and uses IEPs as a guide for the level of detail.

CONTRIBUTING links to the RFC directory and the review process; no manual index needs updating.

Jira: https://issues.apache.org/jira/browse/IGNITE-29201

Validation: documentation-only change; checked the diff, process consistency, links, and Apache license header. No code tests run.

zstan · 2026-10-26T05:22:20Z

+- User-facing configuration, including defaults.
+- Supported metrics, JMX interfaces, and system views.
+
+The same review requirement covers client and internode protocols and persistent data formats, including metadata, WAL, and snapshots.


plz clarify - why we need such a requirement ?

Because it's a public API too.
Discussable, but seems to be the truth.

For example, we expect that the next version will be able to use previous versions' data.

Are you mean ABi compatibility ? If so - seems we not discuss it. What 'data' is mean here ?
If you describe thw case when someone implement his own (for example) client and it need to work in times ... I don`t know, it`s questionable as for me and probably beyond this scope?

Why beyond this scope?
It's what makes the product stable and useful. And that's what we desire.

@zstan Thank you for your valuable question.

We want to reach several goals when define network protocol as public API:

Have an ability to easily implement RU process when nodes of different version works in one cluster. Nodes of different version must talk to each other in compatible way, so communication, discovery, idto protocols becomes public API.

Make thoughtful decisions on changes protocols as it very core part of Ignite. And paying less attention that required leads to huge tech debt that we was paying in pas year by refactoring that subsystem from very root.

vldpyatkov · 2026-10-26T10:19:24Z

+## Ticket → RFC PR → implementation
+
+1. Open a ticket describing the problem and proposed change.
+2. Open a PR adding `rfcs/IGNITE-<ticket>-<short-title>.md`. Link the ticket and PR to each other; use the ticket number instead of maintaining a separate RFC counter.


Do you mean in that case where a ticket fits the requirement to create an RFC, it would be implemented in two commits in the main branch (RFT + code implementation)?
Please clarify if it needs to modify other triggers, because before we always intended that we have one commit for a JIAR ticket.

It will be one PR for each Issue.
It will include the RFC and implementation.

vldpyatkov · 2026-10-26T10:27:23Z

+2. Open a PR adding `rfcs/IGNITE-<ticket>-<short-title>.md`. Link the ticket and PR to each other; use the ticket number instead of maintaining a separate RFC counter.
+3. Review the document in the PR. When ready for approval, share the proposed revision on the dev list and allow at least 72 hours for feedback. Keep the list informed of significant changes and concerns.
+4. Collect explicit approval of that revision from at least three different Ignite committers in the PR. Resolve outstanding technical objections and post the approval summary and outcome on the dev list before merging. Material revisions need renewed approval and review time.
+5. Merge the RFC before merging the public API changes. Implementation PRs link to it and follow normal code review and testing.


How could we distinguish the implemented RFTC from the one that only approved and merged?

Let's change to merge the RFC and implementation together?

Implementation can contain more that one issue

Should each extend the previous RFC if it changes the public behavior?

vldpyatkov · 2026-10-26T10:31:08Z

Could we clarify the expected level of implementation detail in an RFC?

Should it describe the public contract, including observable behavior and guarantees, or also the internal algorithms used to implement it? For example, a timeout proposal should specify what happens to an operation after the timeout expires, but must it also describe how timeouts are tracked internally?

anton-vinogradov · 2026-10-26T13:55:54Z

Could we clarify the expected level of implementation detail in an RFC?

Should it describe the public contract, including observable behavior and guarantees, or also the internal algorithms used to implement it? For example, a timeout proposal should specify what happens to an operation after the timeout expires, but must it also describe how timeouts are tracked internally?

RFC should be similar to the IEP. Let's do it this way and define explicit rules when we face issues.
Deal?

anton-vinogradov · 2026-10-26T16:09:09Z

Updated the PR according to the questions.

zstan · 2026-10-27T12:55:29Z

Just a bit joke: did you know that IgniteSQLException is internal - thus no need to discuss it`s changes )

anton-vinogradov · 2026-10-27T13:08:42Z

Just a bit joke: did you know that IgniteSQLException is internal - thus no need to discuss it`s changes )

Currently, we have a huge gap in defining what is public and what is private.
So, common sense is our friend for the moment.
Let's start with some vision and tune it.

nizhikov · 2026-10-27T13:44:52Z

+
+## Why
+
+We should agree on changes to public API before merging them. Use a ticket to describe the problem and a PR to review an RFC stored alongside the code.


public API has rules on how to change it, already.
But, we don't have clear definition of what public API are.

So, we have two goals that must be adressed in different RFCs in my optinion:

Give clear definition of public API and public behavior in Apache Ignite.

Define (change) process of creation, changes or removal public API.

public API has rules on how to change it, already.

Can you point to the rules?

So, we have two goals

Could you make an initial proposal for discussion?

anton-vinogradov · 2026-10-27T14:20:37Z

Split into two focused discussions:

IGNITE-29219 Define public API and compatibility contracts #13759 — public API, observable behavior, and compatibility contracts (IGNITE-29219).
IGNITE-29220 Introduce the RFC development process #13760 — RFC development process (IGNITE-29220).

Please review the API definitions first, then the process. Closing this PR in favor of those two; the discussion here remains available for context.

anton-vinogradov added 3 commits October 23, 2026 22:53

IGNITE-29201 Add RFC on public API changes

c9acf68

IGNITE-29201 Use the RFC directory instead of a manual index

1bb559f

IGNITE-29201 Prepare RFC text for adoption

2f2f0ed

zstan reviewed Oct 26, 2026

View reviewed changes

vldpyatkov reviewed Oct 26, 2026

View reviewed changes

IGNITE-29201 Merge RFCs with their implementation

388f1d9

nizhikov reviewed Oct 27, 2026

View reviewed changes

This was referenced Oct 27, 2026

IGNITE-29219 Define public API and compatibility contracts #13759

Open

IGNITE-29220 Introduce the RFC development process #13760

Open

anton-vinogradov closed this Oct 27, 2026


		## Why

		We should agree on changes to public API before merging them. Use a ticket to describe the problem and a PR to review an RFC stored alongside the code.

Conversation

anton-vinogradov commented Oct 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

vldpyatkov commented Oct 26, 2026

Uh oh!

anton-vinogradov commented Oct 26, 2026

Uh oh!

anton-vinogradov commented Oct 26, 2026

Uh oh!

zstan commented Oct 27, 2026

Uh oh!

anton-vinogradov commented Oct 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anton-vinogradov Oct 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anton-vinogradov commented Oct 27, 2026

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

anton-vinogradov commented Oct 23, 2026 •

edited

Loading

anton-vinogradov Oct 27, 2026 •

edited

Loading