8000 Initial contributors guide lines around features by stianst · Pull Request #48928 · keycloak/keycloak · GitHub
[go: up one dir, main page]
Skip to content

Initial contributors guide lines around features #48928

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stianst merged 3 commits into from
May 29, 2026
Merged

Initial contributors guide lines around features #48928

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
71230b0
Initial contributors guide lines around features
stianst May 12, 2026
7d68caa
Apply suggestions from code review
stianst May 13, 2026
003bda3
Update docs/features.md
stianst May 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 74 additions & 0 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Developing Features for Keycloak

Keycloak Features allow individual capabilities of Keycloak to have different support levels; additionally features
can be disabled when they are not needed.

In most cases all significant new capabilities added to Keycloak should be wrapped by a new experimental feature. The
feature is then graduated to preview when it is considered feature complete, and eventually graduates to supported
after feedback from the community.

When implementing a new feature in Keycloak, it is highly recommended to define requirements and a minimum viable feature
initially, with incremental value added to the feature in later stages. Keeping the scope of the feature small allows
implementing the feature quicker and increases the quality as better test coverage and security can be provided.

## Feature level expectations

### Experimental
Comment thread
vmuzikar marked this conversation as resolved.
Resolved

* Is not supported for production use-cases, only for evaluation purposes
* Does not have to be feature complete
* Good test coverage is required
* Documentation is required, and should be updated as the feature evolves
Comment thread
stianst marked this conversation as resolved.
Resolved
* Does not have to provide backwards compatibility for APIs, nor migrating support
@mposolda mposolda May 13, 2026 •
edited
Loading
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Does not have to provide backwards compatibility for APIs, nor migrating support
* Does not have to provide backwards compatibility for APIs, nor migrating support. Experimental features should be **never** enabled in the production environment as they can break later migration of the production instance.

Is it possible to add some more "strong" warning about never enable experimental features in production? Would be good to avoid the bugs similar to this (saw some reports like this in the past):

  • User enables experimental feature in his production instance in version X
  • User creates new realm. That will for example add some new experimental authenticator to the "browser" flow
  • Experimental feature is removed in version X+1. User migrates to this version. Now he tries to authenticate to his realm, but will be unable to do that due the issue like "Authenticator not available" as experimental authenticator impl does not exists anymore

@stianst stianst May 21, 2026
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated to Is not supported


### Preview
Comment thread
stianst marked this conversation as resolved.
Resolved

* Is supported for production use-cases, but does not guarantee seamless upgrades
* Must be feature complete (minimum viable feature)
* A review of test coverage is required prior to graduating a feature to preview
* A security review is required prior to graduating a feature to preview
* Review of any feedback or open issues must be resolved prior to graduating a feature to preview
* Should aim to provide backwards compatible APIs, and migration. However, this can be omitted if needed
@vmuzikar vmuzikar May 21, 2026
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* Should aim to provide backwards compatible APIs, and migration. However, this can be omitted if needed
* Should aim to provide backwards compatible APIs, and migration. However, this can be omitted if needed, i.e. a breaking change can be introduced to a preview feature

@stianst stianst May 26, 2026
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You are basically just writing again what is in the first sentence

@vmuzikar vmuzikar May 26, 2026
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean:

but does not guarantee seamless upgrades

That does not read to me the same as "breaking changes can happen".

@stianst stianst May 27, 2026
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I meant Should aim to provide backwards compatible APIs

* When a feature is graduated to preview it is expected the feature will graduate to supported in the next major or minor release
Comment thread
stianst marked this conversation as resolved.
Resolved

### Supported

* Is supported for production use-cases
* Must provide backwards compatible APIs and migration support if needed
Comment thread
ahus1 marked this conversation as resolved.
Resolved
* Review of any feedback or open issues must be resolved prior to graduating a feature to supported

# Breaking changes and removal of features

Breaking changes to supported features must be introduced through a new version of the feature. During a major release
life-cycle the default version can not be changed. However, there may be multiple supported versions. Previous versions
may be deprecated, but should remain the default. Migration to a newer version should be as simple as possible, where the ideal is a fully automated migration provided.

New major releases can remove features completely or older feature versions. In general this should only be done after
Comment thread
ryanemerson marked this conversation as resolved.
Resolved
the feature or feature version having been deprecated for a minimum of one release (not including patch releases).

In the majority of cases preview features should follow the process for supported features. However, if breaking changes are required to preview features that can be made in the same version. Preview features can also be removed without deprecation, but ideally should be deprecated first.

Experimental features have no contract in terms of breaking changes. That means breaking changes can be introduced at any point, without new versions, deprecations, or any other warning. Additionally, no migration support is required.

# Documentation

## Experimental

Relevant documentation and guides for the feature should be clearly marked as experimental, and as under active
Comment thread
ahus1 marked this conversation as resolved.
Resolved
Comment thread
ryanemerson marked this conversation as resolved.
Resolved
development. This should include a link to the nightly release for those that want to evaluate the latest changes to
the feature.

To encourage feedback there should be a link to a single GitHub Discussion (in the [Feedback category](https://github.com/keycloak/keycloak/discussions/categories/feedback)). The Discussion may optionally further link to GitHub Issues
relevant to the feature.

## Preview

Relevant documentation and guides for the feature should be clearly marked as preview, with a notice that the feature
can be used in production, but seamless upgrades are not guaranteed.

The link to the GitHub Discussion should remain for preview features.

## Supported

As a feature is graduated to supported, any experimental/preview notices should be removed, including the link to the GitHub
Discussions marked for feedback. The GitHub Discussion should be marked as closed.
0