Updated hacking on KC guide

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

misc/DatabaseTesting.md

@@ -1,19 +1,28 @@
 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:
 
     docker run --name mysql -e MYSQL_DATABASE=keycloak -e MYSQL_USER=keycloak -e MYSQL_PASSWORD=keycloak -e MYSQL_ROOT_PASSWORD=keycloak -d 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,15 +32,15 @@ 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:
 
     docker run --name postgres -e POSTGRES_DATABASE=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=keycloak -e POSTGRES_ROOT_PASSWORD=keycloak -d postgres
 
 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:
 

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.
-
+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 (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)

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 <keycloak.js from dist> dist/keycloak-js-bower
+$ cp <keycloak.min.js from dist> 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

testsuite/integration/README.md → 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
 ==========

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. 
+Get the database from an old version of Keycloak that includes the demo applications. Start the server with this and test it.