diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 226a796c46ed..8136e5228614 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,14 +8,15 @@ Details for building from source and working with the codebase are provided in t ## Contributing to Keycloak -Keycloak is an Open Source community-driven project and we welcome contributions as well as feedback from the community. +Keycloak is an Open Source community-driven project and we welcome contributions as well as feedback from the community. We do have a few guidelines in place to help you be successful with your contribution to Keycloak. -We do have a few guidelines in place to help you be successful with your contribution to Keycloak. +Firstly, if you want to contribute a larger change to Keycloak we ask that you open a +discussion first. For minor changes you can skip this part and go straight ahead to sending a contribution. Bear in mind that if you open a discussion first you can identify if the change will be accepted, as well as getting early feedback. Here's a quick checklist for a good PR, more details below: -1. [Keycloak Dev Mailing List](https://groups.google.com/forum/#!forum/keycloak-dev) -2. A JIRA associated with the PR +1. A discussion around the change (https://github.com/keycloak/keycloak/discussions/categories/ideas) +2. A JIRA with a good description associated with the PR 3. One feature/change per PR 4. One commit per PR 5. PR rebased on master (`git rebase`, not `git pull`) @@ -36,13 +37,15 @@ If you would like to contribute to Keycloak, but are not sure exactly what to wo issues that are awaiting contributions in the [Keycloak JIRA](https://issues.jboss.org/projects/KEYCLOAK/versions/12340167). -### Open a discussion on Keycloak Dev Mailing List +### Open a discussion on a proposed change -As Keycloak is a community-driven project we require contributors to send a description of what they are planning to -work on to the [Keycloak Dev Mailing List](https://groups.google.com/forum/#!forum/keycloak-dev). +As Keycloak is a community-driven project we require contributors to open a discussion on what they are planning to contribute. -We recommend starting the discussion prior to submitting your PR. Through the mailing list you can get valuable -feedback both from the core Keycloak team as well as the wider community. +Discussions should first and foremost be done through [GitHub Discussions](https://github.com/keycloak/keycloak/discussions/categories/ideas). + +The [Keycloak Dev Mailing List](https://groups.google.com/forum/#!forum/keycloak-dev) can be used to notify the community on your new discussion, and can also be used for more low-level implementation discussions. + +For very large proposals it can be inefficient to capture all the information in the GitHub Discussion. In this cases a separate design proposal can be sent to the [Keycloak Community repository](https://github.com/keycloak/keycloak-community/tree/master/design), and linked to from the GitHub Discussion. ### Create an issue in Keycloak JIRA diff --git a/GOVERNANCE.md b/GOVERNANCE.md index 3538cc84df67..ec46b5fa317e 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -94,16 +94,13 @@ If the change has a bigger impact it has to follow the process for larger change ### Larger Changes -For larger changes all maintainers and contributors should have a chance of reviewing the change. This is done by -sending an email to the [developer mailing list](https://groups.google.com/forum/#!forum/keycloak-dev) to start a -discussion around the change. +For larger changes all maintainers and contributors should have a chance of reviewing the change. This is done through [GitHub Discussions](https://github.com/keycloak/keycloak/discussions/categories/ideas). -For new features we highly recommend creating a design proposal. There is no strict requirement of the content or layout, -but it should at least cover motivation, use cases and how the feature will be used. A design proposal is created by -sending a PR to [design proposals repository](https://github.com/keycloak/keycloak-community/tree/master/design). +For new features we highly recommend always opening a discussion in GitHub Discussions early. -The contributor can decide to send a pull request prior to discussion on the mailing list, and the creation of a design -proposal. However, the change will not be accepted until it has been discussed on the mailing list. +For very large proposals it can be inefficient to capture all the information in the GitHub Discussion. In this cases a separate design proposal can be sent to the [Keycloak Community repository](https://github.com/keycloak/keycloak-community/tree/master/design), and linked to from the GitHub Discussion. -If there are any objections to the change they can in most cases be resolved through discussions on the mailing list or -on the pull request. If a resolution can not be made it can be accepted if at least 2/3 of maintainers approve the change. +The contributor can decide to send a pull request prior to discussions. However, the change will not be accepted until it has been discussed through [GitHub Discussions](https://github.com/keycloak/keycloak/discussions/categories/ideas). + +If there are any objections to the change they can in most cases be resolved through discussions in [GitHub Discussions](https://github.com/keycloak/keycloak/discussions/categories/ideas), or +in the pull request. If a resolution can not be made it can be accepted if at least 2/3 of maintainers approve the change. \ No newline at end of file