http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/2d7f6a51/content/docs/faq/index.html ---------------------------------------------------------------------- diff --git a/content/docs/faq/index.html b/content/docs/faq/index.html new file mode 100644 index 0000000..e091201 --- /dev/null +++ b/content/docs/faq/index.html @@ -0,0 +1,638 @@ +<!doctype html> +<html lang="en" class="no-js"> + <head> + <meta charset="utf-8"> + +<!-- begin SEO --> + + + + + + + + + +<title>Frequently Asked Questions - Apache RocketMQ</title> + + + + +<meta name="description" content="The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.General1. Why create rocketmq project instead of selecting other products?In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss."> + + + + +<meta property="og:locale" content="en"> +<meta property="og:site_name" content="Apache RocketMQ"> +<meta property="og:title" content="Frequently Asked Questions"> + + + <link rel="canonical" href="http://localhost:4000/docs/faq/";> + <meta property="og:url" content="http://localhost:4000/docs/faq/";> + + + + <meta property="og:description" content="The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.General1. Why create rocketmq project instead of selecting other products?In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss."> + + + + <meta name="twitter:site" content="@ApacheRocketMQ"> + <meta name="twitter:title" content="Frequently Asked Questions"> + <meta name="twitter:description" content="The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.General1. Why create rocketmq project instead of selecting other products?In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss."> + <meta name="twitter:url" content="http://localhost:4000/docs/faq/";> + + + <meta name="twitter:card" content="summary"> + + + + + + + + + + + + + + + + <meta property="og:type" content="article"> + <meta property="article:published_time" content="2017-03-16T11:42:05+08:00"> + + + + + + + + + <script type="application/ld+json"> + { + "@context" : "http://schema.org";, + "@type" : "Person", + "name" : "Apache RocketMQ", + "url" : "http://localhost:4000";, + "sameAs" : null + } + </script> + + + + <meta name="google-site-verification" content="aand0XZkSGsziuC-UPD4ZJniFD0m0JhGx6820y2mAQY" /> + + + <meta name="baidu-site-verification" content="wD06EbDRkQ" /> + + + + +<!-- end SEO --> + + +<link href="http://localhost:4000/feed.xml"; type="application/atom+xml" rel="alternate" title="Apache RocketMQ Feed"> + +<!-- http://t.co/dKP3o1e --> +<meta name="HandheldFriendly" content="True"> +<meta name="MobileOptimized" content="320"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> + +<script> + document.documentElement.className = document.documentElement.className.replace(/\bno-js\b/g, '') + ' js '; +</script> + +<!-- For all browsers --> +<link rel="stylesheet" href="http://localhost:4000/assets/css/main.css";> + +<meta http-equiv="cleartype" content="on"> + <!-- start custom head snippets --> + +<!-- insert favicons. use http://realfavicongenerator.net/ --> + +<!-- end custom head snippets --> + </head> + + <body class="layout--single"> + + <!--[if lt IE 9]> +<div class="notice--danger align-center" style="margin: 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/";>upgrade your browser</a> to improve your experience.</div> +<![endif]--> + <div class="masthead"> + <div class="masthead__inner-wrap"> + <div class="masthead__menu"> + <nav id="site-nav" class="greedy-nav"> + <button><div class="navicon"></div></button> + <ul class="visible-links"> + <li class="masthead__menu-item masthead__menu-item--lg"><a href="http://localhost:4000/";>Apache RocketMQ</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/docs/quick-start/";>Documentation</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/year-archive/";>Blog</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/community/";>Community</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/about/team/";>About</a></li> + + </ul> + <ul class="hidden-links hidden"></ul> + </nav> + </div> + </div> +</div> + + + + + +<div id="main" role="main"> + + <div class="sidebar sticky"> + + + + + + + + + + +<nav class="nav__list"> + + <input id="ac-toc" name="accordion-toc" type="checkbox" /> + <label for="ac-toc">Toggle Menu</label> + <ul class="nav__items"> + + <li> + + <span class="nav__sub-title">User Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/quick-start/"; class="">Quick Start</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/motivation/"; class="">Motivation</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/core-concept/"; class="">Core Concept</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cli-admin-tool/"; class="">CLI Admin Tool</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cluster-deployment/"; class="">Cluster Configuration & Deployment</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Developer Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/code-guidelines/"; class="">Code Guidelines</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/branching-model"; class="">Branching Model</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/pull-request/"; class="">Best Practice in PR</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/release-manual"; class="">Release Manual</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Best Practice</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-broker/"; class="">Broker</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-producer/"; class="">Producer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-consumer/"; class="">Consumer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-namesvr/"; class="">NameServer</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Release Notes</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/dowloading/releases/"; class="">Download</a></li> + + + + + + + + <li><a href="http://localhost:4000/release_notes/release-notes-4.0.0-incubating/"; class="">4.0.0-incubating</a></li> + + </ul> + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/roadmap/";><span class="nav__sub-title">RoadMap</span></a> + + + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/faq/";><span class="nav__sub-title">FAQ</span></a> + + + + </li> + + </ul> +</nav> + + + </div> + + + <article class="page" itemscope itemtype="http://schema.org/CreativeWork";> + <meta itemprop="headline" content="Frequently Asked Questions"> + <meta itemprop="description" content="The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.General1. Why create rocketmq project instead of selecting other products?In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss."> + <meta itemprop="datePublished" content="March 16, 2017"> + <meta itemprop="dateModified" content="December 28, 2016"> + + <div class="page__inner-wrap"> + + <header> + <h1 class="page__title" itemprop="headline">Frequently Asked Questions +</h1> + + </header> + + + <section class="page__content" itemprop="text"> + <p>The following questions are frequently asked with regard to the RocketMQ project in general. If you have further questions, make sure to consult the documentation or ask the community.</p> + +<h2 id="general">General</h2> +<h3 id="1-why-create-rocketmq-project-instead-of-selecting-other-products">1. Why create rocketmq project instead of selecting other products?</h3> +<p>In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability. So we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss.</p> + +<h3 id="2-do-i-have-to-install-other-softewares-such-as-zookeeper-to-use-rocketmq">2. Do I have to install other softewares, such as zookeeper, to use RocketMQ?</h3> +<p>No. RocketMQ can run without any other softeware, you can run broker server and name server indepentently. Aslo, the topic can be created by using command, such as sh mqadmin updatetopic etc. After creating successfully, you enjoy yourself with RocketMQ.</p> + +<h2 id="usage">Usage</h2> +<h3 id="1-where-does-the-newly-created-consumer-id-start-consuming-messages">1. Where does the newly created Consumer ID start consuming messages?</h3> + +<ol> + <li>If the topic sends a message within three days, then the consumer start consume message from the first message saved in the server.</li> + <li>If the topic sends a message in three days ago, the consumer start consume message from the latest message in the server, in other words, starting to consume the message queue tail.</li> + <li>If such consumer is the second reboot, then start to consumer message from the last consumption location.</li> +</ol> + +<h3 id="2-how-to-reconsume-message-when-consumption-fails">2. How to reconsume message when consumption fails?</h3> +<div class="highlighter-rouge"><pre class="highlight"><code>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. +</code></pre> +</div> + +<h3 id="3-how-to-deal-with-consume-message-failed">3. How to deal with consume message failed?</h3> + +<ol> + <li>Use topic query by the time range, you can query to a period of time Topic received all the messages.</li> + <li>Using Topic and Message Id to accurately query the message.</li> + <li>Using Topic and Message Key accurately query a class of messages with the same Message Key.</li> +</ol> + +<h3 id="4-delivery-exactly-once">4. Delivery exactly once?</h3> + +<p>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.</p> + +<h3 id="5-how-to-add-a-new-broker">5. How to add a new broker?</h3> + +<ol> + <li>Start up a new broker and make it register to the same list of name servers.</li> + <li>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.</li> +</ol> + +<h2 id="configuration-related">Configuration related</h2> +<h3 id="1-how-long-the-message-is-saved-on-the-server">1. How long the message is saved on the server?</h3> + +<p>Stored messages are saved for up to 3 days, and messages that are not consumed for more than 3 days will be deleted.</p> + +<h3 id="2-what-is-the-length-limit-for-message-body">2. What is the length limit for message Body?</h3> +<p>Generally 256KB, but can be modified by configuration.</p> + +<h3 id="3-how-to-set-the-number-of-consumer-threads">3. How to set the number of consumer threads?</h3> +<p>When you start Consumer, set a ConsumeThreadNums property, example as follow.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>properties.put(PropertyKeyConst.ConsumeThreadNums,20); +</code></pre> +</div> + +<h2 id="errors">Errors</h2> +<h3 id="1-start-producer-or-consumer-failed-and-producer-group-or-consumer-repeat">1. Start producer or consumer failed and producer group or consumer repeat?</h3> +<p>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.</p> + +<p>Solution: Ensure that a JVM corresponds to a Producer ID/Consumer ID starts only with a Producer/Consumer instance.</p> + +<h3 id="2-in-broadcast-mode-consumer-start-loading-json-file-failed">2. In broadcast mode, consumer start loading json file failed?</h3> +<p>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.</p> + +<p>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.</p> + +<h3 id="3-what-if-a-broker-crashes">3. What if a broker crashes?</h3> + +<div class="highlighter-rouge"><pre class="highlight"><code>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. +</code></pre> +</div> + +<h3 id="4-producer-complains-no-topic-route-info-how-to-diagnose">4. Producer complains âNo Topic Route Infoâ, how to diagnose?</h3> +<p>This happens when you are trying to send message to a topic whose route info is not available to the producer.</p> + +<ol> + <li>Confirm the producer can connect to a name server and capable of fetching routing meta info from it.</li> + <li>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.</li> + <li>Confirm your brokers are sending heartbeats to the same list of name servers your producer is connecting to.</li> + <li>Confirm that the topicâs perm is 6(rw-), or at least 2(-w-).</li> +</ol> + +<p>If you canât find this topic, create it via admin tools command updateTopic or web console on a broker.</p> + +<h2 id="features">Features</h2> +<h3 id="1-what-kind-of-consumption-pattern-does-rocketmq-provide">1. What kind of consumption pattern does RocketMQ provide?</h3> +<p>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.</p> + +<h3 id="2-how-many-kinds-of-message-type-are-supported">2. How many kinds of message type are supported?</h3> +<p>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.</p> + + + </section> + + <footer class="page__meta"> + + + + + + <p class="page__date"><strong><i class="fa fa-fw fa-calendar" aria-hidden="true"></i> Updated:</strong> <time datetime="2016-12-28">December 28, 2016</time></p> + + </footer> + + <section class="page__share"> + + <h4 class="page__share-title">Share on</h4> + + + <a href="https://twitter.com/intent/tweet?via=ApacheRocketMQ&text=Frequently Asked Questions http://localhost:4000/docs/faq/"; class="btn btn--twitter" title="Share on Twitter"><i class="fa fa-fw fa-twitter" aria-hidden="true"></i><span> Twitter</span></a> + + <a href="https://www.facebook.com/sharer/sharer.php?u=http://localhost:4000/docs/faq/"; class="btn btn--facebook" title="Share on Facebook"><i class="fa fa-fw fa-facebook" aria-hidden="true"></i><span> Facebook</span></a> + + <a href="https://plus.google.com/share?url=http://localhost:4000/docs/faq/"; class="btn btn--google-plus" title="Share on Google Plus"><i class="fa fa-fw fa-google-plus" aria-hidden="true"></i><span> Google+</span></a> + + <a href="https://www.linkedin.com/shareArticle?mini=true&url=http://localhost:4000/docs/faq/"; class="btn btn--linkedin" title="Share on LinkedIn"><i class="fa fa-fw fa-linkedin" aria-hidden="true"></i><span> LinkedIn</span></a> +</section> + + + + <nav class="pagination"> + + <a href="http://localhost:4000/docs/documentation/"; class="pagination--pager" title="Documentation +">Previous</a> + + + <a href="http://localhost:4000/docs/release-manual"; class="pagination--pager" title="Release Manual +">Next</a> + + </nav> + + </div> + + + <div class="page__comments"> + + + <h4 class="page__comments-title">Leave a Comment</h4> + <section id="disqus_thread"></section> + +</div> + + </article> + + + +</div> + + <div class="page__footer"> + <footer> + <!-- start custom footer snippets --> + +<!-- end custom footer snippets --> + <style type="text/css"> + div.columns { float: left; margin-left: 10px;} + div.clear { clear: both; } +</style> +<div> + <div class="columns"> + <a href="https://www.apache.org/";><img src="/assets/images/feather-small.gif" alt="Apache Software Foundation" style="height: 88px !important" /></a> + </div> + <div class="columns" style="width: 80%"> + <div class="page__footer-follow"> + <ul class="social-icons"> + + <li><strong>Follow:</strong></li> + + + <li><a href="https://twitter.com/ApacheRocketMQ";><i class="fa fa-fw fa-twitter-square" aria-hidden="true"></i> Twitter</a></li> + + + + <li><a href="http://github.com/apache/incubator-rocketmq";><i class="fa fa-fw fa-github" aria-hidden="true"></i> GitHub</a></li> + + + <li><a href="http://localhost:4000/feed.xml";><i class="fa fa-fw fa-rss-square" aria-hidden="true"></i> Feed</a></li> + </ul> + </div> + + <div class="page__footer-copyright">Copyright © 2017 <a href="http://www.apache.org/";>The Apache Software Foundation</a>. All Rights Reserved.</div> + </div> +</div> +<div class="clear"></div> + </footer> + </div> + + <script src="http://localhost:4000/assets/js/main.min.js";></script> + + + + + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-89603173-1', 'auto'); + ga('send', 'pageview'); +</script> + +<script> +var _hmt = _hmt || []; +(function() { + var hm = document.createElement("script"); + hm.src = "https://hm.baidu.com/hm.js?36428f2b841d08e7405724cbf7f860d2";; + var s = document.getElementsByTagName("script")[0]; + s.parentNode.insertBefore(hm, s); +})(); +</script> + + + + + + <script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'rocketmq'; + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function () { + var s = document.createElement('script'); s.async = true; + s.type = 'text/javascript'; + s.src = '//' + disqus_shortname + '.disqus.com/count.js'; + (document.getElementsByTagName('HEAD')[0] || document.getElementsByTagName('BODY')[0]).appendChild(s); + }()); + </script> + <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript";>comments powered by Disqus.</a></noscript> + + + + + + + </body> +</html>
http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/2d7f6a51/content/docs/motivation/index.html ---------------------------------------------------------------------- diff --git a/content/docs/motivation/index.html b/content/docs/motivation/index.html new file mode 100644 index 0000000..c0035dc --- /dev/null +++ b/content/docs/motivation/index.html @@ -0,0 +1,627 @@ +<!doctype html> +<html lang="en" class="no-js"> + <head> + <meta charset="utf-8"> + +<!-- begin SEO --> + + + + + + + + + +<title>Motivation - Apache RocketMQ</title> + + + + +<meta name="description" content="In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious."> + + + + +<meta property="og:locale" content="en"> +<meta property="og:site_name" content="Apache RocketMQ"> +<meta property="og:title" content="Motivation"> + + + <link rel="canonical" href="http://localhost:4000/docs/motivation/";> + <meta property="og:url" content="http://localhost:4000/docs/motivation/";> + + + + <meta property="og:description" content="In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious."> + + + + <meta name="twitter:site" content="@ApacheRocketMQ"> + <meta name="twitter:title" content="Motivation"> + <meta name="twitter:description" content="In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious."> + <meta name="twitter:url" content="http://localhost:4000/docs/motivation/";> + + + <meta name="twitter:card" content="summary"> + + + + + + + + + + + + + + + + <meta property="og:type" content="article"> + <meta property="article:published_time" content="2017-03-16T11:42:05+08:00"> + + + + + + + + + <script type="application/ld+json"> + { + "@context" : "http://schema.org";, + "@type" : "Person", + "name" : "Apache RocketMQ", + "url" : "http://localhost:4000";, + "sameAs" : null + } + </script> + + + + <meta name="google-site-verification" content="aand0XZkSGsziuC-UPD4ZJniFD0m0JhGx6820y2mAQY" /> + + + <meta name="baidu-site-verification" content="wD06EbDRkQ" /> + + + + +<!-- end SEO --> + + +<link href="http://localhost:4000/feed.xml"; type="application/atom+xml" rel="alternate" title="Apache RocketMQ Feed"> + +<!-- http://t.co/dKP3o1e --> +<meta name="HandheldFriendly" content="True"> +<meta name="MobileOptimized" content="320"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> + +<script> + document.documentElement.className = document.documentElement.className.replace(/\bno-js\b/g, '') + ' js '; +</script> + +<!-- For all browsers --> +<link rel="stylesheet" href="http://localhost:4000/assets/css/main.css";> + +<meta http-equiv="cleartype" content="on"> + <!-- start custom head snippets --> + +<!-- insert favicons. use http://realfavicongenerator.net/ --> + +<!-- end custom head snippets --> + </head> + + <body class="layout--single"> + + <!--[if lt IE 9]> +<div class="notice--danger align-center" style="margin: 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/";>upgrade your browser</a> to improve your experience.</div> +<![endif]--> + <div class="masthead"> + <div class="masthead__inner-wrap"> + <div class="masthead__menu"> + <nav id="site-nav" class="greedy-nav"> + <button><div class="navicon"></div></button> + <ul class="visible-links"> + <li class="masthead__menu-item masthead__menu-item--lg"><a href="http://localhost:4000/";>Apache RocketMQ</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/docs/quick-start/";>Documentation</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/year-archive/";>Blog</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/community/";>Community</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/about/team/";>About</a></li> + + </ul> + <ul class="hidden-links hidden"></ul> + </nav> + </div> + </div> +</div> + + + + + +<div id="main" role="main"> + + <div class="sidebar sticky"> + + + + + + + + + + +<nav class="nav__list"> + + <input id="ac-toc" name="accordion-toc" type="checkbox" /> + <label for="ac-toc">Toggle Menu</label> + <ul class="nav__items"> + + <li> + + <span class="nav__sub-title">User Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/quick-start/"; class="">Quick Start</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/motivation/"; class="active">Motivation</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/core-concept/"; class="">Core Concept</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cli-admin-tool/"; class="">CLI Admin Tool</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cluster-deployment/"; class="">Cluster Configuration & Deployment</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Developer Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/code-guidelines/"; class="">Code Guidelines</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/branching-model"; class="">Branching Model</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/pull-request/"; class="">Best Practice in PR</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/release-manual"; class="">Release Manual</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Best Practice</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-broker/"; class="">Broker</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-producer/"; class="">Producer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-consumer/"; class="">Consumer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-namesvr/"; class="">NameServer</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Release Notes</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/dowloading/releases/"; class="">Download</a></li> + + + + + + + + <li><a href="http://localhost:4000/release_notes/release-notes-4.0.0-incubating/"; class="">4.0.0-incubating</a></li> + + </ul> + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/roadmap/";><span class="nav__sub-title">RoadMap</span></a> + + + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/faq/";><span class="nav__sub-title">FAQ</span></a> + + + + </li> + + </ul> +</nav> + + + </div> + + + <article class="page" itemscope itemtype="http://schema.org/CreativeWork";> + <meta itemprop="headline" content="Motivation"> + <meta itemprop="description" content="In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious."> + <meta itemprop="datePublished" content="March 16, 2017"> + <meta itemprop="dateModified" content="December 17, 2016"> + + <div class="page__inner-wrap"> + + <header> + <h1 class="page__title" itemprop="headline">Motivation +</h1> + + </header> + + + <section class="page__content" itemprop="text"> + <p>In the early stages, we constructed our distributed messaging middleware on the basis of ActiveMQ 5.x(less than 5.3). Our international business uses it for async communication, search, social network activity stream, data pipeline, even in our trade order process. As our trade business throughput rises more and more inconceivably, pressure originating from our messaging cluster also become more and more obvious.</p> + +<aside class="sidebar__right"> +<nav class="toc"> + <header><h4 class="nav__title"><i class="fa fa-file-text"></i> On This Page</h4></header> +<ul class="toc__menu" id="markdown-toc"> + <li><a href="#why-rocketmq-" id="markdown-toc-why-rocketmq-">Why RocketMQ ?</a></li> + <li><a href="#rocketmq-vs-activemq-vs-kafka" id="markdown-toc-rocketmq-vs-activemq-vs-kafka">RocketMQ vs. ActiveMQ vs. Kafka</a></li> +</ul> + + </nav> +</aside> + +<h1 id="why-rocketmq-">Why RocketMQ ?</h1> + +<p>Based on our observations and research, with more and more queues and virtual topics in use, ActiveMQ IO module becomes a bottleneck. In some cases, slower consumers can slow down the producers. We tried our best efforts to handle this problems through throttling, circuit breaker or degradation, but it cannot scale out gracefully. So we begin to focus on the popular messaging solution Kafka at that time. Unfortunately, Kafka can not meet our requirements such as low latency and high reliability, see <a href="https://github.com/alibaba/RocketMQ/wiki/how_to_support_more_queues";>here</a> for details.</p> + +<p>In this context, we decided to innovate a new messaging middleware to handle a broad set of use cases, ranging from traditional publish/subscribe scenario to demandingly high volume realtime transaction system that tolerates no message loss. We also created a cornerstone product based on RocketMQ, a Platform as a Service (PaaS) product named the +<a href="https://intl.aliyun.com/";>Alibaba Cloud Platform</a>. Today, more than 100 companies are using the RocketMQ open source version in their business solutions. We believe RocketMQ can benefit more people, so we would like to share it around the world.</p> + +<p>The following are some different design between RocketMQ, ActiveMQ and Kafkaï¼They are the apacheâs most popular messaging solutions according to <a href="https://github.com/akullpp/awesome-java";>awesome-java</a>):</p> + +<h1 id="rocketmq-vs-activemq-vs-kafka">RocketMQ vs. ActiveMQ vs. Kafka</h1> + +<table> + <thead> + <tr> + <th>Messaging Product</th> + <th>Client SDK</th> + <th>Protocol and Specification</th> + <th>Order Message</th> + <th>Message Filter</th> + <th>Server Triggered Redelivery</th> + <th>Persistent Message</th> + <th>Retroactive Consumers</th> + <th>Message Priority</th> + <th>High Availability and Failover</th> + <th>Message Track</th> + <th>Configuration</th> + <th>Management and Operation Tools</th> + </tr> + </thead> + <tbody> + <tr> + <td>ActiveMQ</td> + <td>Java, .NET, C++ etc.</td> + <td>Push model, support OpenWire, STOMP, AMQP, MQTT, JMS</td> + <td>Exclusive Consumer or Exclusive Queues can ensure ordering</td> + <td>Supported</td> + <td>Not Supported</td> + <td>Supports very fast persistence using JDBC along with a high performance journalï¼such as levelDB, kahaDB</td> + <td>Supported</td> + <td>Supported</td> + <td>Supported, depending on storage,if using kahadb it requires a ZooKeeper server</td> + <td>Not Supported</td> + <td>The default configuration is low level, user need to optimize the configuration parameters</td> + <td>Supported</td> + </tr> + <tr> + <td>Kafka</td> + <td>Java, Scala etc.</td> + <td>Pull model, support TCP</td> + <td>Ensure ordering of messages within a partition</td> + <td>Supported, you can use Kafka Streams to filter messages</td> + <td>Not Supported</td> + <td>High performance file storage</td> + <td>Supported offset indicate</td> + <td>Not Supported</td> + <td>Supported, requires a ZooKeeper server</td> + <td>Not Supported</td> + <td>Kafka uses key-value pairs format for configuration. These values can be supplied either from a file or programmatically.</td> + <td>Supported, use terminal command to expose core metrics</td> + </tr> + <tr> + <td>RocketMQ</td> + <td>Java, .NET, C++</td> + <td>Pull model, support TCP, JMS</td> + <td>Ensure strict ordering of messages, have no hot spot problem,and can scale out gracefully</td> + <td>Supported, you can even upload yourself custom-built filter code snippets</td> + <td>Supported</td> + <td>High performance and low latency file storage</td> + <td>Supported timestamp and offset 2 indicates</td> + <td>Not Supported</td> + <td>Supported, Master-Slave model, without another kit</td> + <td>Supported</td> + <td>Work out of box,user only need to pay attention to a few configurations</td> + <td>Supported, rich web and terminal command to expose core metrics</td> + </tr> + </tbody> +</table> + + + </section> + + <footer class="page__meta"> + + + + + + <p class="page__date"><strong><i class="fa fa-fw fa-calendar" aria-hidden="true"></i> Updated:</strong> <time datetime="2016-12-17">December 17, 2016</time></p> + + </footer> + + <section class="page__share"> + + <h4 class="page__share-title">Share on</h4> + + + <a href="https://twitter.com/intent/tweet?via=ApacheRocketMQ&text=Motivation http://localhost:4000/docs/motivation/"; class="btn btn--twitter" title="Share on Twitter"><i class="fa fa-fw fa-twitter" aria-hidden="true"></i><span> Twitter</span></a> + + <a href="https://www.facebook.com/sharer/sharer.php?u=http://localhost:4000/docs/motivation/"; class="btn btn--facebook" title="Share on Facebook"><i class="fa fa-fw fa-facebook" aria-hidden="true"></i><span> Facebook</span></a> + + <a href="https://plus.google.com/share?url=http://localhost:4000/docs/motivation/"; class="btn btn--google-plus" title="Share on Google Plus"><i class="fa fa-fw fa-google-plus" aria-hidden="true"></i><span> Google+</span></a> + + <a href="https://www.linkedin.com/shareArticle?mini=true&url=http://localhost:4000/docs/motivation/"; class="btn btn--linkedin" title="Share on LinkedIn"><i class="fa fa-fw fa-linkedin" aria-hidden="true"></i><span> LinkedIn</span></a> +</section> + + + + <nav class="pagination"> + + <a href="http://localhost:4000/docs/quick-start/"; class="pagination--pager" title="Quick Start +">Previous</a> + + + <a href="http://localhost:4000/docs/core-concept/"; class="pagination--pager" title="Core Concept +">Next</a> + + </nav> + + </div> + + + <div class="page__comments"> + + + <h4 class="page__comments-title">Leave a Comment</h4> + <section id="disqus_thread"></section> + +</div> + + </article> + + + +</div> + + <div class="page__footer"> + <footer> + <!-- start custom footer snippets --> + +<!-- end custom footer snippets --> + <style type="text/css"> + div.columns { float: left; margin-left: 10px;} + div.clear { clear: both; } +</style> +<div> + <div class="columns"> + <a href="https://www.apache.org/";><img src="/assets/images/feather-small.gif" alt="Apache Software Foundation" style="height: 88px !important" /></a> + </div> + <div class="columns" style="width: 80%"> + <div class="page__footer-follow"> + <ul class="social-icons"> + + <li><strong>Follow:</strong></li> + + + <li><a href="https://twitter.com/ApacheRocketMQ";><i class="fa fa-fw fa-twitter-square" aria-hidden="true"></i> Twitter</a></li> + + + + <li><a href="http://github.com/apache/incubator-rocketmq";><i class="fa fa-fw fa-github" aria-hidden="true"></i> GitHub</a></li> + + + <li><a href="http://localhost:4000/feed.xml";><i class="fa fa-fw fa-rss-square" aria-hidden="true"></i> Feed</a></li> + </ul> + </div> + + <div class="page__footer-copyright">Copyright © 2017 <a href="http://www.apache.org/";>The Apache Software Foundation</a>. All Rights Reserved.</div> + </div> +</div> +<div class="clear"></div> + </footer> + </div> + + <script src="http://localhost:4000/assets/js/main.min.js";></script> + + + + + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-89603173-1', 'auto'); + ga('send', 'pageview'); +</script> + +<script> +var _hmt = _hmt || []; +(function() { + var hm = document.createElement("script"); + hm.src = "https://hm.baidu.com/hm.js?36428f2b841d08e7405724cbf7f860d2";; + var s = document.getElementsByTagName("script")[0]; + s.parentNode.insertBefore(hm, s); +})(); +</script> + + + + + + <script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'rocketmq'; + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function () { + var s = document.createElement('script'); s.async = true; + s.type = 'text/javascript'; + s.src = '//' + disqus_shortname + '.disqus.com/count.js'; + (document.getElementsByTagName('HEAD')[0] || document.getElementsByTagName('BODY')[0]).appendChild(s); + }()); + </script> + <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript";>comments powered by Disqus.</a></noscript> + + + + + + + </body> +</html> http://git-wip-us.apache.org/repos/asf/incubator-rocketmq-site/blob/2d7f6a51/content/docs/pull-request/index.html ---------------------------------------------------------------------- diff --git a/content/docs/pull-request/index.html b/content/docs/pull-request/index.html new file mode 100644 index 0000000..0e29345 --- /dev/null +++ b/content/docs/pull-request/index.html @@ -0,0 +1,729 @@ +<!doctype html> +<html lang="en" class="no-js"> + <head> + <meta charset="utf-8"> + +<!-- begin SEO --> + + + + + + + + + +<title>Best Practice in Pull Request - Apache RocketMQ</title> + + + + +<meta name="description" content="This page guides you through Git setup and contribution process."> + + + + +<meta property="og:locale" content="en"> +<meta property="og:site_name" content="Apache RocketMQ"> +<meta property="og:title" content="Best Practice in Pull Request"> + + + <link rel="canonical" href="http://localhost:4000/docs/pull-request/";> + <meta property="og:url" content="http://localhost:4000/docs/pull-request/";> + + + + <meta property="og:description" content="This page guides you through Git setup and contribution process."> + + + + <meta name="twitter:site" content="@ApacheRocketMQ"> + <meta name="twitter:title" content="Best Practice in Pull Request"> + <meta name="twitter:description" content="This page guides you through Git setup and contribution process."> + <meta name="twitter:url" content="http://localhost:4000/docs/pull-request/";> + + + <meta name="twitter:card" content="summary"> + + + + + + + + + + + + + + + + <meta property="og:type" content="article"> + <meta property="article:published_time" content="2017-03-16T11:42:05+08:00"> + + + + + + + + + <script type="application/ld+json"> + { + "@context" : "http://schema.org";, + "@type" : "Person", + "name" : "Apache RocketMQ", + "url" : "http://localhost:4000";, + "sameAs" : null + } + </script> + + + + <meta name="google-site-verification" content="aand0XZkSGsziuC-UPD4ZJniFD0m0JhGx6820y2mAQY" /> + + + <meta name="baidu-site-verification" content="wD06EbDRkQ" /> + + + + +<!-- end SEO --> + + +<link href="http://localhost:4000/feed.xml"; type="application/atom+xml" rel="alternate" title="Apache RocketMQ Feed"> + +<!-- http://t.co/dKP3o1e --> +<meta name="HandheldFriendly" content="True"> +<meta name="MobileOptimized" content="320"> +<meta name="viewport" content="width=device-width, initial-scale=1.0"> + +<script> + document.documentElement.className = document.documentElement.className.replace(/\bno-js\b/g, '') + ' js '; +</script> + +<!-- For all browsers --> +<link rel="stylesheet" href="http://localhost:4000/assets/css/main.css";> + +<meta http-equiv="cleartype" content="on"> + <!-- start custom head snippets --> + +<!-- insert favicons. use http://realfavicongenerator.net/ --> + +<!-- end custom head snippets --> + </head> + + <body class="layout--single"> + + <!--[if lt IE 9]> +<div class="notice--danger align-center" style="margin: 0;">You are using an <strong>outdated</strong> browser. Please <a href="http://browsehappy.com/";>upgrade your browser</a> to improve your experience.</div> +<![endif]--> + <div class="masthead"> + <div class="masthead__inner-wrap"> + <div class="masthead__menu"> + <nav id="site-nav" class="greedy-nav"> + <button><div class="navicon"></div></button> + <ul class="visible-links"> + <li class="masthead__menu-item masthead__menu-item--lg"><a href="http://localhost:4000/";>Apache RocketMQ</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/docs/quick-start/";>Documentation</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/year-archive/";>Blog</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/community/";>Community</a></li> + + + <li class="masthead__menu-item"><a href="http://localhost:4000/about/team/";>About</a></li> + + </ul> + <ul class="hidden-links hidden"></ul> + </nav> + </div> + </div> +</div> + + + + + +<div id="main" role="main"> + + <div class="sidebar sticky"> + + + + + + + + + + +<nav class="nav__list"> + + <input id="ac-toc" name="accordion-toc" type="checkbox" /> + <label for="ac-toc">Toggle Menu</label> + <ul class="nav__items"> + + <li> + + <span class="nav__sub-title">User Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/quick-start/"; class="">Quick Start</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/motivation/"; class="">Motivation</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/core-concept/"; class="">Core Concept</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cli-admin-tool/"; class="">CLI Admin Tool</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/cluster-deployment/"; class="">Cluster Configuration & Deployment</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Developer Guide</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/code-guidelines/"; class="">Code Guidelines</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/branching-model"; class="">Branching Model</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/pull-request/"; class="active">Best Practice in PR</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/release-manual"; class="">Release Manual</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Best Practice</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-broker/"; class="">Broker</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-producer/"; class="">Producer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-consumer/"; class="">Consumer</a></li> + + + + + + + + <li><a href="http://localhost:4000/docs/best-practice-namesvr/"; class="">NameServer</a></li> + + </ul> + + </li> + + <li> + + <span class="nav__sub-title">Release Notes</span> + + + + <ul> + + + + + + + + <li><a href="http://localhost:4000/dowloading/releases/"; class="">Download</a></li> + + + + + + + + <li><a href="http://localhost:4000/release_notes/release-notes-4.0.0-incubating/"; class="">4.0.0-incubating</a></li> + + </ul> + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/roadmap/";><span class="nav__sub-title">RoadMap</span></a> + + + + </li> + + <li> + + + + + <a href="http://localhost:4000/docs/faq/";><span class="nav__sub-title">FAQ</span></a> + + + + </li> + + </ul> +</nav> + + + </div> + + + <article class="page" itemscope itemtype="http://schema.org/CreativeWork";> + <meta itemprop="headline" content="Best Practice in Pull Request"> + <meta itemprop="description" content="This page guides you through Git setup and contribution process."> + <meta itemprop="datePublished" content="March 16, 2017"> + <meta itemprop="dateModified" content="December 25, 2016"> + + <div class="page__inner-wrap"> + + <header> + <h1 class="page__title" itemprop="headline">Best Practice in Pull Request +</h1> + + </header> + + + <section class="page__content" itemprop="text"> + <p>This page guides you through Git setup and contribution process.</p> + +<aside class="sidebar__right"> +<nav class="toc"> + <header><h4 class="nav__title"><i class="fa fa-file-text"></i> On This Page</h4></header> +<ul class="toc__menu" id="markdown-toc"> + <li><a href="#git-setup-for-contributors" id="markdown-toc-git-setup-for-contributors">Git setup for Contributors</a></li> + <li><a href="#git-setup-for-committers" id="markdown-toc-git-setup-for-committers">Git setup for Committers</a></li> + <li><a href="#do-some-work-on-the-branch" id="markdown-toc-do-some-work-on-the-branch">Do some work on the branch</a></li> + <li><a href="#how-to-create-a-pr-committers" id="markdown-toc-how-to-create-a-pr-committers">How to create a PR (committers)</a></li> + <li><a href="#how-to-create-a-pr-contributors" id="markdown-toc-how-to-create-a-pr-contributors">How to create a PR (contributors)</a></li> + <li><a href="#merging-a-pr-yours-or-contributors" id="markdown-toc-merging-a-pr-yours-or-contributors">Merging a PR (yours or contributors)</a></li> + <li><a href="#closing-a-pr-without-committing-for-committers" id="markdown-toc-closing-a-pr-without-committing-for-committers">Closing a PR without committing (for committers)</a></li> + <li><a href="#apachegithub-integration-features" id="markdown-toc-apachegithub-integration-features">Apache/github integration features</a></li> + <li><a href="#best-practises" id="markdown-toc-best-practises">Best Practises</a> <ul> + <li><a href="#avoiding-accidentally-committing-private-branches-to-the-asf-repo" id="markdown-toc-avoiding-accidentally-committing-private-branches-to-the-asf-repo">Avoiding accidentally committing private branches to the ASF repo</a></li> + </ul> + </li> +</ul> + + </nav> +</aside> + +<h1 id="git-setup-for-contributors">Git setup for Contributors</h1> +<p>First of all, fork githubâs <code class="highlighter-rouge">apache/incubator-rocketmq</code> to your own account on github and clone it as follows,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git clone https://github.com/<your_github_name>/incubator-rocketmq.git +</code></pre> +</div> + +<p>Cloning this locally will set up <code class="highlighter-rouge">origin</code> to point to your remote fork on github as the default remote. +Now you can create your pull requests.</p> + +<p>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,</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git remote add upstream https://github.com/apache/incubator-rocketmq.git +</code></pre> +</div> + +<p>and update your local master via <code class="highlighter-rouge">git fetch</code> followed by <code class="highlighter-rouge">git rebase</code>, for instance, as follows</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git fetch upstream master +git rebase upstream/master +</code></pre> +</div> + +<h1 id="git-setup-for-committers">Git setup for Committers</h1> +<p>In addition to contributorsâ configurations, committers will have to attach the apache git repo:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git remote add apache https://git-wip-us.apache.org/repos/asf/incubator-rocketmq.git +</code></pre> +</div> + +<p>To check your remote setup, issue</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git remote -v +</code></pre> +</div> + +<p>You should see something like this:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>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) +</code></pre> +</div> + +<p>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.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git checkout -b ROCKETMQ-xxxx #xxxx typically is a JIRA ticket number +</code></pre> +</div> + +<p><em>To guarantee code quality of the master branch, all but minor changes should go through pull requests reviewed by peer committers.</em></p> + +<h1 id="do-some-work-on-the-branch">Do some work on the branch</h1> + +<div class="highlighter-rouge"><pre class="highlight"><code>git commit -a -m "doing some work" +git push origin ROCKETMQ-xxxx # notice pushing to **origin** not **apache** +</code></pre> +</div> + +<p>Once you are ready to commit to the apache remote you can merge and push them directly or better yet create a PR.</p> + +<h1 id="how-to-create-a-pr-committers">How to create a PR (committers)</h1> + +<p>Push your branch to Github:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git checkout ROCKETMQ-xxxx +git push origin ROCKETMQ-xxxx +</code></pre> +</div> + +<ol> + <li> + <p>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.</p> + </li> + <li>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.</li> + <li>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.</li> + <li>From now on the PR lives on githubâs apache/incubator-rocketmq. You use the commenting UI there.</li> + <li>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.</li> + <li>When you are satisfied and want to push it to Apacheâs remote repo proceed with Merging a PR</li> +</ol> + +<h1 id="how-to-create-a-pr-contributors">How to create a PR (contributors)</h1> +<p>Before you create a pull request, make sure</p> +<ol> + <li>A corresponding <a href="https://issues.apache.org/jira/browse/ROCKETMQ/";>JIRA</a> issue is created and has a clear problem description.</li> + <li>You follow <a href="/docs/code-guidelines/">Coding Guidelines</a>.</li> +</ol> + +<p>For information on creating pull requests, see <a href="https://help.github.com/articles/creating-a-pull-request/";>GitHub PR docs</a>.</p> + +<p>Pull requests are made to <code class="highlighter-rouge">apache/incubator-rocketmq</code> 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.</p> + +<h1 id="merging-a-pr-yours-or-contributors">Merging a PR (yours or contributors)</h1> +<p>Start with reading <a href="https://help.github.com/articles/checking-out-pull-requests-locally/";>GitHub PR merging locally</a>. 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. +Merging pull requests are equivalent to a âpullâ of a contributorâs branch:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>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 +</code></pre> +</div> + +<p><code class="highlighter-rouge">--squash</code> 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 <code class="highlighter-rouge">--squash</code> 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.</p> + +<p>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.</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git checkout master # switch to local master branch +git pull apache master # fast-forward to current remote HEAD +git merge --squash ROCKETMQ-xxxx +</code></pre> +</div> + +<p>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</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git commit --author="contributor_name <contributor_email>" -a -m "ROCKETMQ-XXXX description closes apache/incubator-rocketmq#ZZ" +</code></pre> +</div> + +<p>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 <a href="https://help.github.com/articles/closing-issues-via-commit-messages/";>GitHub PR closing docs.</a>. +Next, push to git-wip-us.apache.org:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git push apache master +</code></pre> +</div> + +<p>(this will require Apache handle credentials). +The PR, once pushed, will get mirrored to github. To update your github version push there too:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git push origin master +</code></pre> +</div> + +<p>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.</p> + +<h1 id="closing-a-pr-without-committing-for-committers">Closing a PR without committing (for committers)</h1> +<p>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:</p> + +<div class="highlighter-rouge"><pre class="highlight"><code>git commit --allow-empty -m "ROCKETMQ-XXXX closes apache/incubator-rocketmq#ZZ *Won't fix*" +git push apache master +</code></pre> +</div> + +<p>that should close PR ZZ on github mirror without merging and any code modifications in the master repository.more detail please refer to RocketMQ PR https://github.com/apache/incubator-rocketmq/pull/15</p> + +<h1 id="apachegithub-integration-features">Apache/github integration features</h1> + +<p>Read <a href="https://blogs.apache.org/infra/entry/improved_integration_between_apache_and";>infra blog</a>. 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.</jira-issue-description></p> + +<h1 id="best-practises">Best Practises</h1> + +<h2 id="avoiding-accidentally-committing-private-branches-to-the-asf-repo">Avoiding accidentally committing private branches to the ASF repo</h2> + +<p>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).</p> + +<p>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.</p> + +<p>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.</p> + +<p>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.</p> + + + + </section> + + <footer class="page__meta"> + + + + + + <p class="page__date"><strong><i class="fa fa-fw fa-calendar" aria-hidden="true"></i> Updated:</strong> <time datetime="2016-12-25">December 25, 2016</time></p> + + </footer> + + <section class="page__share"> + + <h4 class="page__share-title">Share on</h4> + + + <a href="https://twitter.com/intent/tweet?via=ApacheRocketMQ&text=Best Practice in Pull Request http://localhost:4000/docs/pull-request/"; class="btn btn--twitter" title="Share on Twitter"><i class="fa fa-fw fa-twitter" aria-hidden="true"></i><span> Twitter</span></a> + + <a href="https://www.facebook.com/sharer/sharer.php?u=http://localhost:4000/docs/pull-request/"; class="btn btn--facebook" title="Share on Facebook"><i class="fa fa-fw fa-facebook" aria-hidden="true"></i><span> Facebook</span></a> + + <a href="https://plus.google.com/share?url=http://localhost:4000/docs/pull-request/"; class="btn btn--google-plus" title="Share on Google Plus"><i class="fa fa-fw fa-google-plus" aria-hidden="true"></i><span> Google+</span></a> + + <a href="https://www.linkedin.com/shareArticle?mini=true&url=http://localhost:4000/docs/pull-request/"; class="btn btn--linkedin" title="Share on LinkedIn"><i class="fa fa-fw fa-linkedin" aria-hidden="true"></i><span> LinkedIn</span></a> +</section> + + + + <nav class="pagination"> + + <a href="http://localhost:4000/docs/cluster-deployment/"; class="pagination--pager" title="Cluster Configuration and Deployment +">Previous</a> + + + <a href="http://localhost:4000/docs/code-guidelines/"; class="pagination--pager" title="Coding Guidelines +">Next</a> + + </nav> + + </div> + + + <div class="page__comments"> + + + <h4 class="page__comments-title">Leave a Comment</h4> + <section id="disqus_thread"></section> + +</div> + + </article> + + + +</div> + + <div class="page__footer"> + <footer> + <!-- start custom footer snippets --> + +<!-- end custom footer snippets --> + <style type="text/css"> + div.columns { float: left; margin-left: 10px;} + div.clear { clear: both; } +</style> +<div> + <div class="columns"> + <a href="https://www.apache.org/";><img src="/assets/images/feather-small.gif" alt="Apache Software Foundation" style="height: 88px !important" /></a> + </div> + <div class="columns" style="width: 80%"> + <div class="page__footer-follow"> + <ul class="social-icons"> + + <li><strong>Follow:</strong></li> + + + <li><a href="https://twitter.com/ApacheRocketMQ";><i class="fa fa-fw fa-twitter-square" aria-hidden="true"></i> Twitter</a></li> + + + + <li><a href="http://github.com/apache/incubator-rocketmq";><i class="fa fa-fw fa-github" aria-hidden="true"></i> GitHub</a></li> + + + <li><a href="http://localhost:4000/feed.xml";><i class="fa fa-fw fa-rss-square" aria-hidden="true"></i> Feed</a></li> + </ul> + </div> + + <div class="page__footer-copyright">Copyright © 2017 <a href="http://www.apache.org/";>The Apache Software Foundation</a>. All Rights Reserved.</div> + </div> +</div> +<div class="clear"></div> + </footer> + </div> + + <script src="http://localhost:4000/assets/js/main.min.js";></script> + + + + + <script> + (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){ + (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o), + m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) + })(window,document,'script','//www.google-analytics.com/analytics.js','ga'); + + ga('create', 'UA-89603173-1', 'auto'); + ga('send', 'pageview'); +</script> + +<script> +var _hmt = _hmt || []; +(function() { + var hm = document.createElement("script"); + hm.src = "https://hm.baidu.com/hm.js?36428f2b841d08e7405724cbf7f860d2";; + var s = document.getElementsByTagName("script")[0]; + s.parentNode.insertBefore(hm, s); +})(); +</script> + + + + + + <script type="text/javascript"> + /* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */ + var disqus_shortname = 'rocketmq'; + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function() { + var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true; + dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js'; + (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq); + })(); + + /* * * DON'T EDIT BELOW THIS LINE * * */ + (function () { + var s = document.createElement('script'); s.async = true; + s.type = 'text/javascript'; + s.src = '//' + disqus_shortname + '.disqus.com/count.js'; + (document.getElementsByTagName('HEAD')[0] || document.getElementsByTagName('BODY')[0]).appendChild(s); + }()); + </script> + <noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript";>comments powered by Disqus.</a></noscript> + + + + + + + </body> +</html>
