Polish web-site documents
Project: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/commit/fbef4631 Tree: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/tree/fbef4631 Diff: http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/diff/fbef4631 Branch: refs/heads/asf-site Commit: fbef4631dd407793d7ffdde81771a5c88f7ce6d9 Parents: 899327e Author: Li Zhanhui <[email protected]> Authored: Thu Jun 8 13:08:18 2017 +0800 Committer: Li Zhanhui <[email protected]> Committed: Thu Jun 8 13:08:18 2017 +0800 ---------------------------------------------------------------------- _data/navigation.yml | 7 ++- _docs/01-quick-start-guide.md | 5 +- _docs/02-motivation.md | 17 ++++-- _docs/03-core-concept.md | 24 ++++---- _docs/04-cli-admin-tool.md | 16 ++--- _docs/05-cluster-deployment.md | 2 +- _docs/06-best-practice-pull-request.md | 55 ++++++++--------- _docs/07-code-guidelines.md | 2 +- _docs/07-frequently-asked-questions.md | 88 +++++++++++++-------------- _docs/08-release-manual.md | 48 +++++++-------- _docs/11-rocketmq-road-map.md | 28 ++++----- _docs/12-rmq-batch-example.md | 12 ++-- _docs/13-rmq-broadcasting-example.md | 6 +- _docs/14-rmq-deployment.md | 26 ++++---- _docs/16-rmq-architecture.md | 16 ++--- _docs/18-simple-example.md | 24 ++++---- _docs/best-practice-consumer.md | 24 ++++---- _docs/best-practice-create-pr.md | 84 +++++++++++++++++++++++++ _docs/best-practice-namesvr.md | 26 ++++---- _docs/best-practice-producer.md | 40 ++++++------ _pages/community.md | 2 +- _pages/customer.md | 9 ++- _sass/_archive.scss | 4 +- assets/images/community/tree-logo.png | Bin 0 -> 9954 bytes assets/images/community/yhsoft-logo.png | Bin 0 -> 18076 bytes assets/images/eco.png | Bin 0 -> 116702 bytes 26 files changed, 333 insertions(+), 232 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_data/navigation.yml ---------------------------------------------------------------------- diff --git a/_data/navigation.yml b/_data/navigation.yml index 5185f2d..cc6c8cd 100644 --- a/_data/navigation.yml +++ b/_data/navigation.yml @@ -35,6 +35,8 @@ docs: url: /docs/batch-example/ - title: "Filter Example" url: /docs/filter-by-sql92-example/ + - title: "FAQ" + url: /docs/faq/ - title: Deployment & Operations children: @@ -51,7 +53,7 @@ docs: url: /docs/code-guidelines/ #- title: "Branching Model" # url: /docs/branching-model - - title: "Pull Request" + - title: "Manage Pull Request" url: /docs/pull-request/ - title: "Release Manual" url: /docs/release-manual @@ -76,8 +78,7 @@ docs: url: /release_notes/release-notes-4.0.0-incubating/ - title: RoadMap url: /docs/roadmap/ - - title: FAQ - url: /docs/faq/ + about: - title: Team http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/01-quick-start-guide.md ---------------------------------------------------------------------- diff --git a/_docs/01-quick-start-guide.md b/_docs/01-quick-start-guide.md index e298d39..cd7d4f2 100644 --- a/_docs/01-quick-start-guide.md +++ b/_docs/01-quick-start-guide.md @@ -5,7 +5,8 @@ excerpt: "How to quickly install and setup Apache RocketMQ." modified: 2016-12-29T15:01:43-04:00 --- -This quick start guide is a detailed instruction of setting up RocketMQ messaging system on a local machine and sending/receiving messages. +This quick start guide is a detailed instruction of setting up RocketMQ messaging system on your local machine to send +and receive messages. {% include toc %} @@ -42,7 +43,7 @@ This quick start guide is a detailed instruction of setting up RocketMQ messagin > tail -f ~/logs/rocketmqlogs/broker.log The broker[%s, 172.30.30.233:10911] boot success... ``` - + # Send & Receive Messages http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/02-motivation.md ---------------------------------------------------------------------- diff --git a/_docs/02-motivation.md b/_docs/02-motivation.md index 14eb57a..b15cee2 100644 --- a/_docs/02-motivation.md +++ b/_docs/02-motivation.md @@ -4,16 +4,25 @@ permalink: /docs/motivation/ modified: 2016-12-16T15:01:43-04:00 --- -At early stages, we constructed our distributed messaging middleware based on ActiveMQ 5.x(prior to 5.3). Our multinational business uses it for async communication, search, social network activity stream, data pipeline, even in its trade processes. As our trade business throughput rises, pressure originating from our messaging cluster also become urgent. +At early stages, we constructed our distributed messaging middleware based on ActiveMQ 5.x(prior to 5.3). Our +multinational business uses it for asynchronous communication, search, social network activity stream, data pipeline, +even in its trade processes. As our trade business throughput rises, pressure originating from our messaging cluster +also becomes urgent. {% include toc %} # Why RocketMQ ? -Based on our research, with increased queues and virtual topics in use, ActiveMQ IO module reaches a bottleneck. We tried our best to solve this problem through throttling, circuit breaker or degradation, but it didn't work well. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements especially low latency and high reliability, see [here](/rocketmq/how-to-support-more-queues-in-rocketmq/) for details. +Based on our research, with increased queues and virtual topics in use, ActiveMQ IO module reaches a bottleneck. We +tried our best to solve this problem through throttling, circuit breaker or degradation, but it did not work well. So +we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our +requirements especially in terms of low latency and high reliability, see [here](/rocketmq/how-to-support-more-queues-in-rocketmq/) for details. -In this context, we decided to invent a new messaging engine to handle a broader set of use cases, ranging from traditional pub/sub scenarios to high volume realtime zero-loss tolerance transaction system. We believe this solution can be beneficial, so we would like to open source it to the community. Today, more than 100 companies are using the open source version of RocketMQ in their business. We also published a commercial distribution based on RocketMQ, a Platform as a Service (PaaS) product called the -[Alibaba Cloud Platform](https://intl.aliyun.com/). +In this context, we decided to invent a new messaging engine to handle a broader set of use cases, ranging from +traditional pub/sub scenarios to high volume real-time zero-loss tolerance transaction system. We believe this solution +can be beneficial, so we would like to open source it to the community. Today, more than 100 companies are using the +open source version of RocketMQ in their business. We also published a commercial distribution based on RocketMQ, a PaaS + product called the [Alibaba Cloud Platform](https://intl.aliyun.com/). The following table demonstrates the comparison between RocketMQ, ActiveMQ and Kafka (Apache's most popular messaging solutions according to [awesome-java](https://github.com/akullpp/awesome-java)): http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/03-core-concept.md ---------------------------------------------------------------------- diff --git a/_docs/03-core-concept.md b/_docs/03-core-concept.md index 06d4add..ec0734a 100644 --- a/_docs/03-core-concept.md +++ b/_docs/03-core-concept.md @@ -6,7 +6,7 @@ modified: 2016-12-16T15:01:43-04:00  -From the above model, we can look deeper into some topics about messaging system design: +According to the above model, we can dig deeper into some topics about messaging system design: {% include toc %} @@ -23,9 +23,9 @@ A producer sends messages generated by the business application systems to broke ## Producer Group -Producers of the same role are grouped together. A different producer instance of the same producer group may be contacted by a broker to commit or roll back a transaction in case the original producer crashed after starting the transaction. +Producers of the same role are grouped together. A different producer instance of the same producer group may be contacted by a broker to commit or roll back a transaction in case the original producer crashed after the transaction. -**Warning**: Considering the provided producer is sufficiently powerful at sending messages, only one instance is allowed per producer group and process to avoid unnecessarily initializing of producer instances. +**Warning**: Considering the provided producer is sufficiently powerful at sending messages, only one instance is allowed per producer group to avoid unnecessary initialization of producer instances. # Consumer @@ -37,7 +37,7 @@ A Consumer pulls messages from brokers and feeds them into application. In persp ## PushConsumer - Push consumer, on the other hand, encapsulates message pulling, consuming progress maintaining and other effortful work inside, leaving a callback interface to end user to implement which will be executed on message arrival. + Push consumer, on the other hand, encapsulates message pulling, consuming progress and maintaining other work inside, leaving a callback interface to end user to implement which will be executed on message arrival. ## Consumer Group @@ -45,31 +45,31 @@ Similar to previously mentioned producer group, consumers of the exactly same ro Consumer Group is a great concept with which achieving goals of load-balance and fault-tolerance, in terms of message consuming, is super easy. -**Warning**: consumer instances of a consumer group **must** have exactly same topic subscription(s). +**Warning**: consumer instances of a consumer group **must** have exactly the same topic subscription(s). # Topic -Topic is a category to which producers deliver messages and from which consumers pull messages. Topics have very loose relation with producers and consumers. Specifically, a topic may have zero, one or multiple producers that sends messages to it; conversely, a producer can sends messages of different topics. In consumer's view, a topic may be subscribed by zero, one or multiple consumer groups; and a consumer group, in the same paradigm, may subscribe one or multiple topics as long as instances of this group keep their subscription consistent as emphasized in the previous section. +Topic is a category in which producers deliver messages and consumers pull messages. Topics have very loose relationship with producers and consumers. Specifically, a topic may have zero, one or multiple producers that sends messages to it; conversely, a producer can send messages of different topics. In consumer's perspective, a topic may be subscribed by zero, one or multiple consumer groups. And a consumer group, similarly, may subscribe to one or more topics as long as instances of this group keep their subscription consistent. # Message -Message is the envelope of your information to deliver. A message must be specified with a topic, which can be interpreted as address of your letter to mail to. A message may also have an optional tag set. Extra key-value pairs may also be included. For example, you may set a business key for your message and look up the message on broker server to diagnose issues during development. +Message is the information to be delivered. A message must have a topic, which can be interpreted as address of your letter to mail to. A message may also have an optional tag and extra key-value pairs. For example, you may set a business key to your message and look up the message on a broker server to diagnose issues during development. ## Message Queue -Topic, internally, is logically partitioned into one or more sub-topics. We call these sub-topics "message queues". This concept plays a major role in implementing valuable features, including fail-over, maximum concurrency, etc. +Topic is partitioned into one or more sub-topics, "message queues". ## Tag -Tag, which can be thought as sub-topic, provides an extra flexibility for user. Through introducing tag, messages with different purposes from the same business module may have the same topic yet different tag. It would be helpful to keep your code clean and coherent. +Tag, in other words sub-topic, provides extra flexibility to users. With tag, messages with different purposes from the same business module may have the same topic and different tag. Tags would be helpful to keep your code clean and coherent, and tags also can facilitate the query system RocketMQ provides. ## Broker -Broker is the major role of the RocketMQ system. It receives messages sent from producers, store them and being prepared to serve pull requests from consumers. It also stores message consuming related meta data, including consumer groups, consuming progress offsets and topic / queue info. +Broker is a major component of the RocketMQ system. It receives messages sent from producers, store them and prepare to handle pull requests from consumers. It also stores message related meta data, including consumer groups, consuming progress offsets and topic / queue info. # Name Server -Name server serves as the routing information provider. Producer/Consumer clients look up topics to find broker list to read from and write to. +Name server serves as the routing information provider. Producer/Consumer clients look up topics to find the corresponding broker list. # Message Model @@ -89,7 +89,7 @@ Consuming messages orderly means messages are consumed the same order they are s * Concurrently -When consuming concurrently, maximum concurrency of message consuming is only limited by thread pool specified for each consumer client. +When consuming messages concurrently, maximum concurrency of message consuming is only limited by thread pool specified for each consumer client. **Warn**: Message order is no longer guaranteed in this mode. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/04-cli-admin-tool.md ---------------------------------------------------------------------- diff --git a/_docs/04-cli-admin-tool.md b/_docs/04-cli-admin-tool.md index aa2ef44..943c8be 100644 --- a/_docs/04-cli-admin-tool.md +++ b/_docs/04-cli-admin-tool.md @@ -15,15 +15,15 @@ Make sure you have walked through [Quick Start](/docs/quick-start/) and [Core Co # How To Get it -The admin tool is shipped along with RocketMQ. Either you download a pre-built binary version or build from source by yourself, you already have it. +The admin tool is shipped along with RocketMQ. Whether you download a pre-built binary version or build from source by yourself, you have the tool with the package. -In case you don't have source code, the [rocketmq-tools module](https://github.com/apache/incubator-rocketmq/tree/master/tools) contains its source code. +If you want to look at the source code, please refer to [rocketmq-tools module](https://github.com/apache/incubator-rocketmq/tree/master/tools) # How to use -The Admin Tool is very easy to use. Here, for demonstration purpose, *nix environment is assumed. +The Admin Tool is very user friendly. Here, for demonstration purpose, *nix environment is assumed. -Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the following help menu pops out. +Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the following help menu. The most commonly used mqadmin commands are: updateTopic Update or create topic @@ -34,7 +34,7 @@ Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the f updateTopicPerm Update topic perm topicRoute Examine topic route info topicStatus Examine topic Status info - topicClusterList get cluster info for topic + topicClusterList Get cluster info for topic brokerStatus Fetch broker runtime status data queryMsgById Query Message by Id queryMsgByKey Query Message by Key @@ -42,13 +42,13 @@ Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the f queryMsgByOffset Query Message by offset queryMsgByUniqueKey Query Message by Unique key printMsg Print Message Detail - sendMsgStatus send msg to broker. + sendMsgStatus Send msg to broker. brokerConsumeStats Fetch broker consume stats data producerConnection Query producer's socket connection and client version consumerConnection Query consumer's socket connection, client version and subscription consumerProgress Query consumers's progress, speed consumerStatus Query consumer's internal data structure - cloneGroupOffset clone offset from other group. + cloneGroupOffset Clone offset from other group. clusterList List all of clusters topicList Fetch all topic list from name server updateKvConfig Create or update KV config. @@ -62,7 +62,7 @@ Change directory to ${PACKAGE}/bin, command `bash mqadmin`, you should see the f statsAll Topic and Consumer tps stats syncDocs Synchronize wiki and issue to github.com allocateMQ Allocate MQ - checkMsgSendRT check message send response time + checkMsgSendRT Check message send response time clusterRT List All clusters Message Send RT See 'mqadmin help <command>' for more information on a specific command. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/05-cluster-deployment.md ---------------------------------------------------------------------- diff --git a/_docs/05-cluster-deployment.md b/_docs/05-cluster-deployment.md index 7874f89..38c41c8 100644 --- a/_docs/05-cluster-deployment.md +++ b/_docs/05-cluster-deployment.md @@ -22,7 +22,7 @@ Name server follows share-nothing design paradigm. Brokers send heartbeat data t # Broker -Brokers can be divided into two categories according to their roles: master and slave. Master brokers can read and write while slave brokers can only read messages replicated from master. Master brokers have brokerId=0; brokerId of slave is non-zero. +Brokers can be divided into two categories according to their roles: master and slave. Master brokers can read and write while slave brokers can only read messages replicated from master. Master brokers have brokerID=0; brokerID of slave is non-zero. Brokers may also be grouped by the brokerName property. Slave brokers find their master through brokerName. One master broker along with zero, one or multiple slave brokers is called a broker set. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/06-best-practice-pull-request.md ---------------------------------------------------------------------- diff --git a/_docs/06-best-practice-pull-request.md b/_docs/06-best-practice-pull-request.md index 7442604..321ba1a 100644 --- a/_docs/06-best-practice-pull-request.md +++ b/_docs/06-best-practice-pull-request.md @@ -1,5 +1,5 @@ --- -title: "Best Practice in Pull Request" +title: "How to manage Pull Request" permalink: /docs/pull-request/ modified: 2016-12-24T15:01:43-04:00 --- @@ -16,13 +16,12 @@ First of all, fork githubâs `apache/incubator-rocketmq` to your own account on Cloning this locally will set up `origin` to point to your remote fork on github as the default remote. Now you can create your pull requests. -You will need to update a local master sometimes (to merge to your development branches sometimes). +You will need to update a local master sometimes (to merge to your development branches). For this, you have to add remote for RocketMQ mirror as follows, git remote add upstream https://github.com/apache/incubator-rocketmq.git -and update your local master via `git fetch` followed by `git rebase`, for instance, as follows - +and update your local master via `git fetch` followed by `git rebase`, for instance: git fetch upstream master git rebase upstream/master @@ -48,14 +47,14 @@ Now if you want to experiment with a branch everything, by default, points to yo git checkout -b ROCKETMQ-xxxx #xxxx typically is a JIRA ticket number -_To guarantee code quality of the master branch, all but minor changes should go through pull requests reviewed by peer committers._ +_To ensure the code quality of the master branch, all but minor changes should go through pull requests reviewed by peer committers._ # Do some work on the branch git commit -a -m "doing some work" git push origin ROCKETMQ-xxxx # notice pushing to **origin** not **apache** -Once you are ready to commit to the apache remote you can merge and push them directly or better yet create a PR. +Once you are ready to commit to the apache remote you can merge and push them directly, otherwise always create a PR. # How to create a PR (committers) @@ -64,48 +63,48 @@ Push your branch to Github: git checkout ROCKETMQ-xxxx git push origin ROCKETMQ-xxxx -1. Go to your ROCKETMQ-xxxx branch on Github. Since you forked it from Github's apache/incubator-rocketmq. it will default any PR to go to apache/master. +1. Go to your ROCKETMQ-xxxx branch on Github. Since you forked it from Github's apache/incubator-rocketmq. By default all PR will go to apache/master. -2. Click the green "Compare, review, and create pull request" button.You can edit the to and from for the PR if it isn't correct. The "base fork" should be apache/incubator-rocketmq unless you are collaborating separately with one of the committers on the list. The "base" will be master. Don't submit a PR to one of the other branches unless you know what you are doing. The "head fork" will be your forked repo and the "compare" will be your ROCKETMQ-xxxx branch. +2. Click the green "Compare, review, and create pull request" button. You can edit the to and from for the PR if it isn't correct. The "base fork" should be apache/incubator-rocketmq unless you are collaborating with one of the committers on the list. The "base" will be master. Don't submit a PR to any other branches unless permitted by branch owner. The "head fork" will be your forked repo and the "compare" will be your ROCKETMQ-xxxx branch. 3. Click the "Create pull request" button and name the request "ROCKETMQ-xxxx" all caps. This will connect the comments of the PR to the mailing list and JIRA comments. -4. From now on the PR lives on github's apache/incubator-rocketmq. You use the commenting UI there. -5. If you are looking for a review or sharing with someone else say so in the comments but don't worry about automated merging of your PR -- you will have to do that later. The PR is tied to your branch so you can respond to comments, make fixes, and commit them from your local repo. They will appear on the PR page and be mirrored to Jira and the mailing list. -6. When you are satisfied and want to push it to Apache's remote repo proceed with Merging a PR +4. From now on the PR lives on github's apache/incubator-rocketmq. You can use the commenting UI there. +5. If you are looking for a review or wanting to share with someone else please write a note in the comments and don't worry about automated merging of your PR -- you will have to do that later. The PR is tied to your branch so you can respond to comments, make fixes, and commit them from your local repo. They will appear on the PR page and be mirrored to JIRA and the mailing list. +6. When you are satisfied and want to push it to Apache's remote repo, you can merge this PR. # How to create a PR (contributors) Before you create a pull request, make sure 1. A corresponding [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ/) issue is created and has a clear problem description. -2. You follow [Coding Guidelines](/docs/code-guidelines/). -3. You have unit tests for it, whenever applicable. +2. Make sure you follow [Coding Guidelines](/docs/code-guidelines/). +3. You have unit tests for everything you are about to commit. -For information on creating pull requests, see [GitHub PR docs](https://help.github.com/articles/creating-a-pull-request/). +For information about creating pull requests, please check [GitHub PR docs](https://help.github.com/articles/creating-a-pull-request/). Pull requests are made to `apache/incubator-rocketmq` repository on Github. -In the Github UI you should pick the master branch to target the PR as described in the section for committers. <br /> -You pull request will be reviewed and commented by committers, and issues can be discussed the contribution in progress. When all reviewers are positive on the pull request, it will be merged. +In the Github UI you should pick the master branch as target of the PR. <br /> +You pull request will be reviewed and commented by committers, and issues can be discussed. When all reviewers are positive on the pull request, it will be merged. # Merging a PR (yours or contributors) -Start with reading [GitHub PR merging locally](https://help.github.com/articles/checking-out-pull-requests-locally/). Remember that pull requests are equivalent to a remote github branch with potentially a multitude of commits. In this case it is recommended to squash remote commit history to have one commit per issue, rather than merging in a multitude of contributor's commits. In order to do that, as well as close the PR at the same time, it is recommended to use squash commits. +Start with reading [GitHub PR merging locally](https://help.github.com/articles/checking-out-pull-requests-locally/). Remember that pull requests are equivalent to a remote github branch with potentially a multitude of commits. In this case it is recommended to squash remote commit history to have one commit per issue, rather than merging in a multitude of contributor's commits. In order to do that, as well as to close the PR at the same time, it is recommended to use squash commits. Merging pull requests are equivalent to a "pull" of a contributor's branch: git checkout master # switch to local master branch git pull apache master # fast-forward to current remote HEAD git pull --squash https://github.com/cuser/incubator-rocketmq.git ROCKETMQ-xxxx # merge to master -`--squash` ensures all PR history is squashed into single commit, and allows committer to use his/her own message. Read git help for merge or pull for more information about `--squash` option. In this example we assume that the contributor's Github handle is "cuser" and the PR branch name is "ROCKETMQ-xxxx". Next, resolve conflicts, if any, or ask a contributor to rebase on top of master, if PR went out of sync. +`--squash` ensures all PR history is squashed into single commit, and allows committer to use his/her own message. Please refer to git help for merge or pull for more information about `--squash` option. In this example we assume that the contributor's Github handle is "cuser" and the PR branch name is "ROCKETMQ-xxxx". Next, resolve all conflicts, or ask a contributor to rebase on top of master, if PR went out of sync. -If you are ready to merge your own (committer's) PR you probably only need to merge (not pull), since you have a local copy that you've been working on. This is the branch that you used to create the PR. +If you are ready to merge your own (committer's) PR you only need to merge (not pull), since you have a local copy that you've been working on. This is the branch that you used to create the PR. git checkout master # switch to local master branch git pull apache master # fast-forward to current remote HEAD git merge --squash ROCKETMQ-xxxx -Remember to run regular patch checks, build with tests enabled, and change CHANGELOG. -If everything is fine, you now can commit the squashed request along the lines +Please run regular patch checks, build with tests enabled, and change CHANGELOG whenever needed. +If all requirements are met, you can commit the squashed request using: git commit --author="contributor_name <contributor_email>" -a -m "ROCKETMQ-XXXX description closes apache/incubator-rocketmq#ZZ" -ROCKETMQ-XXXX is all caps and where ZZ is the pull request number on apache/incubator-rocketmq repository. Including "closes apache/incubator-rocketmq#ZZ" will close the PR automatically. More information is found here [GitHub PR closing docs.](https://help.github.com/articles/closing-issues-via-commit-messages/). +ROCKETMQ-XXXX is all capitalized and ZZ is the pull request number on apache/incubator-rocketmq repository. Including "closes apache/incubator-rocketmq#ZZ" will close the PR automatically. More information can be found here [GitHub PR closing docs.](https://help.github.com/articles/closing-issues-via-commit-messages/). Next, push to git-wip-us.apache.org: git push apache master @@ -115,7 +114,7 @@ The PR, once pushed, will get mirrored to github. To update your github version git push origin master -Note on squashing: Since squash discards remote branch history, repeated PRs from the same remote branch are difficult for merging. The workflow implies that every new PR starts with a new rebased branch. This is more important for contributors to know, rather than for committers, because if new PR is not mergeable, github would warn to begin with. Anyway, watch for dupe PRs (based on same source branches). This is a bad practice. +Note on squashing: Since squash discards remote branch history, repeated PRs from the same remote branch are difficult to be merged. The workflow implies that every new PR starts with a new rebased branch. This is more important for contributors to know, rather than for committers, because if new PR is not mergeable, github would warn at the start. Please watch for dupe PRs (based on same source branches). # Closing a PR without committing (for committers) When we want to reject a PR (close without committing), we can just issue an empty commit on master's HEAD without merging the PR: @@ -130,18 +129,18 @@ that should close PR ZZ on github mirror without merging and any code modificati Read [infra blog](https://blogs.apache.org/infra/entry/improved_integration_between_apache_and). Comments and PRs with RocketMQ issue handles should post to mailing lists and JIRA. RocketMQ issue handles must in the form ROCKETMQ-YYYYY (all capitals). Usually it makes sense to file a JIRA issue first, and then create a PR with description ROCKETMQ-YYYY: <jira-issue-description> -In this case all subsequent comments will automatically be copied to jira without having to mention JIRA issue explicitly in each comment of the PR. +All subsequent comments will then automatically be copied to JIRA. # Best Practises ## Avoiding accidentally committing private branches to the ASF repo -Its dangerously easy âespecially when using IDEsâ to accidentally commit changes to the ASF repo, be it direct to the trunk, branch-2 or other standard branch on which you are developing, or to a private branch you had intended to keep on github (or a private repo). +It's dangerous âespecially when using IDEsâ to accidentally commit changes to the ASF repo, be directed to the trunk, branch-2, other standard branch on which you are developing, or to a private branch you had intended to keep on github (or a private repo). -Committers can avoid this by having the directory in which they develop code set up with read only access to the ASF repository on github, without the apache repository added. A separate directory should be set up with write access to the ASF repository as well as read access to your other repositories. Merging operations and pushes back to the ASF repo are done from this directory âso isolated from all local development. +Committers can avoid this by setting the directory in which they develop code to read only access to the ASF repository on github. A separate directory should also be set up with write access to the ASF repository as well as read access to your other repositories. Merging operations and push backs to the ASF repo are done from this directory âso it will be immune to all local changes. -If you accidentally commit a patch to an ASF branch, do not attempt to roll back the branch and force out a new update. Simply commit and push out a new patch revoking the change. +If you accidentally committed a patch to an ASF branch, do not attempt to roll back the branch and force out a new update. Simply commit and push out a new patch revoking the change. -If you do accidentally commit a branch to the ASF repo, the infrastructure team can delete it âbut they cannot stop it propagating to github and potentially being visible. Try not to do that. +If you do accidentally committed a branch to the ASF repo, the infrastructure team can delete it âbut they cannot stop it propagating to github and potentially being visible. Please avoid this. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/07-code-guidelines.md ---------------------------------------------------------------------- diff --git a/_docs/07-code-guidelines.md b/_docs/07-code-guidelines.md index 3326140..1901370 100644 --- a/_docs/07-code-guidelines.md +++ b/_docs/07-code-guidelines.md @@ -8,7 +8,7 @@ modified: 2016-12-29T15:01:43-04:00 {% include toc %} # Introduction -This document describes formatting rules and guidelines for software source code. Note that this document does not cover best programming practices or techniques. It is solely concentrating on source code formatting and conventions. +This page describes formatting rules and guidelines for software source code. Studies have shown that 80% of development time is spent on software maintenance which involves software source code understanding, refactoring and support. Established and enforced code formatting rules and guidelines improve source code readability, promote team code ownership, allow engineers understand new code more quickly and thorough as well as simplify maintenance. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/07-frequently-asked-questions.md ---------------------------------------------------------------------- diff --git a/_docs/07-frequently-asked-questions.md b/_docs/07-frequently-asked-questions.md index 68d45e1..24629cd 100644 --- a/_docs/07-frequently-asked-questions.md +++ b/_docs/07-frequently-asked-questions.md @@ -16,80 +16,80 @@ No. RocketMQ can run independently. ### 1. Where does the newly created Consumer ID start consuming messages? 1. If the topic sends a message within three days, then the consumer start consuming messages from the first message saved in the server. -2. If the topic sends a message three days ago, the consumer start consuming messages from the latest message in the server, in other words, starting from the tail of message queue. -3. If such consumer is the second reboot, then start to consumer message from the last consumption location. +2. If the topic sends a message three days ago, the consumer starts to consume messages from the latest message in the server, in other words, starting from the tail of message queue. +3. If such consumer is rebooted, then it starts to consume messages from the last consumption location. ### 2. How to reconsume message when consumption fails? - 1.Cluster consumption pattern - The consumer business logic code return Action.ReconsumerLater, or NULL, or throws an exception, the message will go up to 16 times retry procedure, if still fail to retry 16 times, then such message descarded. - 2.Broadcast consumption pattern - The broadcaset consumption still ensures that a message is consumered at least once, but it is consumed fail without retry. +1. Cluster consumption pattern +The consumer business logic code returns Action.ReconsumerLater, NULL, or throws an exception, if a message failed to be consumed, it will retry for up to 16 times, after that, the message would be descarded. + +2. Broadcast consumption pattern +The broadcaset consumption still ensures that a message is consumered at least once, but no resend option is provided. -### 3. How to deal with consume message failed? +### 3. How to query the failed message if there is a consumption failure? -1. Use topic query by the time range, you can query to a period of time Topic received all the messages. +1. Using topic query by time, you can query messages within a period of time. 2. Using Topic and Message Id to accurately query the message. 3. Using Topic and Message Key accurately query a class of messages with the same Message Key. -### 4. Delivery exactly once? +### 4. Are messages delivered exactly once? -In most cases, the message is not repeated. As a distributed message middleware, in the network jitter, application processing timeout and other abnormal circumstances, can not guarantee that the message is not repeated, but can ensure that the message is not lost. +RocketMQ ensures that all messages are delivered at least once. In most cases, the messages are not repeated. ### 5. How to add a new broker? -1. Start up a new broker and make it register to the same list of name servers. -2. On default, only internally system topics and consumer groups are created automatically. If you would like to have your business topic and consumer groups on the new node, remember to replicate them from the existing broker. You may turn to admin tool command to achieve this. +1. Start up a new broker and register it to the same list of name servers. +2. By default, only internal system topics and consumer groups are created automatically. If you would like to have your business topic and consumer groups on the new node, please replicate them from the existing broker. Admin tool and command lines are provided to handle this. ## Configuration related -### 1. How long the message is saved on the server? +The following answers are all default values and can be modified by configuration. +### 1. How long are the messages saved on the server? -Stored messages are saved for up to 3 days, and messages that are not consumed for more than 3 days will be deleted. +Stored messages are will be saved for up to 3 days, and messages that are not consumed for more than 3 days will be deleted. -### 2. What is the length limit for message Body? -Generally 256KB, but can be modified by configuration. +### 2. What is the size limit for message Body? +Generally 256KB. ### 3. How to set the number of consumer threads? -When you start Consumer, set a ConsumeThreadNums property, example as follow. +When you start Consumer, set a ConsumeThreadNums property, example is as follows: - properties.put(PropertyKeyConst.ConsumeThreadNums,20); + consumer.setConsumeThreadMin(20); + consumer.setConsumeThreadMax(20); ## Errors -### 1. Start producer or consumer failed and producer group or consumer repeat? -Reasonï¼In the same JVM inside using the same Producer ID/Consumer ID launched multiple instances of Producer/Consumer, it may cause the client to start failure. +### 1. If you start a producer or consumer failed and the error message is producer group or consumer repeat? +Reasonï¼Using the same Producer /Consumer Group to launch multiple instances of Producer/Consumer in the same JVM may cause the client fail to start. -Solution: Ensure that a JVM corresponds to a Producer ID/Consumer ID starts only with a Producer/Consumer instance. +Solution: Make sure that a JVM corresponding to one Producer /Consumer Group starts only with one Producer/Consumer instance. -### 2. In broadcast mode, consumer start loading json file failed? -Reason: Fastjson version is too low to cause the broadcast consumer to load a local offsets.json file failed, which causing the consumer boot failure. +### 2. If consumer failed to start loading json file in broadcast mode? +Reason: Fastjson version is too low to allow the broadcast consumer to load local offsets.json, causing the consumer boot failure. Damaged fastjson file can also cause the same problem. -Solution: Fastjson version will be upgraded to rocketmq client dependent version, to ensure that the local offsets.json can be normal loading. By default offsets.json file is in /home/{user}/.rocketmq_offsets. +Solution: Fastjson version has to be upgraded to rocketmq client dependent version to ensure that the local offsets.json can be loaded. By default offsets.json file is in /home/{user}/.rocketmq_offsets. Or check the integrity of fastjson. -### 3. What if a broker crashes? +### 3. What is the impact of a broker crash? - 1. Master crashes - Messages can no longer be sent to this broker set, but if you have another broker set available, messages can be still sent there given the topic is present.Messages can still be consumed from slaves. - 2. One slaves crashes - As long as there is another working slave, no impact on writing messages;No impact on consuming messages except when the consumer group is set to consume from this slave preferably. By default, it is from master. - 3. All slaves crash - No impact on writing messages on master, but if master is a SYNC_MASTER, the producer will get a result of SLAVE_NOT_AVAILABLE indicating that the message is not replicated to any slaves.No impact on consuming messages except that if the consumer group is set to consume from slave preferably. By default, it is from master. +1. Master crashes -### 4. Producer complains "No Topic Route Info", how to diagnose? -This happens when you are trying to send message to a topic whose route info is not available to the producer. - -1. Confirm the producer can connect to a name server and capable of fetching routing meta info from it. -2. Confirm that name servers do contain routing meta info of the topic. You may query the routing meta info from name server through topicRoute of admin tools or web console. -3. Confirm your brokers are sending heartbeats to the same list of name servers your producer is connecting to. -4. Confirm that the topic's perm is 6(rw-), or at least 2(-w-). + Messages can no longer be sent to this broker set, but if you have another broker set available, messages can still be sent given the topic is present. Messages can still be consumed from slaves. + +2. Some slave crash -If you can't find this topic, create it via admin tools command updateTopic or web console on a broker. + As long as there is another working slave, there will be no impact on sending messages. There will also be no impact on consuming messages except when the consumer group is set to consume from this slave preferably. By default, comsumer group consumes from master. +3. All slaves crash -## Features -### 1. What kind of consumption pattern does RocketMQ provide? -In RocketMQ, it providers two types of consumption patterns, such as Clustering consumption patterns and broadcasting consumption patterns. See the documentation on cluster patterns for details. + There will be no impact on sending messages to master, but, if the master is SYNC_MASTER, producer will get a SLAVE_NOT_AVAILABLE indicating that the message is not sent to any slaves. There will also be no impact on consuming messages except that if the consumer group is set to consume from slave preferably. By default, comsumer group consumes from master. + +### 4. Producer complains "No Topic Route Info", how to diagnose? +This happens when you are trying to send messages to a topic whose routing info is not available to the producer. + +1. Make sure that the producer can connect to a name server and is capable of fetching routing meta info from it. +2. Make sure that name servers do contain routing meta info of the topic. You may query the routing meta info from name server through topicRoute using admin tools or web console. +3. Make sure that your brokers are sending heartbeats to the same list of name servers your producer is connecting to. +4. Make sure that the topic's permssion is 6(rw-), or at least 2(-w-). -### 2. How many kinds of message type are supported? -There are several types of messages that are currently supported in rocketmqï¼such as common message, timed message, transaction message, sequential message and delay message. User can select the appropriate message type according to the needs of the business. +If you can't find this topic, create it on a broker via admin tools command updateTopic or web console. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/08-release-manual.md ---------------------------------------------------------------------- diff --git a/_docs/08-release-manual.md b/_docs/08-release-manual.md index fd0f05b..428ef80 100644 --- a/_docs/08-release-manual.md +++ b/_docs/08-release-manual.md @@ -7,11 +7,11 @@ modified: 2017-02-7T15:01:43-04:00 {% include toc %} -This is a guide to making a release of Apache RocketMQ (incubating). Please follow the steps below. +This is a guide to make a released version of Apache RocketMQ (incubating). Please follow the steps below: ## Preliminaries ### Apache Release Documentation -There are some release documentations provided by The ASF, including the incubator release documentation, can be found here: +The release documentations provided by The ASF can be found here: * [Apache Release Guide](http://www.apache.org/dev/release-publishing) * [Apache Release Policy](http://www.apache.org/dev/release.html) @@ -20,18 +20,18 @@ There are some release documentations provided by The ASF, including the incubat * [Maven Release Info](http://www.apache.org/dev/publishing-maven-artifacts.html) ### Code Signing Key -Create a code signing gpg key for release signing, use **\<your Apache ID\>@apache.org** as your primary ID for the code signing key. See the [Apache Release Signing documentation](https://www.apache.org/dev/release-signing) for more details. +Create a code signing gpg key for release signing, use **\<your Apache ID\>@apache.org** as your primary ID for the code signing key. See [Apache Release Signing documentation](https://www.apache.org/dev/release-signing) for more details. -* Create new pgp key. How to use pgp please refer to [here](http://www.apache.org/dev/openpgp.html). +* Create new pgp key. Please refer to [here](http://www.apache.org/dev/openpgp.html) on how to use gpg key. * Generate a new key via `gpg --gen-key`, and answer 4096 bits with no expiration time. -* Upload your key to a public key server, like `gpg --keyserver pgpkeys.mit.edu --send-key <your key id>`. +* Upload your key to a public key server by `gpg --keyserver pgpkeys.mit.edu --send-key <your key id>`. * Get the key signed by other committers(Optional). * Add the key to the RocketMQ [KEYS file](https://dist.apache.org/repos/dist/dev/incubator/rocketmq/KEYS). **Tips:** If you have more than one key in your gpg, set the code signing key to `~/.gnupg/gpg.conf` as default key is recommended. ### Prepare Your Maven Settings -Make sure that your Maven settings.xml file contains the following: +Make sure your Maven settings.xml file contains the following: ```xml <settings> @@ -81,29 +81,29 @@ Firstly, checkout a new branch from `master` with its name equal to the release ### Build the Candidate Release Artifacts Before building the release artifacts, do some verifications below: -* Ensure that now your are in the candidate release branch. -* Ensure that all the unit tests can pass via `mvn clean install`. -* Ensure that all the integration tests can pass via `mvn clean test -Pit-test`. +* Make sure that your are in the candidate release branch. +* Make sure that all the unit tests can pass via `mvn clean install`. +* Make sure that all the integration tests can pass via `mvn clean test -Pit-test`. Perform the following to generate and stage the artifacts: 1. `mvn clean release:clean` -2. `mvn release:prepare -Psigned_release -Darguments="-DskipTests"`, answer the right release version, SCM release tag, and the new development version. +2. `mvn release:prepare -Psigned_release -Darguments="-DskipTests"`, answer the correct release version, SCM release tag, and the new development version. 3. `mvn -Psigned_release release:perform -Darguments="-DskipTests"`, generate the artifacts and push them to the [Nexus repo](https://repository.apache.org/#stagingRepositories). If you would like to perform a dry run first (without pushing the artifacts to the repo), add the arg -DdryRun=true Now, the candidate release artifacts can be found in the [Nexus staging repo](https://repository.apache.org/#stagingRepositories) and in the `target` folder of your local branch. -**Tips:** If you are performing a source-only release, please remove all artifacts from the staging repo except for the .zip file containing the source and the javadocs jar file. In the Nexus GUI, you can right click on each artifact to be deleted and then select `Delete`. +**Tips:** If you are performing a source-only release, please remove all artifacts from the staging repo besides the .zip file containing the source and the javadocs jar file. In the Nexus GUI, you can right click on each artifact to be deleted and then select `Delete`. ### Validate the Release Candidate -Now the release candidate is ready, before calling a vote, the artifacts must satisfy the following checklist: +Now the release candidate is ready, before calling a vote, the artifacts must satisfy the following requirements: * Checksums and PGP signatures are valid. * Build is successful including unit and integration tests. -* DISCLAIMER is correct, filenames include âincubatingâ. +* DISCLAIMER is correct and filenames must include âincubatingâ. * LICENSE and NOTICE files are correct and dependency licenses are acceptable. -* All source files have license headers where appropriate, RAT checks pass -* Javadocs have been generated correctly and are accurate. +* All source files have license headers and pass RAT checks. +* Javadocs have been generated correctly. * The provenance of all source files is clear (ASF or software grants). Please follow the steps below to verify the checksums and PGP signatures: @@ -123,26 +123,26 @@ Please follow the steps below to verify the checksums and PGP signatures: ```shell gpg --verify rocketmq-all-%version-number%-incubating-source-release.zip.asc rocketmq-all-%version-number%-incubating-source-release.zip ``` - Check the output to ensure it contains only good signatures: + Check the output to ensure it only contains good signatures: ```text gpg: Good signature from ... gpg: Signature made ... ``` -3. Compare MD5, SHA hash generated from the below command with the downloaded hash files. +3. Compare MD5, SHA hash generated by the below command with the downloaded hash files. ```shell gpg --print-mds rocketmq-all-%version-number%-incubating-source-release.zip ``` ### Release Artifacts to Dev-Repository -If the release candidate appears to pass the validation checklist, close the staging repository in Nexus by selecting the staging repository `orgapacherocketmq-XXX` and clicking on the `Close` icon. +If the release candidate passes the validation checklist, close the staging repository in Nexus by selecting the staging repository `orgapacherocketmq-XXX` and clicking on the `Close` icon. Nexus will now run through a series of checksum and signature validations. -If the checks pass, Nexus will close the repository and give a URL to the closed staging repo (which contains the candidate artifacts). Include this URL in the voting email so that folks can find the staged candidate release artifacts. +If the checks are passed, Nexus will close the repository and produce a URL to the closed staging repo (which contains the candidate artifacts). Include this URL in the voting email so that folks can find the staged candidate release artifacts. -If the checks do not pass, fix the issues, roll back and restart the release process. +If the checks aren't passed, fix the issues then go back and restart the release process. If everything is ok, use svn to copy the candidate release artifacts to RocketMQ repo: https://dist.apache.org/repos/dist/dev/incubator/rocketmq/${release version}. @@ -153,7 +153,7 @@ As per the Apache Incubator [release guidelines](http://incubator.apache.org/inc General information regarding the Apache voting process can be found [here](http://www.apache.org/foundation/voting.html). ### Apache RocketMQ Community Vote -To vote on a candidate release, send an email to the [dev list](mailto:[email protected]) with subject **[VOTE]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** and a body along the lines of: +To vote on a candidate release, send an email to the [dev list](mailto:[email protected]) with subject **[VOTE]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** and body: > Hello RocketMQ Community, > @@ -188,7 +188,7 @@ To vote on a candidate release, send an email to the [dev list](mailto:dev@rocke > Thanks, > The Apache RocketMQ Team -Once 72 hours has passed (which is generally preferred) and/or at least three +1 (binding) votes have been cast with no -1 (binding) votes, send an email closing the vote and pronouncing the release candidate a success. Please use the subject: **[RESULT][VOTE]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** : +Once 72 hours has passed (which is generally preferred) and/or at least three +1 (binding) votes have been cast with no -1 (binding) votes, send an email closing the vote and congratulate the release candidate. Please use the subject: **[RESULT][VOTE]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** : > Hello RocketMQ Community, > @@ -209,7 +209,7 @@ Once 72 hours has passed (which is generally preferred) and/or at least three +1 > Thanks, > The Apache RocketMQ Team -If we do not pass the VOTE, fix the related issues, roll back, restart the release process and increase RC number. When we call a new vote, we must use the updated mail subject: **[RESTART][VOTE][#\<Attempt Number\>]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** +If we do not pass the VOTE, fix the related issues, go back, restart the release process and increase RC number. When we call a new vote, we must use the updated mail subject: **[RESTART][VOTE][#\<Attempt Number\>]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** ### Incubator PMC Vote Once the candidate release vote passes on dev@rocketmq, send an email to [IMPC](mailto:[email protected]) with subject **[VOTE]: Release Apache RocketMQ \<release version\>(incubating) RC\<RC Number\>** and a body along the lines of: @@ -253,7 +253,7 @@ Once the candidate release vote passes on dev@rocketmq, send an email to [IMPC]( > Thanks, > The Apache RocketMQ Team -Also don't forget announce the vote result: +Also don't forget to announce the vote result: > Hello Incubator PMC, > http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/11-rocketmq-road-map.md ---------------------------------------------------------------------- diff --git a/_docs/11-rocketmq-road-map.md b/_docs/11-rocketmq-road-map.md index abf9d7b..76a2581 100644 --- a/_docs/11-rocketmq-road-map.md +++ b/_docs/11-rocketmq-road-map.md @@ -8,14 +8,14 @@ modified: 2017-3-7T15:01:43-04:00 ### OpenMessaging -OpenMessaging, which includes the establishment of industry guidelines and messaging, streaming specifications to provide a common framework for finance, e-commerce, IoT and big-data area. The design principles are the cloud-oriented, simplicity, flexibility, and language independent in distributed heterogeneous environments. Conformance to these specifications will make it possible to develop a heterogeneous messaging applications across all major platforms and operating systems. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-17) +OpenMessaging, which includes the establishment of industry guidelines and messaging, streaming specifications to provide a common framework for finance, e-commerce, IoT and big-data area. The design principles are the cloud-orientedness, simplicity, flexibility, and language independency in distributed heterogeneous environments. Conformance to these specifications allows the development of a heterogeneous messaging applications across all major platforms and operating systems. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-17) {% include toc %} ### Message Filtering -So far, RocketMQ only support message filtering feature by `TAG`, but one message only can own one tag, this is too limited to meet complex business requirements. +So far, RocketMQ only supports message filtering feature by `TAG`, but one message can only own one tag, which is too limited to meet complex business requirements. So, we want to define and implement a reasonable filter language based on a subset of the SQL 92 expression syntax to support customized message filtering. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-121) @@ -23,38 +23,38 @@ So, we want to define and implement a reasonable filter language based on a subs ### Batch Messaging -In order to use RocketMQ in big data related scenarios, batch messaging is necessary, which will bring million-level TPS for RocketMQ. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-80), [PR](https://github.com/apache/incubator-rocketmq/pull/53) +In order to use RocketMQ in big data related scenarios, batch messaging is necessary and will bring million-level TPS for RocketMQ. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-80), [PR](https://github.com/apache/incubator-rocketmq/pull/53) ### Consistent Hash Allocate Strategy(CHAS) -Consumer clients use the average allocate strategy by far, which is very sensitive when clients register or unregister continually. +Consumer clients use the average allocate strategy by far, which is very sensitive when clients register or unregister continuously. -A Consistent Hash allocate strategy is valuable for the developer who cares more about stabilization than averaging. +A Consistent Hash allocate strategy is valuable for developers who care more about stabilization than averaging. -So it's better for us to support CHAS as a extra choice in consumer load balancing. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-67), [PR](https://github.com/apache/incubator-rocketmq/pull/67) +So we decided to support CHAS as an extra choice in consumer load balancing. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-67), [PR](https://github.com/apache/incubator-rocketmq/pull/67) ### Global Order Messaging As we know, messages in the same queue can be consumed sequentially. So we always send the congeneric messages to the same queue to guarantee ordering, which will cause hot-point issue. -So It's cool if we support a new global order messaging mechanism, without hot-points problem. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-122) +So it'd be cool if we can support a new global order messaging mechanism without the hot-point problem. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-122) ### Distributed Transaction Messaging -Undoubtedly, transaction messaging is very frequently-used in most business. +Undoubtedly, transaction messaging is frequently used in most business. -But it is unfortunate that users must implement transaction mechanism by themselves until now, may be they need DataBase to implement it. +But users have to implement transaction mechanism by themselves for now, so there is a potential need of a database implementation to solve the problem. -It's time to support distributed transaction messaging to make it convenient for the user, help them handle complex business with skill and ease. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-123) +Now we can support distributed transaction messaging to make it convenient for the users and help them handle complex business. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-123) ### Non-Redundant Message Delivery Mechanism -The duplicated messages are worrisome. It will cost much if user need non-repeating messages. +The duplicated messages will impose extra cost if user needs non-repeating messages. -In most cases, user need store the consume records to judge a message is replicated or not, and the store stage should guarantee strong consistency. As you see, it's very complicated, so support a strict and non-redundant message delivery mechanism is impending. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-124) +In most cases, user needs to store the consume records to determine if a message is duplicated, and the store stage should guarantee consistency. So we need to support a strict and non-redundant message delivery mechanism. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-124) ### Intellective HA Architecture -RocketMQ uses master-slave as HA architecture, which has low latency and high throughput features, but this program need human intervention to recover from abnormal situations. +RocketMQ uses master-slave as HA architecture, which has low latency and high throughput, but this program needs human intervention to recover from abnormal situations. So, we want to support a multi-replication high availabilityï¼reliability mechanism, without human intervention. [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ-125) @@ -67,7 +67,7 @@ MQTT is a machine-to-machine (M2M)/"Internet of Things" connectivity protocol, w ## 4.4.0-incubating+ RoadMap: 1. Support more application layer protocol: WebSocket, HTTP2, etc. -2. Support more native language SDK: PHP, Python, .Net, Node, Go, etc. The chosen programming languages are the result of surveying many cloud platforms. +2. Support more native language SDK: PHP, Python, .Net, Node, Go, etc. The chosen programming languages are based on the investigation of many cloud platforms. 3. Support advanced message queuing protocol(AMQP). ## RocketMQ Externals http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/12-rmq-batch-example.md ---------------------------------------------------------------------- diff --git a/_docs/12-rmq-batch-example.md b/_docs/12-rmq-batch-example.md index a94c27c..67a436c 100644 --- a/_docs/12-rmq-batch-example.md +++ b/_docs/12-rmq-batch-example.md @@ -7,15 +7,15 @@ modified: 2017-04-24T15:01:43-04:00 {% include toc %} -### Why batch? -Sending messages in batch improves performance of delivering small messages. +#### Why batch? +Sending messages in batch improves performance of delivering small messages. -### Usage constraints +#### Usage constraints Messages of the same batch should have: same topic, same waitStoreMsgOK and no schedule support. Besides, the total size of the messages in one batch should be no more than 1MiB. -### How to use batch +#### How to use batch If you just send messages of no more than 1MiB at a time, it is easy to use batch: ```java @@ -32,7 +32,7 @@ try { } ``` -### Split into lists +#### Split into lists The complexity only grow when you send large batch and you may not sure if it exceeds the size limit (1MiB). At this time, you'd better split the lists: @@ -91,4 +91,4 @@ while (splitter.hasNext()) { //handle the error } } -``` +``` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/13-rmq-broadcasting-example.md ---------------------------------------------------------------------- diff --git a/_docs/13-rmq-broadcasting-example.md b/_docs/13-rmq-broadcasting-example.md index ea2b30d..f236abf 100644 --- a/_docs/13-rmq-broadcasting-example.md +++ b/_docs/13-rmq-broadcasting-example.md @@ -7,10 +7,10 @@ modified: 2017-04-24T15:01:43-04:00 {% include toc %} -### What is broadcasting +#### What is broadcasting Broadcasting is sending a message to all subscribers of a topic. If you want all subscribers receive messages about a topic, broadcasting is a good choice. -### Producer example +#### Producer example ```java public class BroadcastProducer { @@ -31,7 +31,7 @@ public class BroadcastProducer { } ``` -### Consumer example +#### Consumer example ```java public class BroadcastConsumer { http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/14-rmq-deployment.md ---------------------------------------------------------------------- diff --git a/_docs/14-rmq-deployment.md b/_docs/14-rmq-deployment.md index 9e52422..497b0ac 100644 --- a/_docs/14-rmq-deployment.md +++ b/_docs/14-rmq-deployment.md @@ -7,28 +7,28 @@ modified: 2017-04-24T15:01:43-04:00 {% include toc %} -This section is to introduce deployment solution which is considered production-ready. Generally speaking, we are deploying a resilient RocketMQ cluster having no single point of failure. +This section introduces production-ready deployment solution. Generally speaking, we are deploying a resilient RocketMQ cluster having no single point of failure. ### Prerequisite -Before starting this section, make sure you have read Quick Start section, in which core concepts and components of RocketMQ are introduced. +Before starting this section, make sure you have read Quick Start section, and are farmiliar with the core concepts and components of RocketMQ. #### Production-ready Deployment ##### Name Server -To ensure the cluster can still operate normally when one instance crashes, two or more name server instances are recommended. As long as there is one name server instance alive, the whole cluster remains in service. +To ensure the cluster can still function when one instance crashes, two or more name server instances are recommended. As long as there is one name server instance alive, the whole cluster remains in service. -Name server follows the share-nothing design paradigm. Brokers send heartbeat data to all name servers. Producers and consumers may query meta data from any of name servers available while sending / consuming messages. +Name server follows the share-nothing design paradigm. Brokers send heartbeat data to all name servers. Producers and consumers can query meta data from any of name servers available while sending / consuming messages. #### Broker Brokers can be divided into two categories according to their roles: master and slave. Master brokers provide RW access while slave brokers only accept read access. -To deploy a high-availability RocketMQ cluster which has no single point of failure, a series of broker sets should be deployed. A broker set contains one master with brokerId set to 0 and several slaves with non-zero brokerIDs. All of the brokers in one set have the same brokerName. In serious scenarios, we should have at least two brokers in one broker set. Each topic resides in two or more brokers. +To deploy a high-availability RocketMQ cluster with no single point of failure, a series of broker sets should be deployed. A broker set contains one master with brokerId set to 0 and several slaves with non-zero brokerIDs. All of the brokers in one set have the same brokerName. In serious scenarios, we should have at least two brokers in one broker set. Each topic resides in two or more brokers. ### Configuration -When deploying a RocketMQ cluster, below configurations should be taken into consideration. +When deploying a RocketMQ cluster, recommended configuration is listed below: ##### Broker configuration -| Property Name | Default values | Details | +| Property Name | Default value | Details | | ----------------- |:------------------:| ---------------:| | listenPort | 10911 | listen port for client | | namesrvAddr | null | name server address | @@ -50,12 +50,12 @@ RocketMQ provides a CLI(command-line interface) admin tool belt to query, manage #### How To Get The admin tool is shipped along with RocketMQ. Either you download a pre-built binary version or build from source by yourself, you already have it. -In case you have source code, the rocketmq-tools module contains its source code. +In case you need the source code, the rocketmq-tools module contains its source code. #### How to use The Admin Tool is very easy to use. Here, for demonstration purpose, *nix environment is assumed. -Change directory to ${PACKAGE}/bin, command bash mqadmin, you should see the following help menu pops out: +Change directory to ${PACKAGE}/bin, command bash mqadmin, you should see the following help menu: ```java The most commonly used mqadmin commands are: @@ -75,13 +75,13 @@ The most commonly used mqadmin commands are: queryMsgByOffset Query Message by offset queryMsgByUniqueKey Query Message by Unique key printMsg Print Message Detail - sendMsgStatus send msg to broker + sendMsgStatus Send msg to broker brokerConsumeStats Fetch broker consume stats data producerConnection Query producer's socket connection and client version consumerConnection Query consumer's socket connection, client version and subscription consumerProgress Query consumers's progress, speed consumerStatus Query consumer's internal data structure - cloneGroupOffset clone offset from other group + cloneGroupOffset Clone offset from other group clusterList List all of clusters topicList Fetch all topic list from name server updateKvConfig Create or update KV config @@ -95,7 +95,7 @@ The most commonly used mqadmin commands are: statsAll Topic and Consumer tps stats syncDocs Synchronize wiki and issue to github.com allocateMQ Allocate MQ - checkMsgSendRT check message send response time + checkMsgSendRT Check message send response time clusterRT List All clusters Message Send RT ``` @@ -111,7 +111,7 @@ usage: mqadmin clusterList [-h] [-i <arg>] [-m] [-n <arg>] ``` ### Replication mode -To guarantee any successfully published message won't be lost, RocketMQ provides a Replication mode to gain stronger durability and higher availability with two replication way: Sync & Async. +To make sure that no successfully published message will be lost, RocketMQ provides a Replication mode to gain stronger durability and higher availability with two replication ways: Sync & Async. ##### Replication: Sync / Async Broker http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/16-rmq-architecture.md ---------------------------------------------------------------------- diff --git a/_docs/16-rmq-architecture.md b/_docs/16-rmq-architecture.md index 0cd352b..165e2c3 100644 --- a/_docs/16-rmq-architecture.md +++ b/_docs/16-rmq-architecture.md @@ -13,7 +13,7 @@ modified: 2017-04-24T15:01:43-04:00 # Overview -The greatest strengths of RocketMQ are high throughput, high reliability, and low latency when supporting massive messages through exquisite scale out and scale up. RocketMQ consists of four parts: name servers, brokers, producers and consumers. Each of them can be horizontally extended without a single Point of Failure. As shown in screenshot below. +Apache RocketMQ is a distributed messaging and streaming platform with low latency, high performance and reliability, trillion-level capacity and flexible scalability. It consists of four parts: name servers, brokers, producers and consumers. Each of them can be horizontally extended without a single Point of Failure. As shown in screenshot above. @@ -23,7 +23,7 @@ Name Servers provide lightweight service discovery and routing. Each Name Server **Broker Cluster** -Brokers take care of message storage by providing lightweight TOPIC and QUEUE mechanisms. It supports the Push and Pull model, contains fault tolerance mechanism (2 copies or 3 copies), and provides strong padding of peaks and capacity of accumulating hundreds of billion messages in their original time order. In addition, Brokers provide disaster recovery, rich metrics statistics, and alert mechanisms, all of which are lacking in traditional messaging systems. +Brokers take care of message storage by providing lightweight TOPIC and QUEUE mechanisms. They support the Push and Pull model, contains fault tolerance mechanism (2 copies or 3 copies), and provides strong padding of peaks and capacity of accumulating hundreds of billion messages in their original time order. In addition, Brokers provide disaster recovery, rich metrics statistics, and alert mechanisms, all of which are lacking in traditional messaging systems. **Producer Cluster** @@ -32,7 +32,7 @@ Producers support distributed deployment. Distributed Producers send messages to **Consumer Cluster** Consumers support distributed deployment in the Push and Pull model as well. It also supports cluster consumption and message broadcasting. It provides real-time message subscription mechanism and can meet most consumer requirements. -RocketMQâs website provides a simple quick-start guide[3] to interested users. +RocketMQâs website provides a simple quick-start guide to interested users. # NameServer @@ -58,11 +58,11 @@ Broker server is responsible for message store and delivery, message query, HA g As shown in image below, Broker server has searval important sub modules: -* Remoting Module, the entry of broker, handle the requests from clients. -* Client Manager, manage the clients (Producer/Consumer), maintain topic subscription of consumer. -* Store Service, provide simple APIs to store or query message in physical disk. -* HA Service, provide data sync feature between master broker and slave broker. -* Index Service, build index for messages by specified key and provide quick message query function. +* Remoting Module, the entry of broker, handles the requests from clients. +* Client Manager, manages the clients (Producer/Consumer) and maintains topic subscription of consumer. +* Store Service, provides simple APIs to store or query message in physical disk. +* HA Service, provides data sync feature between master broker and slave broker. +* Index Service, builds index for messages by specified key and provides quick message query.  http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/18-simple-example.md ---------------------------------------------------------------------- diff --git a/_docs/18-simple-example.md b/_docs/18-simple-example.md index f7436b9..c782117 100644 --- a/_docs/18-simple-example.md +++ b/_docs/18-simple-example.md @@ -10,13 +10,12 @@ modified: 2017-04-24T15:01:43-04:00 {% include toc %} Use RocketMQ to send messages in three ways: reliable synchronous, reliable -asynchronous, and one-way transmission. +asynchronous, and one-way transmission. -This page introduces: -the use cases, similarities and differences between the three implementations, -and a code example for reference. +This page exemplifies these three message-sending ways. Checkout the notes along with the example to figure out which +way to use for your specific use case. -### Reliable synchronous transmission +#### Reliable synchronous transmission Application: Reliable synchronous transmission is used in extensive scenes, such as important notification messages, SMS notification, SMS marketing system, etc.. @@ -46,16 +45,15 @@ public class SyncProducer { } ``` -### Reliable asynchronous transmission +#### Reliable asynchronous transmission -Application: asynchronous transmission is generally used to link time-consuming, -response time sensitive business scenarios. +Application: asynchronous transmission is generally used in response time sensitive business scenarios. ```java public class AsyncProducer { public static void main(String[] args) throws Exception { //Instantiate with a producer group name. - DefaultMQProducer producer = new DefaultMQProducer("Jodie_Daily_test"); + DefaultMQProducer producer = new DefaultMQProducer("ExampleProducerGroup"); //Launch the instance. producer.start(); producer.setRetryTimesWhenSendAsyncFailed(0); @@ -85,7 +83,7 @@ public class AsyncProducer { } ``` -### One-way transmission +#### One-way transmission Application: One-way transmission is used for cases requiring moderate reliability, such as log collection. @@ -94,7 +92,7 @@ such as log collection. public class OnewayProducer { public static void main(String[] args) throws Exception{ //Instantiate with a producer group name. - DefaultMQProducer producer = new DefaultMQProducer("example_group_name"); + DefaultMQProducer producer = new DefaultMQProducer("ExampleProducerGroup"); //Launch the instance. producer.start(); for (int i = 0; i < 100; i++) { @@ -106,11 +104,11 @@ public class OnewayProducer { ); //Call send message to deliver message to one of brokers. producer.sendOneway(msg); - + } //Shut down once the producer instance is not longer in use. producer.shutdown(); } } -``` +``` \ No newline at end of file http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/best-practice-consumer.md ---------------------------------------------------------------------- diff --git a/_docs/best-practice-consumer.md b/_docs/best-practice-consumer.md index a1d6c6b..c1bd2c5 100644 --- a/_docs/best-practice-consumer.md +++ b/_docs/best-practice-consumer.md @@ -8,25 +8,25 @@ Some useful tips for users. {% include toc %} ## Consumer Group and Subscriptions -The first thing you should be aware of is that different Consumer Group can consume the same topic independently, each of the group will have their own consuming offsets. -And make sure each Consumer within the same Group to subscribe the same topics. +The first thing you should be aware of is that different Consumer Group can consume the same topic independently, and each of them will have their own consuming offsets. +Please make sure each Consumer within the same Group to subscribe the same topics. ## MessageListener ### Orderly -The Consumer will lock each MessageQueue to make sure it is consumed one by one orderly. This will cause performance loss, but it is useful when you are care about the order of the messages. -It is not recommended to throw exception, you can return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT instead. +The Consumer will lock each MessageQueue to make sure it is consumed one by one in order. This will cause a performance loss, but it is useful when you care about the order of the messages. +It is not recommended to throw exceptions, you can return ConsumeOrderlyStatus.SUSPEND_CURRENT_QUEUE_A_MOMENT instead. ### Concurrently -As the name tells, the Consumer will consume the messages concurrently. It is recommended to use this for achieving good performance. -It is not recommended to throw exception, you can return ConsumeConcurrentlyStatus.RECONSUME_LATER instead. +As the name tells, the Consumer will consume the messages concurrently. It is recommended to use this for good performance. +It is not recommended to throw exceptions, you can return ConsumeConcurrentlyStatus.RECONSUME_LATER instead. ### Consume Status For MessageListenerConcurrently, you can return RECONSUME_LATER to tell the consumer that you can not consume it right now and want to reconsume it later. Then you can continue to consume other messages. -For MessageListenerOrderly, as that you care about the order, so you can not jump over the message, but you can return SUSPEND_CURRENT_QUEUE_A_MOMENT to tell the consumer to hold on for a moment. +For MessageListenerOrderly, because you care about the order, you can not jump over the message, but you can return SUSPEND_CURRENT_QUEUE_A_MOMENT to tell the consumer to wait for a moment. ### Blocking -It is not recommend to block the Listener, for in return it will block the thread pool, and finally the consuming process may get stuck. +It is not recommend to block the Listener, because it will block the thread pool, and eventually may stop the consuming process. ## Thread Number -The consumer use a ThreadPoolExecutor to process consuming internally. So you can tune it by using setConsumeThreadMin or setConsumeThreadMax. +The consumer use a ThreadPoolExecutor to process consuming internally, so you can change it by setting setConsumeThreadMin or setConsumeThreadMax. ## ConsumeFromWhere -When a new Consumer Group is established, it will need to decide whether it need to consume the historical messages which had already existed in the Broker. -CONSUME_FROM_LAST_OFFSET will ignore the historical messages, and consume any newly produced. +When a new Consumer Group is established, it will need to decide whether it needs to consume the historical messages which had already existed in the Broker. +CONSUME_FROM_LAST_OFFSET will ignore the historical messages, and consume anything produced after that. CONSUME_FROM_FIRST_OFFSET will consume every message existed in the Broker. You can also use CONSUME_FROM_TIMESTAMP to consume messages produced after the specified timestamp. ## Duplication @@ -35,5 +35,5 @@ Many circumstances could cause duplication, such as: * Consumer shutdown with some offsets not updated to the Broker in time. -So you may need to do some external work to handle this if your application cannot tolerate. For example, you may check the primary key of your DB. +So you may need to do some external work to handle this if your application cannot tolerate duplication. For example, you may check the primary key of your DB. http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/fbef4631/_docs/best-practice-create-pr.md ---------------------------------------------------------------------- diff --git a/_docs/best-practice-create-pr.md b/_docs/best-practice-create-pr.md new file mode 100644 index 0000000..aeced4f --- /dev/null +++ b/_docs/best-practice-create-pr.md @@ -0,0 +1,84 @@ +--- +title: "How to create Pull Request" +permalink: /docs/create-pull-request/ +modified: 2016-12-24T15:01:43-04:00 +--- + +This page guides you through the pull request creation process. + +{% include toc %} + +# Git setup for Contributors +First of all, fork githubâs `apache/incubator-rocketmq` to your own account on github and clone it as follows, + + git clone https://github.com/<your_github_name>/incubator-rocketmq.git + +Cloning this locally will set up `origin` to point to your remote fork on github as the default remote. +Now you can create your pull requests. + +You will need to update a local master sometimes (to merge to your development branches sometimes). +For this, you have to add remote for RocketMQ mirror as follows, + + git remote add upstream https://github.com/apache/incubator-rocketmq.git + +and update your local master via `git fetch` followed by `git rebase`, for instance: + git fetch upstream master + git rebase upstream/master + +# Git setup for Committers +In addition to contributors' configurations, committers will have to attach the apache git repo: + + git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git + +To check your remote setup, issue + + git remote -v + +You should see something like this: + + origin https://github.com/<your_github_name>/incubator-rocketmq.git (fetch) + origin https://github.com/<your_github_name>/incubator-rocketmq.git (push) + upstream https://github.com/apache/incubator-rocketmq.git (fetch) + upstream https://github.com/apache/incubator-rocketmq.git (push) + apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git (fetch) + apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git (push) + +Now if you want to experiment with a branch everything, by default, points to your github account because 'origin' is default. You can work as normal using only github until you are ready to merge with the apache remote. Some conventions will integrate with Apache JIRA ticket numbers. + + git checkout -b ROCKETMQ-xxxx #xxxx typically is a JIRA ticket number + +_To ensure the code quality of the master branch, all but minor changes should go through pull requests reviewed by peer committers._ + +# Do some work on the branch + + git commit -a -m "doing some work" + git push origin ROCKETMQ-xxxx # notice pushing to **origin** not **apache** + +Once you are ready to commit to the apache remote you can merge and push them directly, otherwise always create a PR. + +# How to create a PR (committers) + +Push your branch to Github: + + git checkout ROCKETMQ-xxxx + git push origin ROCKETMQ-xxxx + +1. Go to your ROCKETMQ-xxxx branch on Github. Since you forked it from Github's apache/incubator-rocketmq. By default all PR will go to apache/master. + +2. Click the green "Compare, review, and create pull request" button. You can edit the to and from for the PR if it isn't correct. The "base fork" should be apache/incubator-rocketmq unless you are collaborating with one of the committers on the list. The "base" will be master. Don't submit a PR to any other branches unless permitted by branch owner. The "head fork" will be your forked repo and the "compare" will be your ROCKETMQ-xxxx branch. +3. Click the "Create pull request" button and name the request "ROCKETMQ-xxxx" all caps. This will connect the comments of the PR to the mailing list and JIRA comments. +4. From now on the PR lives on github's apache/incubator-rocketmq. You can use the commenting UI there. +5. If you are looking for a review or wanting to share with someone else please write a note in the comments and don't worry about automated merging of your PR -- you will have to do that later. The PR is tied to your branch so you can respond to comments, make fixes, and commit them from your local repo. They will appear on the PR page and be mirrored to JIRA and the mailing list. +6. When you are satisfied and want to push it to Apache's remote repo, you can merge this PR. + +# How to create a PR (contributors) +Before you create a pull request, make sure +1. A corresponding [JIRA](https://issues.apache.org/jira/browse/ROCKETMQ/) issue is created and has a clear problem description. +2. Make sure you follow [Coding Guidelines](/docs/code-guidelines/). +3. You have unit tests for everything you are about to commit. + +For information about creating pull requests, please check [GitHub PR docs](https://help.github.com/articles/creating-a-pull-request/). + +Pull requests are made to `apache/incubator-rocketmq` repository on Github. +In the Github UI you should pick the master branch as target of the PR. <br /> +You pull request will be reviewed and commented by committers, and issues can be discussed. When all reviewers are positive on the pull request, it will be merged. \ No newline at end of file
