[ 
https://issues.apache.org/jira/browse/SCB-330?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16356675#comment-16356675
 ] 

ASF GitHub Bot commented on SCB-330:
------------------------------------

WillemJiang closed pull request #134: SCB-330 update document of pack
URL: https://github.com/apache/incubator-servicecomb-saga/pull/134
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/README.md b/README.md
old mode 100755
new mode 100644
index 9a7249f5..fd569ea6
--- a/README.md
+++ b/README.md
@@ -1,76 +1,36 @@
 # Saga [![Build 
Status](https://travis-ci.org/apache/incubator-servicecomb-saga.svg?branch=master)](https://travis-ci.org/apache/incubator-servicecomb-saga?branch=master)
 [![Coverage 
Status](https://coveralls.io/repos/github/apache/incubator-servicecomb-saga/badge.svg?branch=master)](https://coveralls.io/github/apache/incubator-servicecomb-saga?branch=master)
 
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
-Apache ServiceComb (incubating) Saga is a type of Compensating Transaction 
pattern, which provides a simple way to help users solve the data consistency 
problems encountered in micro-service applications.
+Apache ServiceComb (incubating) Saga is an eventually data consistency 
solution for micro-service applications. Transactions are commited directly in 
the try phase and compensated in reverse order in the rollback phase comparing 
to [TCC](http://design.inf.usi.ch/sites/default/files/biblio/rest-tcc.pdf). 
 
-## Documentation
-Reference documentation is available on the [ServiceComb 
website][servicecomb-website].
+## Features
+* High availability. The coordinator is stateless and thus can have multiple 
instances.
+* High reliability. All transaction events are stored in database permanently.
+* High performance. Transaction events are reported to coordinator via gRPC 
and transaction payloads are serialized/deserialized by Kyro.
+* Low invasion. All you need to do is add 2-3 annotations and the 
corresponding compensate methods.
+* Easy to deploy. All components can boot via docker.
+* Supported micro-service frameworks:
+  + Spring Cloud
+* Support both forward(retry) and backward(compensate) recovery.
 
-[servicecomb-website]: http://servicecomb.incubator.apache.org/
+## Architecture
+Saga is composed of  **alpha** and **omega**.
+* The alpha plays as the coordinator. It is responsible for the management of 
transactions.
+* The omega plays as an agent inside the micro-service. It intercepts 
incoming/outgoing requests and reports transaction events to alpha.
 
-## Major Architecture of Saga
-* saga-core(transaction and compensation handling logic)
-* saga-format(data serialization and deserialization)
-* saga-transports(communication protocol implementation such as rest or rpc in 
the future)
-* saga-discovery(service discovery)
-* saga-spring(restful service framework)
+The following diagram shows the relationships among alpha, omega and services.
+![Saga Pack Architecture](docs/static_files/pack.png)
 
-![Saga](docs/static_files/saga.png) 
+See [Saga Pack Design](docs/design.md) for details. If you are interested in 
our previous architecture, please move forward to [Old Saga's 
Documentation](docs/old_saga.md).
 
-## Prerequisites
-You will need:
-1. [Oracle JDK 1.8+][jdk]
-2. [Maven 3.x][maven]
-3. [Docker][docker]
-4. [PostgreSQL][postgres]
-5. [Service Center(optional)][service_center]
-6. [Docker compose(optional)][docker_compose]
-7. [Docker machine(optional)][docker_machine]
+## Get Started
+See [Booking Demo](saga-demo/pack-demo/README.md) for details.
 
-
-[jdk]: 
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
-[maven]: https://maven.apache.org/install.html
-[docker]: https://www.docker.com/get-docker
-[postgres]: https://www.postgresql.org/download/
-[service_center]: 
https://github.com/apache/incubator-servicecomb-service-center
-[docker_compose]: https://docs.docker.com/compose/install/
-[docker_machine]: https://docs.docker.com/machine/install-machine/
-
-
-
-## Building
-Download the source code.
-```
-git clone https://github.com/apache/incubator-servicecomb-saga.git
-```
-
-Enter the Saga root directory,build Saga project by maven command and generate 
a docker image named saga-spring in local.
-```
-mvn package -DskipTests -Pdocker
-```
-
-## Run Services
-A `docker-compose.yaml` file is provided to start Saga services and its 
dependencies(Service center and Mysql) as docker containers.
-User also can configure specified Service center or Mysql in 
`docker-compose.yaml`.
-
-Enter the Saga root directory, run all service images using command,
-```
-docker-compose up
-```
-
-
-## Reference API
-See [Saga API](docs/api/api.md) for details.
-
-
-## Example
-See [Saga 
demo](https://github.com/apache/incubator-servicecomb-saga/tree/master/saga-demo)
 for details.
-
-## Contact
-Bugs: [issues](https://issues.apache.org/jira/browse/SCB).
-
-Mailing lists: 
[subscribe](mailto:dev-subscr...@servicecomb.incubator.apache.org) 
[dev](https://lists.apache.org/list.html?d...@servicecomb.apache.org)
+## Contact Us
+* [issues](https://issues.apache.org/jira/browse/SCB)
+* [gitter](https://gitter.im/ServiceCombUsers/Lobby)
+* mailing list: 
[subscribe](mailto:dev-subscr...@servicecomb.incubator.apache.org) 
[view](https://lists.apache.org/list.html?d...@servicecomb.apache.org)
 
 ## Contributing
-See [Pull Request Guide](http://servicecomb.io/developers/submit-codes/) for 
details.
+See [Pull Request 
Guide](http://servicecomb.incubator.apache.org/developers/submit-codes/) for 
details.
 
-## Reporting Issues
-See reporting bugs for details about reporting any issues.
+## License
+Licensed under an [Apache 
2.0](https://github.com/apache/incubator-servicecomb-saga/blob/master/LICENSE) 
license.
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 00000000..625cb95b
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,31 @@
+# Saga Pack Design
+## Overview
+Pack contains two components: *alpha* and *omega*. Alpha is the pack leader 
and backed by database to make sure transaction events stored permanently while 
omega is the pack worker and embeded inside services to intercept 
incoming/outgoing requests and report events to alpha.
+
+![Pack Architecture](static_files/pack.png)
+
+## Omega Internal
+Omega plays as an embeded agent inside services. When a request arrives, omega 
intercepts its header and retrieve the global transaction id as its global 
transaction id and retrieve the local transaction id as its parent transaction 
id. In pre-process phase, a transaction started event will be recorded in 
alpha. In post-process phase, a transaction ended event will be recorded in 
alpha to mark the end of the sub-transaction.
+
+![Omega Internal](static_files/omega_internal.png)
+
+## Inter-Service Communication
+The process of Inter-Service Communication is similiar to 
[Zipkin](https://github.com/openzipkin/zipkin)'s. In the producer side, omega 
intercepts the transaction ids from request to retrieve the transaction 
context. In the consumer side, omega inject the transaction ids into request to 
pass the transaction context. Sub-transactions can chain as a single global 
transaction by co-operating producers and consumers.
+
+![Inter-Service Communication](static_files/inter-service_communication.png)
+
+## Workflow
+### Successful Scenario
+In a successful scenario, all started events will have a corresponding ended 
event.
+
+![Successful Scenario](static_files/successful_scenario.png)
+
+### Exception Scenario
+In an exception scenario, omega inside the abnormal service will report an 
aborted event to alpha. Apha will then send compensate commands to the 
completed events within the global transaction to make suer all 
sub-transactions are either completed or rollbacked.
+
+![Exception Scenario](static_files/exception_scenario.png)
+
+### Timeout Scenario
+In timeout scenario, timeouted events will be detected by alpha's periodly 
scanner and abort the corresponding global transaction.
+
+![Timeout Scenario](static_files/timeout_scenario.png)
diff --git a/docs/old_saga.md b/docs/old_saga.md
new file mode 100755
index 00000000..2b79d221
--- /dev/null
+++ b/docs/old_saga.md
@@ -0,0 +1,53 @@
+# Previous Saga's Documentation
+## Major Architecture of Saga
+* saga-core(transaction and compensation handling logic)
+* saga-format(data serialization and deserialization)
+* saga-transports(communication protocol implementation such as rest or rpc in 
the future)
+* saga-discovery(service discovery)
+* saga-spring(restful service framework)
+
+![Saga](static_files/saga.png) 
+
+## Prerequisites
+You will need:
+1. [Oracle JDK 1.8+][jdk]
+2. [Maven 3.x][maven]
+3. [Docker][docker]
+4. [PostgreSQL][postgres]
+5. [Service Center(optional)][service_center]
+6. [Docker compose(optional)][docker_compose]
+7. [Docker machine(optional)][docker_machine]
+
+[jdk]: 
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
+[maven]: https://maven.apache.org/install.html
+[docker]: https://www.docker.com/get-docker
+[postgres]: https://www.postgresql.org/download/
+[service_center]: 
https://github.com/apache/incubator-servicecomb-service-center
+[docker_compose]: https://docs.docker.com/compose/install/
+[docker_machine]: https://docs.docker.com/machine/install-machine/
+
+## Building
+Download the source code.
+```
+git clone https://github.com/apache/incubator-servicecomb-saga.git
+```
+
+Enter the Saga root directory,build Saga project by maven command and generate 
a docker image named saga-spring in local.
+```
+mvn package -DskipTests -Pdocker
+```
+
+## Run Services
+A `docker-compose.yaml` file is provided to start Saga services and its 
dependencies(Service center and Mysql) as docker containers.
+User also can configure specified Service center or Mysql in 
`docker-compose.yaml`.
+
+Enter the Saga root directory, run all service images using command,
+```
+docker-compose up
+```
+
+## Reference API
+See [Saga API](docs/api/api.md) for details.
+
+## Example
+See [Saga 
demo](https://github.com/apache/incubator-servicecomb-saga/tree/master/saga-demo)
 for details.
diff --git a/docs/static_files/exception_scenario.png 
b/docs/static_files/exception_scenario.png
new file mode 100644
index 00000000..a8738baf
Binary files /dev/null and b/docs/static_files/exception_scenario.png differ
diff --git a/docs/static_files/inter-service_communication.png 
b/docs/static_files/inter-service_communication.png
new file mode 100644
index 00000000..11d8dffb
Binary files /dev/null and b/docs/static_files/inter-service_communication.png 
differ
diff --git a/docs/static_files/omega_internal.png 
b/docs/static_files/omega_internal.png
new file mode 100644
index 00000000..1f130a2c
Binary files /dev/null and b/docs/static_files/omega_internal.png differ
diff --git a/docs/static_files/pack.png b/docs/static_files/pack.png
new file mode 100644
index 00000000..2c30c00e
Binary files /dev/null and b/docs/static_files/pack.png differ
diff --git a/docs/static_files/successful_scenario.png 
b/docs/static_files/successful_scenario.png
new file mode 100644
index 00000000..5dd8850c
Binary files /dev/null and b/docs/static_files/successful_scenario.png differ
diff --git a/docs/static_files/timeout_scenario.png 
b/docs/static_files/timeout_scenario.png
new file mode 100644
index 00000000..998cfcfb
Binary files /dev/null and b/docs/static_files/timeout_scenario.png differ
diff --git a/saga-demo/pack-demo/README.md b/saga-demo/pack-demo/README.md
index 1e8d7007..9eecd623 100644
--- a/saga-demo/pack-demo/README.md
+++ b/saga-demo/pack-demo/README.md
@@ -4,6 +4,18 @@ This demo simulates a booking application including three 
services:
 * pack-car
 * pack-hotel
 
+## Prerequisites
+You will need:
+1. [JDK 1.8][jdk]
+2. [Maven 3.x][maven]
+3. [Docker][docker]
+4. [Docker compose][docker_compose]
+
+[jdk]: 
http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html
+[maven]: https://maven.apache.org/install.html
+[docker]: https://www.docker.com/get-docker
+[docker_compose]: https://docs.docker.com/compose/install/
+
 ## Running Demo
 1. run the following command to create docker images in saga project root 
folder.
 ```


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org


> [pack] update documents of saga pack
> ------------------------------------
>
>                 Key: SCB-330
>                 URL: https://issues.apache.org/jira/browse/SCB-330
>             Project: Apache ServiceComb
>          Issue Type: Improvement
>          Components: Saga
>    Affects Versions: saga-0.1.0
>            Reporter: Eric Lee
>            Assignee: Eric Lee
>            Priority: Major
>             Fix For: saga-0.1.0
>
>
> As a dev, I want to know how to use the Saga's new architecture pack. 
> Documents including README and quick start should contain details of its 
> usages, features and architecture.



--
This message was sent by Atlassian JIRA
(v7.6.3#76005)

Reply via email to