From 656a5c4baa5539d30c887d274db9db8394b3d29d Mon Sep 17 00:00:00 2001 From: Stian Thorgersen Date: Tue, 14 Apr 2015 10:30:58 +0200 Subject: [PATCH] Updated hacking on KC guide --- README.md | 10 ++- misc/DatabaseTesting.md | 17 +++- misc/HackingOnKeycloak.md | 79 +++++++++++++++--- misc/ReleaseProcess.md | 80 +++++++++++++++++++ .../README.md => misc/Testsuite.md | 10 +-- misc/UpdatingDatabaseSchema.md | 2 +- 6 files changed, 175 insertions(+), 23 deletions(-) create mode 100644 misc/ReleaseProcess.md rename testsuite/integration/README.md => misc/Testsuite.md (92%) diff --git a/README.md b/README.md index dd5060b0e89a..9b7edaf6f808 100755 --- a/README.md +++ b/README.md @@ -7,10 +7,16 @@ Keycloak is an SSO Service for web apps and REST services. For more information Building -------- -Ensure you have JDK 7 (or newer) and Maven 3.2.1 (or newer) installed +Ensure you have JDK 7 (or newer), Maven 3.2.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: @@ -45,7 +51,7 @@ To stop the server press `Ctrl + C`. Contributing ------------ -* [Hacking On Keycloak](https://github.com/keycloak/keycloak/blob/master/misc/HackingOnKeycloak.md) +* [Hacking on Keycloak](misc/HackingOnKeycloak.md) License diff --git a/misc/DatabaseTesting.md b/misc/DatabaseTesting.md index 0ae699d27c1e..07feccb465d0 100644 --- a/misc/DatabaseTesting.md +++ b/misc/DatabaseTesting.md @@ -1,11 +1,20 @@ Test with various databases =========================== +MongoDB +------- + +The Keycloak testsuite uses an embedded MongoDB when running tests so you don't have to have one running locally. + +Run tests: + + mvn install -Pmongo + MySQL ----- -Use the official [MySQL docker image](https://registry.hub.docker.com/_/mysql/). +The simplest way to test with MySQL is to use the official [MySQL docker image](https://registry.hub.docker.com/_/mysql/). Start MySQL: @@ -13,7 +22,7 @@ Start MySQL: Run tests: - mvn clean install -Dkeycloak.connectionsJpa.url=jdbc:mysql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' mysql`/keycloak -Dkeycloak.connectionsJpa.driver=com.mysql.jdbc.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak + mvn install -Dkeycloak.connectionsJpa.url=jdbc:mysql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' mysql`/keycloak -Dkeycloak.connectionsJpa.driver=com.mysql.jdbc.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak Stop MySQl: @@ -23,7 +32,7 @@ Stop MySQl: PostgreSQL ---------- -Use the official [PostgreSQL docker image](https://registry.hub.docker.com/_/postgres/). +The simplest way to test with PostgreSQL is to use the official [PostgreSQL docker image](https://registry.hub.docker.com/_/postgres/). Start PostgreSQL: @@ -31,7 +40,7 @@ Start PostgreSQL: Run tests: - mvn clean install -Dkeycloak.connectionsJpa.url=jdbc:postgresql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' postgres`:5432/keycloak -Dkeycloak.connectionsJpa.driver=org.postgresql.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak + mvn install -Dkeycloak.connectionsJpa.url=jdbc:postgresql://`docker inspect --format '{{ .NetworkSettings.IPAddress }}' postgres`:5432/keycloak -Dkeycloak.connectionsJpa.driver=org.postgresql.Driver -Dkeycloak.connectionsJpa.user=keycloak -Dkeycloak.connectionsJpa.password=keycloak Stop PostgreSQL: diff --git a/misc/HackingOnKeycloak.md b/misc/HackingOnKeycloak.md index 473df2eacecc..d6bd5dc1607f 100644 --- a/misc/HackingOnKeycloak.md +++ b/misc/HackingOnKeycloak.md @@ -1,9 +1,70 @@ -So you are a developer who wants to start hacking on Keycloak? Here is the short list of things you need to know: - -1. You'll get a good feel for the Keycloak server and adapters if you try out the demo apps. Instructions for setting that up are at [https://github.com/keycloak/keycloak/tree/master/examples/demo-template](https://github.com/keycloak/keycloak/tree/master/examples/demo-template). -2. The build has three Maven roots. There is the obvious one at the root of the project, which builds all the core stuff. The second one is in /distribution. That assembles the appliance, the adapters, and a few other things. The third is in /docbook. That one creates the documentation. -3. We track everything in [Jira](https://issues.jboss.org/browse/KEYCLOAK). Make sure you create an issue for any changes you propose. -4. We work with GitHub in much the same way as the WildFly project. You can look at [Hacking on Wildfly](https://developer.jboss.org/wiki/HackingOnWildFly) to get some tips on that. -5. If you have other questions, ask on the [Developer Mailing List](https://lists.jboss.org/mailman/listinfo/keycloak-dev). We don't use IRC much, so that's the best place to ask. -6. For a more productive development, please consider using org.keycloak.testutils.KeycloakServer. This class is a Java Application that starts a KC server without requiring you to deploy a WAR file in a specific container. - \ No newline at end of file +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//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 (https://github.com/wildfly/wildfly-core/tree/master/ide-configs)[https://github.com/wildfly/wildfly-core/tree/master/ide-configs]. + +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 + +Once you're happy with your changes go to GitHub and create a PR. + + +Release Keycloak +---------------- + +* [Release Process](ReleaseProcess.md) \ No newline at end of file diff --git a/misc/ReleaseProcess.md b/misc/ReleaseProcess.md new file mode 100644 index 000000000000..08fd1b6db4ac --- /dev/null +++ b/misc/ReleaseProcess.md @@ -0,0 +1,80 @@ +## Test + +* Make sure tests pass on Travis +* Make sure tests pass on Jenkins +* Go through the (manual testing)[https://docs.google.com/spreadsheets/d/17C_WEHNE03r5DxN71OXGJaytjA6_WjZKCXRcsnmNQD4] + +## Create release + +* Get from github +``` +$ git@github.com:keycloak/keycloak.git +``` + +* Build everything to make sure its kosher. +``` +$ cd keycloak +$ mvn install +``` + +* Build javadoc and jaxrs-doc +``` +$ mvn javadoc:javadoc +# This is for jaxrs-docs +$ cd services +$ mvn package +# back to root keycloak dir +$ cd .. +``` + +* Upload to Nexus (from project root) +``` +$ mvn -Pdistribution deploy +``` + +* Login to Nexus and release the maven repository uploads in the staging area. + +* Upload src and distro zips to sf.net/projects/keycloak. This includes appliance, war-dist, each adapter, and proxy distros. You need to create an adapters folder on sf.net and each uploaded adapter there. + +* Upload documentation to docs.jboss.org +``` +$ sftp keycloak@filemgmt.jboss.org +> cd docs_htdocs/keycloak/docs +> mkdir 1.0.0.Final (or whatever version) +> quit + +$ unzip distribution/examples-docs-zip/target/keycloak-examples-docs-dist.zip +$ cd docs +$ rsync -rv --protocol=28 * keycloak@filemgmt.jboss.org:/docs_htdocs/keycloak/docs/1.0.0.Final +``` + +* tag release +``` +$ git tag -a -m "1.0.0.Final" 1.0.0.Final +$ git push --tags +``` + +## Update Bower +``` +$ git clone https://github.com/keycloak/keycloak-js-bower +$ cp dist/keycloak-js-bower +$ cp dist/keycloak-js-bower +``` +Edit bower.json and set version (include -beta -rc, but not -final). Create tag. + +## Update OpenShift Cartridge + +See https://github.com/keycloak/openshift-keycloak-cartridge for details + +## Update Docker image + +Instructions TBD + +## Maven central + +Releases are automatically synced to Maven central, but this can take up to one day + +## Announce + +* Update Magnolia site to link keycloak docs and announcements. +* Write a blog and email about release including links to download, migration guide, docs, and blurb about what's new \ No newline at end of file diff --git a/testsuite/integration/README.md b/misc/Testsuite.md similarity index 92% rename from testsuite/integration/README.md rename to misc/Testsuite.md index f76392ed54b3..658a0427cbee 100644 --- a/testsuite/integration/README.md +++ b/misc/Testsuite.md @@ -8,14 +8,10 @@ The testsuite uses Sellenium. By default it uses the HtmlUnit WebDriver, but can To run the tests with Firefox add `-Dbrowser=firefox` or for Chrome add `-Dbrowser=chrome` -Mongo ------ +Database +-------- -The testsuite is executed with JPA model implementation with data saved in H2 database by default. To run testsuite with Mongo model, just add property `-Dkeycloak.realm.provider=mongo` when executing it. -This single property will cause that mongo will be used for realm-model, user-model and audit. - -Note that this will automatically run embedded Mongo database on localhost/27018 and it will stop it after whole testsuite is finished. -So you don't need to have Mongo installed on your laptop to run mongo execution tests. +By default the testsuite uses an embedded H2 database to test with other databases see (Database Testing)[DatabaseTesting.md]. Test utils ========== diff --git a/misc/UpdatingDatabaseSchema.md b/misc/UpdatingDatabaseSchema.md index 1dcee578df42..274669c6a6b0 100644 --- a/misc/UpdatingDatabaseSchema.md +++ b/misc/UpdatingDatabaseSchema.md @@ -76,4 +76,4 @@ It should be added last to the `DefaultMongoUpdaterProvider#updates` array. Testing database migration -------------------------- -Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it. \ No newline at end of file +Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it. \ No newline at end of file