Update to repository documentation, including updated contributors guide
This commit is contained in:
stianst
Stian Thorgersen
parent
e06c705ca8
commit
191c9753de
11 changed files with 233 additions and 152 deletions
89
CONTRIBUTING.md
Normal file
89
CONTRIBUTING.md
Normal file
|
|
@ -0,0 +1,89 @@
|
|||
# Keycloak Community
|
||||
|
||||
Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services.
|
||||
|
||||
## Building and working with the codebase
|
||||
|
||||
Details for building from source and working with the codebase are provided in the [building and working with the code base](docs/building.md) guide.
|
||||
|
||||
## Contributing to Keycloak
|
||||
|
||||
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.
|
||||
|
||||
Here's a quick checklist for a good PR, more details below:
|
||||
|
||||
1. [Keycloak Dev Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev)
|
||||
2. A JIRA 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`)
|
||||
5. Commit message is prefixed by JIRA number
|
||||
6. No changes to code not directly related to your PR
|
||||
7. Includes functional/integration test
|
||||
8. Includes documentation
|
||||
|
||||
Once you have submitted your PR please monitor it for comments/feedback. We reserve the right to close inactive PRs if
|
||||
you do not respond within 2 weeks (bear in mind you can always open a new PR if it is closed due to inactivity).
|
||||
|
||||
Also, please remember that we do receive a fairly large amount of PRs and also have code to write ourselves, so we may
|
||||
not be able to respond to your PR immediately. The best place to ping us is on the thread you started on the dev mailing list.
|
||||
|
||||
### Finding something to work on
|
||||
|
||||
If you would like to contribute to Keycloak, but are not sure exactly what to work on, you can find a number of open
|
||||
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
|
||||
|
||||
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://lists.jboss.org/mailman/listinfo/keycloak-dev).
|
||||
|
||||
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.
|
||||
|
||||
### Create an issue in Keycloak JIRA
|
||||
|
||||
Take your time to write a proper JIRA including a good summary and description.
|
||||
|
||||
Remember this may be the first thing a reviewer of your PR will look at to get an idea of what you are proposing
|
||||
and it will also be used by the community in the future to find about what new features and enhancements are included in
|
||||
new releases.
|
||||
|
||||
Note: Keycloak Node.js Admin Client uses GitHub issues and not the Keycloak JIRA.
|
||||
|
||||
### Implementing
|
||||
|
||||
Details for building from source and working with the codebase are provided in the
|
||||
[building and working with the code base](docs/building.md) guide.
|
||||
|
||||
Do not format or refactor code that is not directly related to your contribution. If you do this it will significantly
|
||||
increase our effort in reviewing your PR. If you have a strong need to refactor code then submit a separate PR for the
|
||||
refactoring.
|
||||
|
||||
### Testing
|
||||
|
||||
Details for implementing tests are provided in the [writing tests](docs/tests-development.md) guide.
|
||||
|
||||
Do not add mock frameworks or other testing frameworks that are not already part of the testsuite. Please write tests
|
||||
in the same way as we have written our tests.
|
||||
|
||||
### Submitting your PR
|
||||
|
||||
When preparing your PR make sure you have a single commit and your branch is rebased on the master branch from the
|
||||
project repository.
|
||||
|
||||
This means use the `git rebase` command and not `git pull` when integrating changes from master to your branch. See
|
||||
[Git Documentation](https://git-scm.com/book/en/v2/Git-Branching-Rebasing) for more details.
|
||||
|
||||
We require that you squash to a single commit. You can do this with the `git rebase -i HEAD~X` command where X
|
||||
is the number of commits you want to squash. See the [Git Documentation](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
|
||||
for more details.
|
||||
|
||||
The above helps us review your PR and also makes it easier for us to maintain the repository. It is also required by
|
||||
our automatic merging process.
|
||||
|
||||
We also require that the commit message is prefixed with the Keycloak JIRA issue number (example commit message
|
||||
"KEYCLOAK-9876 My super cool new feature").
|
||||
130
README.md
130
README.md
|
|
@ -1,84 +1,72 @@
|
|||
Keycloak
|
||||
========
|
||||
# Keycloak
|
||||
|
||||
Open Source Identity and Access Management for modern Applications and Services.
|
||||
Keycloak is an Open Source Identity and Access Management solution for modern Applications and Services.
|
||||
|
||||
For more information about Keycloak visit [Keycloak homepage](http://keycloak.org) and [Keycloak blog](http://blog.keycloak.org).
|
||||
This repository contains the source code for the Keycloak Server, Java adapters and the JavaScript adapter.
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
## Help and Documentation
|
||||
|
||||
Ensure you have JDK 8 (or newer), Maven 3.1.1 (or newer) and Git installed
|
||||
|
||||
java -version
|
||||
mvn -version
|
||||
git --version
|
||||
|
||||
First clone the Keycloak repository:
|
||||
|
||||
git clone https://github.com/keycloak/keycloak.git
|
||||
cd keycloak
|
||||
|
||||
To build Keycloak run:
|
||||
|
||||
mvn install
|
||||
|
||||
This will build all modules and run the testsuite.
|
||||
|
||||
To build the distribution run:
|
||||
|
||||
mvn install -Pdistribution
|
||||
|
||||
Once completed you will find distribution archives in `distribution`.
|
||||
|
||||
To build only the server run:
|
||||
|
||||
mvn -Pdistribution -pl distribution/server-dist -am -Dmaven.test.skip clean install
|
||||
|
||||
|
||||
Starting Keycloak
|
||||
-----------------
|
||||
|
||||
To start Keycloak during development first build as specified above, then run:
|
||||
|
||||
mvn -f testsuite/utils/pom.xml exec:java -Pkeycloak-server
|
||||
|
||||
When running testsuite, by default an account with username `admin` and password `admin` will be created within the master realm at start.
|
||||
|
||||
To start Keycloak from the server distribution first build the distribution it as specified above, then run:
|
||||
|
||||
tar xfz distribution/server-dist/target/keycloak-<VERSION>.tar.gz
|
||||
cd keycloak-<VERSION>
|
||||
bin/standalone.sh
|
||||
|
||||
To stop the server press `Ctrl + C`.
|
||||
|
||||
Reporting security vulnerabilities
|
||||
----------------------------------
|
||||
|
||||
If you've found a security vulnerability, please look at the [instructions on how to properly report it](http://www.keycloak.org/security.html)
|
||||
|
||||
Help and Documentation
|
||||
----------------------
|
||||
* [Documentation](http://www.keycloak.org/documentation.html) - User Guide, Admin REST API and Javadocs
|
||||
* [User Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-user) - Mailing list to ask for help and general questions about Keycloak
|
||||
* [Documentation](https://www.keycloak.org/documentation.html)
|
||||
* [User Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-user) - Mailing list for help and general questions about Keycloak
|
||||
* [JIRA](https://issues.jboss.org/projects/KEYCLOAK) - Issue tracker for bugs and feature requests
|
||||
|
||||
|
||||
Contributing
|
||||
------------
|
||||
## Reporting Security Vulnerabilities
|
||||
|
||||
* Developer documentation
|
||||
* [Hacking on Keycloak](misc/HackingOnKeycloak.md) - How to become a Keycloak contributor
|
||||
* [Testsuite](misc/Testsuite.md) - Details about testsuite, but also how to quickly run Keycloak during development and a few test tools (OTP generation, LDAP server, Mail server)
|
||||
* [Database Testing](misc/DatabaseTesting.md) - How to do testing of Keycloak on different databases
|
||||
* [Updating Database](misc/UpdatingDatabaseSchema.md) - How to change the Keycloak database
|
||||
* [Changing the Default keycloak-subsystem Configuration](misc/UpdatingServerConfig.md) - How to update the default keycloak-subsystem config
|
||||
* [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev) - Mailing list to discuss development of Keycloak
|
||||
If you've found a security vulnerability, please look at the [instructions on how to properly report it](http://www.keycloak.org/security.html)
|
||||
|
||||
|
||||
License
|
||||
-------
|
||||
## Reporting an issue
|
||||
|
||||
If you believe you have discovered a defect in Keycloak please open an issue in our [Issue Tracker](https://issues.jboss.org/projects/KEYCLOAK).
|
||||
Please remember to provide a good summary, description as well as steps to reproduce the issue.
|
||||
|
||||
|
||||
## Getting started
|
||||
|
||||
To run Keycloak download the distribution from our [website](https://www.keycloak.org/downloads.html). Unzip and run:
|
||||
|
||||
bin/standalone.[sh|bat]
|
||||
|
||||
Alternatively, you can use the Docker image by running:
|
||||
|
||||
docker run jboss/keycloak
|
||||
|
||||
For more details refer to the [Keycloak Documentation](https://www.keycloak.org/documentation.html).
|
||||
|
||||
|
||||
## Building from Source
|
||||
|
||||
To build from source refer to the [building and working with the code base](docs/building.md) guide.
|
||||
|
||||
|
||||
### Testing
|
||||
|
||||
To run tests refer to the [running tests](docs/tests.md) guide.
|
||||
|
||||
|
||||
### Writing Tests
|
||||
|
||||
To write tests refer to the [writing tests](docs/tests-development.md) guide.
|
||||
|
||||
|
||||
## Contributing
|
||||
|
||||
Before contributing to Keycloak please read our [contributing guidelines](CONTRIBUTING.md).
|
||||
|
||||
|
||||
## Other Keycloak Projects
|
||||
|
||||
* [Keycloak](https://github.com/keycloak/keycloak) - Keycloak Server and Java adapters
|
||||
* [Keycloak Documentation](https://github.com/keycloak/keycloak-documentation) - Documentation for Keycloak
|
||||
* [Keycloak QuickStarts](https://github.com/keycloak/keycloak-quickstarts) - QuickStarts for getting started with Keycloak
|
||||
* [Keycloak Docker](https://github.com/jboss-dockerfiles/keycloak) - Docker images for Keycloak
|
||||
* [Keycloak Gatekeeper](https://github.com/keycloak/keycloak-gatekeeper) - Proxy service to secure apps and services with Keycloak
|
||||
* [Keycloak Node.js Connect](https://github.com/keycloak/keycloak-nodejs-connect) - Node.js adapter for Keycloak
|
||||
* [Keycloak Node.js Admin Client](https://github.com/keycloak/keycloak-nodejs-admin-client) - Node.js library for Keycloak Admin REST API
|
||||
|
||||
|
||||
## License
|
||||
|
||||
* [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
|
||||
57
docs/building.md
Normal file
57
docs/building.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
## Building from source
|
||||
|
||||
Ensure you have JDK 8 (or newer), Maven 3.1.1 (or newer) and Git installed
|
||||
|
||||
java -version
|
||||
mvn -version
|
||||
git --version
|
||||
|
||||
First clone the Keycloak repository:
|
||||
|
||||
git clone https://github.com/keycloak/keycloak.git
|
||||
cd keycloak
|
||||
|
||||
To build Keycloak run:
|
||||
|
||||
mvn install
|
||||
|
||||
This will build all modules and run the testsuite.
|
||||
|
||||
To build the ZIP distribution run:
|
||||
|
||||
mvn install -Pdistribution
|
||||
|
||||
Once completed you will find distribution archives in `distribution`.
|
||||
|
||||
To build only the server run:
|
||||
|
||||
mvn -Pdistribution -pl distribution/server-dist -am -Dmaven.test.skip clean install
|
||||
|
||||
|
||||
## Starting Keycloak
|
||||
|
||||
To start Keycloak during development first build as specified above, then run:
|
||||
|
||||
mvn -f testsuite/utils/pom.xml exec:java -Pkeycloak-server
|
||||
|
||||
When running testsuite, by default an account with username `admin` and password `admin` will be created within the master realm at start.
|
||||
|
||||
To start Keycloak from the server distribution first build the distribution it as specified above, then run:
|
||||
|
||||
tar xfz distribution/server-dist/target/keycloak-<VERSION>.tar.gz
|
||||
cd keycloak-<VERSION>
|
||||
bin/standalone.sh
|
||||
|
||||
To stop the server press `Ctrl + C`.
|
||||
|
||||
|
||||
## Working with the codebase
|
||||
|
||||
We don't currently enforce a code style in Keycloak, but a good reference is the code style used by WildFly. This can be
|
||||
retrieved from [Wildfly ide-configs](https://github.com/wildfly/wildfly-core/tree/master/ide-configs).To import formatting
|
||||
rules, see following [instructions](http://community.jboss.org/wiki/ImportFormattingRules).
|
||||
|
||||
If your changes require updates to the database read [Updating Database Schema](updating-database-schema.md).
|
||||
|
||||
If your changes require introducing new dependencies or updating dependency versions please discuss this first on the
|
||||
dev mailing list. We do not accept new dependencies to be added lightly, so try to use what is available.
|
||||
24
docs/test-development.md
Normal file
24
docs/test-development.md
Normal file
|
|
@ -0,0 +1,24 @@
|
|||
## Writing tests
|
||||
|
||||
We focus primarily on integration/functional level tests. Unit tests are avoided and only recommended for isolated
|
||||
classes such as small utils. We do not use any mocking frameworks and we will not accept any contributions that adds a
|
||||
mocking framework.
|
||||
|
||||
When writing tests please follow the same approach as we have taken in the other tests. There are many ways to
|
||||
test software and we have chosen ours, so please appreciate that.
|
||||
|
||||
The main tests are provided in testsuite/integration-arquillian/tests/base. Most server tests are here.
|
||||
|
||||
Integration tests can be executed from the IDE in the same way as you would run unit tests. When ran from within the
|
||||
IDE an embedded Keycloak server is executed automatically.
|
||||
|
||||
A good test to start looking at is org.keycloak.testsuite.forms.LoginTest. It is reasonable straightforward to understand
|
||||
this test.
|
||||
|
||||
When developing your test depending on the feature or enhancement you are testing you may find it best to add to an
|
||||
existing test, or to write a test from scratch. For the latter, we recommend finding another test that is close to what
|
||||
you need and use that as a basis.
|
||||
|
||||
All tests don't have to be fully black box testing as the testsuite deploys a special feature to the Keycloak server
|
||||
that allows running code within the server. This allows writing tests that can execute functions not exposed through
|
||||
APIs as well as access data that is not exposed. For an example on how to do this look at org.keycloak.testsuite.runonserver.RunOnServerTest.
|
||||
|
|
@ -1,5 +1,5 @@
|
|||
Executing testsuite
|
||||
===================
|
||||
Executing tests
|
||||
===============
|
||||
|
||||
Browser
|
||||
-------
|
||||
|
|
@ -11,7 +11,7 @@ To run the tests with Firefox add `-Dbrowser=firefox` or for Chrome add `-Dbrows
|
|||
Database
|
||||
--------
|
||||
|
||||
By default the testsuite uses an embedded H2 database to test with other databases see (Database Testing)[DatabaseTesting.md].
|
||||
By default the testsuite uses an embedded H2 database to test with other databases see (Database Testing)[tests-db.md].
|
||||
|
||||
Test utils
|
||||
==========
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
Hacking on Keycloak
|
||||
===================
|
||||
|
||||
GitHub Repository
|
||||
-----------------
|
||||
|
||||
### Create a GitHub account if you don't already have one
|
||||
|
||||
[Join GitHub](https://github.com/join)
|
||||
|
||||
### Fork Keycloak repository into your account
|
||||
|
||||
[https://github.com/keycloak/keycloak](https://github.com/keycloak/keycloak)
|
||||
|
||||
### Clone your newly forked copy onto your local workspace
|
||||
|
||||
git clone https://github.com/<your username>/keycloak.git
|
||||
cd keycloak
|
||||
|
||||
### Add a remote ref to upstream for pulling future updates
|
||||
|
||||
git remote add upstream https://github.com/keycloak/keycloak.git
|
||||
|
||||
### Pull later updates from upstream
|
||||
|
||||
git fetch upstream
|
||||
git rebase upstream/master
|
||||
|
||||
|
||||
Discuss changes
|
||||
---------------
|
||||
|
||||
Before starting work on a new feature or anything besides a minor bug fix join the [Keycloak Dev mailing list](https://lists.jboss.org/mailman/listinfo/keycloak-dev)
|
||||
and send a mail about your proposed changes. This is vital as otherwise you may waste days implementing a feature that is later rejected.
|
||||
|
||||
Once you have received feedback from the mailing list if there's not one already create a [JIRA issue](https://issues.jboss.org/browse/KEYCLOAK).
|
||||
|
||||
|
||||
Implement changes
|
||||
-----------------
|
||||
|
||||
We don't currently enforce a code style in Keycloak, but a good reference is the code style used by WildFly. This can be retrieved from [Wildfly ide-configs](https://github.com/wildfly/wildfly-core/tree/master/ide-configs).To import formatting rules, see following [instructions](http://community.jboss.org/wiki/ImportFormattingRules)
|
||||
|
||||
If your changes requires updates to the database read [Updating Database Schema](UpdatingDatabaseSchema.md).
|
||||
|
||||
To try your changes out manually you can quickly start Keycloak from within your IDEA or Maven, to find out how to do this
|
||||
read [Testsuite](Testsuite.md). It's also important that you add tests to the testsuite for your changes.
|
||||
|
||||
|
||||
Get your changes merged into upstream
|
||||
-------------------------------------
|
||||
|
||||
Here's a quick check list for a good pull request (PR):
|
||||
|
||||
* Discussed and agreed on Keycloak Dev mailing list
|
||||
* One commit per PR
|
||||
* One feature/change per PR
|
||||
* No changes to code not directly related to your change (e.g. no formatting changes or refactoring to existing code, if you want to refactor/improve existing code that's a separate discussion to mailing list and JIRA issue)
|
||||
* A JIRA associated with your PR (include the JIRA issue number in commit comment)
|
||||
* All tests in testsuite pass
|
||||
* Do a rebase on upstream master
|
||||
* We only accept contributions to the master branch. The exception to this is if the fix is for the latest CR release and Final has not yet been released, in which case you can send the PR to both the corresponding branch and the master branch.
|
||||
* PR needs to be accompanied with tests that sufficiently test added/changed functionality
|
||||
* Relevant documentation change needs to be submitted to keycloak/keycloak-documentation repository
|
||||
* Should a change be requested in a PR that stays without response for 2 weeks, the PR would be closed
|
||||
|
||||
Once you're happy with your changes go to GitHub and create a PR to the master branch.
|
||||
|
||||
|
||||
Development of Wildfly-based features
|
||||
-------------------------------------
|
||||
|
||||
When your changes are developed for Wildfly only, it is rather useful to create a jar-less distro that would retrieve the module jars directly
|
||||
from maven artifacts so that you would not to have to replace the module jars manually during development. You can create such a server
|
||||
distribution by adding a keycloak.provisioning.xml parameter to the standard maven command for creating distribution:
|
||||
|
||||
mvn clean install -Pdistribution -Dkeycloak.provisioning.xml=server-provisioning-devel.xml
|
||||
Loading…
Reference in a new issue