Updated readme files

README-project.md

@@ -0,0 +1,47 @@
+## Get the code
+
+The easiest way to get started with the code is to [create your own fork](http://help.github.com/forking/) of this repository, and then clone your fork:
+
+	$ git clone git@github.com:<you>/debezium.git
+	$ cd debezium
+	$ git remote add upstream git://github.com/debezium/debezium.git
+	
+At any time, you can pull changes from the upstream and merge them onto your master:
+
+	$ git checkout master                    # switches to the 'master' branch
+	$ git pull upstream master               # fetches all 'upstream' changes and merges 'upstream/master' onto your 'master' branch
+    $ git branch -u upstream/master master   # makes your local 'master' branch track the 'upstream/master' branch
+
+The general idea is to keep your local `master` branch in-sync with the `upstream/master`. You don't have to keep your fork's `master` branch updated, since you will use your fork primarily for topic branches and creating pull requests (see below). But if you do want to update your fork's `master` branch, you can always do this with:
+
+	$ git push origin                   # pushes all the updates to your fork, which should be in-sync with 'upstream'
+
+
+## Building Debezium
+
+The following command compiles all the code, installs the JARs into your local Maven repository, and run all of the unit and integration tests:
+
+	$ mvn clean install
+
+## Contribute fixes and features
+
+Debezium is licensed under the Apache License 2.0 (see the file LICENSE.txt or [http://www.apache.org/licenses/LICENSE-2.0.html]() for details). We welcome any contributions you want to make to Debezium, but they must be completely authored by you, and you must have the right to contribute them. All contributions to Debezium must be licensed under the Apache License 2.0, just like the project itself.
+
+If you want to fix a bug or make any changes, please log an issue in the [Debezium JIRA](https://issues.jboss.org/browse/DBZ) describing the bug or new feature. Then we highly recommend making the changes on a topic branch named with the JIRA issue number. For example, this command creates a branch for the DBZ-1234 issue:
+
+	$ git checkout -b DBZ-1234
+
+Then make your changes on this branch, and ensure that the entire branch builds with `mvn clean install`. Commit your changes to your branch using reall good comments. You might check for recent changes made in the official repository:
+
+	$ git checkout master               # switches to the 'master' branch
+	$ git pull upstream master          # fetches all 'upstream' changes and merges 'upstream/master' onto your 'master' branch
+	$ git checkout DBZ-1234             # switches to your topic branch
+	$ git rebase master                 # reapplies your changes on top of the latest in master
+	                                    # (i.e., the latest from master will be the new base for your changes)
+
+If the pull grabbed a lot of changes, you should rerun your build to make sure your changes are still good.
+You can then push your topic branch and its changes into your public fork repository:
+
+	$ git push origin DBZ-1234          # pushes your topic branch into your public fork of Debezium
+
+and [generate a pull-request](http://help.github.com/pull-requests/) for your changes. Your pull request will generate a build on our integration server, and the results will be posted on the pull request page. The Debezium committers will also be notified of your pull request and, if your pull request passes all tests, will review your changes. If they have any questions or suggestions, they will add comments and/or line notes. Otherwise, if the changes are acceptable, they'll merge your pull request into the official codebase and close the JIRA issue.

README.md

@@ -1,15 +1,44 @@
+Copyright 2008-2015 Red Hat and contributors. Licensed under the Apache License, Version 2.0.
 
-== Requirements
+# Debezium
 
-The following software is required to build Debezium locally:
+Debezium is an open source project for change data capture tools. With its libraries, your application can monitor databases and receive detailed events for each row-level change made to the database. Only committed changes are visible, so your application doesn't have to worry about transactions or changes that are rolled back. Debezium provides a single model of all change events, so your application does not have to worry about the intricacies of each kind of database management system. Additionally, when your application restarts it is able to consume all of the events it missed while it was not running, ensuring that all events are processed correctly and completely.
 
+Monitoring databases and being notified when data changes has always been complicated. Relational database triggers can be useful, but are often limited to updating state within the same database (not communicating with external processes) and often don't work with views or schema tables. Some databases offer APIs or frameworks for monitoring changes, but there is no standard so each database's approach is different and requires a lot of knowledged and specialized code.
+
+Debezium provides modules that do this work for you. Some modules are generic and work with multiple database management systems, but are also a bit more limited in functionality and performance. Other modules are tailored for specific database management systems, so they are often far more capable and they leverage the specific features of the system. 
+
+## Common use cases
+
+There are a number of scenarios in which Debezium can be extremely valuable, but here we outline just a few of the more common ones.
+
+### Cache invalidation
+
+Automatically purge and/or update a second-level cache when the record(s) for entries change or are removed. The cache and monitoring logic can be in separate processes from the application(s).
+
+### Updating multiple data systems
+
+Many applications need to update a database and then do additional work after the commit, such as update separate search indexes, update a cache, send notifications, activate business logic, etc. If the application were to crash after the commit but before all of these other activities are performed, updates might be lost or other systems might become inconsistent or invalid. Using change data capture, these other activities can be performed in separate threads or separate processes/services when the data is committed in the original database. This approach is more tolerant of failures, does not miss events, scales better, and more easily supports upgrading and operations.
+
+### Pre-computed 
+
+### Event processing
+
+### 
+
+
+## Requirements
+
+The following software is required to work with the Debezium codebase and build it locally:
+
+* [Git 2.2.1](https://git-scm.com) or later
 * [JDK 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html) or [OpenJDK 8](http://openjdk.java.net/projects/jdk8/)
 * [Maven 3.2.1](https://maven.apache.org/index.html) or later
 * [Docker Engine 1.4](http://docs.docker.com/engine/installation/) or later
 
 See the links above for installation instructions on your platform.
 
-=== Docker
+### Why Docker?
 
 Many open source software projects use Java and Maven, but requiring Docker is less common. Debezium is designed to talk to a number of external systems, such as various databases and services, and our integration tests verify Debezium does this correctly. But rather than expect you have all of these software systems installed locally, Debezium's build system uses Docker to automatically download or create the necessary images and start containers for each of the systems. The integration tests can then use these services and verify Debezium behaves as expected, and when the integration tests finish, Debezum's build will automatically stop any containers that it started.
 

debezium-ingest-mysql/README.md

@@ -1,7 +1,7 @@
-== Ingesting MySQL
+## Ingesting MySQL
 
 
-== Unit and integration tests
+## Unit and integration tests
 
 This module contains both unit tests and integration tests.
 
@@ -11,13 +11,39 @@ An *integration test* is a JUnit test class named `*IT.java` or `IT*.java` that
 
 Running `mvn install` will compile all code and run the unit tests. If there are any problems, such as failing unit tests, the build will stop immediately. Otherwise, the build will create the module's artifacts, create the Docker image with MySQL, start the Docker container, run the integration tests, and stop the container even if there are integration test failures. If there are no problems, the build will end by installing the artifacts into the local Maven repository.
 
-You should always default to using `mvn install`, especially prior to committing changes to Git. However, there are a few situations where you may want to run a different Maven command:
+You should always default to using `mvn install`, especially prior to committing changes to Git. However, there are a few situations where you may want to run a different Maven command.
 
-* Normally, the MySQL Docker container is stopped and removed after the integration tests are run. If instead you want to inspect the state of the database(s) after the integration tests are run, you can use `mvn integration-test` to instruct Maven to run the normal Maven lifecycle but stop before shutting down the Docker container during the `post-integration-test` phase. Be aware that you will need to manually stop and remove the container before running the build again, and to make this more convenient we give the MySQL container the alias `database`:
+### Running some tests
+
+If you are trying to get the test methods in a single integration test class to pass and would rather not run *all* of the integration tests, you can instruct Maven to just run that one integration test class and to skip all of the others. For example, use the following command to run the tests in the `ConnectionIT.java` class:
+
+    $ mvn -Dit.test=ConnectionIT install
+
+Of course, wildcards also work:
+
+    $ mvn -Dit.test=Connect*IT install
+
+### Debugging tests
+
+Normally, the MySQL Docker container is stopped and removed after the integration tests are run. One way to debug tests is to configure the build to wait for a remote debugging client, but then you also have to set up your IDE to connect. It's often far easier to debug a single test directly from within your IDE. To do that, you want to start the MySQL Docker container and keep it running:
+
+    $ mvn docker:start
+
+Then use your IDE to run one or more unit tests, optionally debugging them as needed. Just be sure that the unit tests clean up their database before (and after) each test.
+
+To stop the container, simply use Docker to stop and remove the MySQL Docker container named `database`:
 
     $ docker stop database
     $ docker rm database
 
-* If you are trying to get the test methods in a single integration test class to pass and would rather not run *all* of the integration tests, you can instruct Maven to just run that one integration test class and to skip all of the others. For example, use the following command to run the tests in the `ConnectionIT.java` class:
+### Analyzing the database
+
+Sometimes you may want to inspect the state of the database(s) after one or more integration tests are run. The `mvn install` command runs the tests but shuts down and removes the container after the tests complete. To keep the container running after the tests complete, use this Maven command:
+
+    $ mvn integration-test
+
+This instructs Maven to run the normal Maven lifecycle through `integration-test`, and to stop before the `post-integration-test` phase when the Docker container is normally shut down and removed. Be aware that you will need to manually stop and remove the container before running the build again, and to make this more convenient we give the MySQL container the alias `database`:
+
+    $ docker stop database
+    $ docker rm database
 
-    $ mvn -Dit.test=ConnectionIT install

debezium-ingest-postgres/README.md

@@ -1,7 +1,7 @@
-== Ingesting PostgreSQL
+## Ingesting PostgreSQL
 
 
-== Unit and integration tests
+## Unit and integration tests
 
 This module contains both unit tests and integration tests.
 
@@ -11,13 +11,39 @@ An *integration test* is a JUnit test class named `*IT.java` or `IT*.java` that
 
 Running `mvn install` will compile all code and run the unit tests. If there are any problems, such as failing unit tests, the build will stop immediately. Otherwise, the build will create the module's artifacts, create the Docker image with PostgreSQL, start the Docker container, run the integration tests, and stop the container even if there are integration test failures. If there are no problems, the build will end by installing the artifacts into the local Maven repository.
 
-You should always default to using `mvn install`, especially prior to committing changes to Git. However, there are a few situations where you may want to run a different Maven command:
+You should always default to using `mvn install`, especially prior to committing changes to Git. However, there are a few situations where you may want to run a different Maven command.
 
-* Normally, the PostgreSQL Docker container is stopped and removed after the integration tests are run. If instead you want to inspect the state of the database(s) after the integration tests are run, you can use `mvn integration-test` to instruct Maven to run the normal Maven lifecycle but stop before shutting down the Docker container during the `post-integration-test` phase. Be aware that you will need to manually stop and remove the container before running the build again, and to make this more convenient we give the PostgreSQL container the alias `database`:
+### Running some tests
+
+If you are trying to get the test methods in a single integration test class to pass and would rather not run *all* of the integration tests, you can instruct Maven to just run that one integration test class and to skip all of the others. For example, use the following command to run the tests in the `ConnectionIT.java` class:
+
+    $ mvn -Dit.test=ConnectionIT install
+
+Of course, wildcards also work:
+
+    $ mvn -Dit.test=Connect*IT install
+
+### Debugging tests
+
+Normally, the PostgreSQL Docker container is stopped and removed after the integration tests are run. One way to debug tests is to configure the build to wait for a remote debugging client, but then you also have to set up your IDE to connect. It's often far easier to debug a single test directly from within your IDE. To do that, you want to start the PostgreSQL Docker container and keep it running:
+
+    $ mvn docker:start
+
+Then use your IDE to run one or more unit tests, optionally debugging them as needed. Just be sure that the unit tests clean up their database before (and after) each test.
+
+To stop the container, simply use Docker to stop and remove the PostgreSQL Docker container named `database`:
 
     $ docker stop database
     $ docker rm database
 
-* If you are trying to get the test methods in a single integration test class to pass and would rather not run *all* of the integration tests, you can instruct Maven to just run that one integration test class and to skip all of the others. For example, use the following command to run the tests in the `ConnectionIT.java` class:
+### Analyzing the database
+
+Sometimes you may want to inspect the state of the database(s) after one or more integration tests are run. The `mvn install` command runs the tests but shuts down and removes the container after the tests complete. To keep the container running after the tests complete, use this Maven command:
+
+    $ mvn integration-test
+
+This instructs Maven to run the normal Maven lifecycle through `integration-test`, and to stop before the `post-integration-test` phase when the Docker container is normally shut down and removed. Be aware that you will need to manually stop and remove the container before running the build again, and to make this more convenient we give the PostgreSQL container the alias `database`:
+
+    $ docker stop database
+    $ docker rm database
 
-    $ mvn -Dit.test=ConnectionIT install