Repository navigation
Documentation: merge quarkus/CONTRIBUING.md into quarkus/README.md so that users find all relevant information at one place - #46033
Merged
vmuzikar merged 1 commit intoFeb 9, 2026
Conversation
michalvavrik
force-pushed
the
docs/merge-quarkus-readme-and-contributing-mds
branch
from
February 4, 2026 20:20
3446c29 to
2c87527
Compare
shawkins
previously approved these changes
Feb 6, 2026
Contributor
There was a problem hiding this comment.
LGTM, thanks @michalvavrik
vmuzikar
reviewed
Feb 6, 2026
Contributor
There was a problem hiding this comment.
@michalvavrik Thank you. Looks good, added just some minor comments.
Merging the two documents (`README.md` and `CONTRIBUTING.md`) should provide information like "How to debug Keycloak in Quarkus DEV mode?" or "How to include Keycloak as extension to my existing Quarkus app?" in the one document users read whether they intend to contribute to Keycloak project or not. The new `README.md` also contain information specific to contributing, which is fine as the document is not part of the official Keycloak documentation. The `README.md` is intended as a guide for developers. This change is close to what the issue reporter suggested keycloak#45806 (comment), and is how we agreed to solve the issue when discussing this in Keycloak cloud native team. Closes: keycloak#45805 Supersedes: keycloak#45806 Changes: - `Before you start` section newly mentions `config-api` sub-module and Quarkus word is capitalized - `Activating the Module from the root directory` section is dropped as it is not true: - Quarkus module is not enabled conditionally - Quarkus module compilation with JDK 11 fails as Quarkus baseline is JDK 17 and JDK version is enforced in Keycloak parent by `enforce-java-version` - `Building the Keycloak Quarkus distribution` section - capitalized Quarkus word - `Running from the command line` section contained link leading to unknown discussion https://github.com/keycloak/keycloak/discussions/categories/keycloak-x-quarkus-distribution, I replaced it with general GH discussion link. I could not verify the reload statement due to the issue described below, but judging by this discussion keycloak#14351 explanation about reload limitations is still valid - `Running tests` section used `Keycloaks` which I think was a typo, so I fixed it. And capitalized Quarkus word - `Running tests from your IDE` I changed statement about the `@DistributionTest` test being a blackbox, I think the build may happen in a JVM if it is container environment, otherwise it is just a different JVM process - `Running container-based tests` capitalized word `Docker`. I also dropped `The container based tests are using Testcontainers to spin up the container image and can be considered tech preview.` as 3 years seem long enough for container-based tests to mature - `Running database tests`, fixed few typos - `Updating Expectations` fixed command example and test class rendering - `CONTRIBUTING.md` is merged into `README.md` in following manner: - `Keycloak Quarkus Extension` section, renamed `Resteasy` to `Quarkus REST` and missing recorder method `configSessionFactory` with `configSessionFactory` - dropped `Running the server in development mode` section as it was dealing with the same topic as the `Running from the command line` `README.md` section. however I migrated few sentences - dropped `Running tests` as it deals with the same topic as `Running tests` section of the README and it contains everything the dropped section does, just in a different words - `Before contributing the changes` section content replaced the README `Contributing` section as it provides a better approach - `Documentation` fixed link to the server documentation guides What is not handled here: - `Running from the command line` section suggests command `../mvnw -f server/pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev"`, however running this command on my workstation leads to startup failure due to missing class `java.lang.ClassNotFoundException: org.osgi.framework.FrameworkUtil` - former `CONTRIBUTING.md` keeps stating that the bytecode is recorder during the runtime Signed-off-by: Michal Vavřík <michal.vavrik@aol.com>
michalvavrik
force-pushed
the
docs/merge-quarkus-readme-and-contributing-mds
branch
from
February 7, 2026 19:38
2c87527 to
1f89d35
Compare
michalvavrik
deleted the
docs/merge-quarkus-readme-and-contributing-mds
branch
February 9, 2026 09:56
sashyo
pushed a commit
to tide-foundation/keycloak-IGA
that referenced
this pull request
Jul 20, 2026
keycloak#46033) Closes keycloak#45805 Signed-off-by: Michal Vavřík <michal.vavrik@aol.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Merging the two documents (
README.mdandCONTRIBUTING.md) should provide information like "How to debug Keycloak in Quarkus DEV mode?" or "How to include Keycloak as extension to my existing Quarkus app?" in the one document users read whether they intend to contribute to Keycloak project or not. The newREADME.mdalso contain information specific to contributing, which is fine as the document is not part of the official Keycloak documentation. TheREADME.mdis intended as a guide for developers.This change is close to what the issue reporter suggested #45806 (comment), and is how we agreed to solve the issue when discussing this in Keycloak cloud native team.
Closes: Update getting started documentation. #45805
Supersedes: Update documents to reflect that they are linux-specific #45806
Changes:
Before you startsection newly mentionsconfig-apisub-module and Quarkus word is capitalizedActivating the Module from the root directorysection is dropped as it is not true:enforce-java-versionBuilding the Keycloak Quarkus distributionsection - capitalized Quarkus wordRunning from the command linesection contained link leading to unknown discussion https://github.com/keycloak/keycloak/discussions/categories/keycloak-x-quarkus-distribution, I replaced it with general GH discussion link. I could not verify the reload statement due to the issue described below, but judging by this discussion Quarkus' Dev Services/Live Reload while doing Keycloak extensions development #14351 explanation about reload limitations is still valid. I also dropped note about plans to improving the DEV mode per Vaclav request.Running testssection usedKeycloakswhich I think was a typo, so I fixed it. And capitalized Quarkus wordRunning tests from your IDEI changed statement about the@DistributionTesttest being a blackbox, I think the build may happen in a JVM if it is container environment, otherwise it is just a different JVM processRunning container-based testscapitalized wordDocker. I also droppedThe container based tests are using Testcontainers to spin up the container image and can be considered tech preview.as 3 years seem long enough for container-based tests to matureRunning database tests, fixed few typosUpdating Expectationsfixed command example and test class renderingCONTRIBUTING.mdis merged intoREADME.mdin following manner:Keycloak Quarkus Extensionsection, renamedResteasytoQuarkus RESTand missing recorder methodconfigSessionFactorywithconfigSessionFactoryRunning the server in development modesection as it was dealing with the same topic as theRunning from the command lineREADME.mdsection. however I migrated few sentencesRunning testsas it deals with the same topic asRunning testssection of the README and it contains everything the dropped section does, just in a different wordsBefore contributing the changessection content replaced the READMEContributingsection as it provides a better approachDocumentationfixed link to the server documentation guidesChanging versions of Quarkiverse dependenciesper Vaclav requestWhat is not handled here:
Running from the command linesection suggests command../mvnw -f server/pom.xml compile quarkus:dev -Dkc.config.built=true -Dquarkus.args="start-dev", however running this command on my workstation leads to startup failure due to missing classjava.lang.ClassNotFoundException: org.osgi.framework.FrameworkUtil(maybe related to [admin-api-v2] Remove GlassFish Expressly dependency for Hibernate Validator #44628 as it happens when some EL factory is created, I did not check)