Author: rhs
Date: Mon Feb 2 20:52:34 2015
New Revision: 1656568
URL: http://svn.apache.org/r1656568
Log:
added some content on contributing to proton
Added:
qpid/site/docs/proton/contributing.html
qpid/site/docs/proton/proton-j-proton-c.html
qpid/site/docs/proton/submitting-patches.html
qpid/site/input/proton/contributing.md
qpid/site/input/proton/proton-j-proton-c.md
qpid/site/input/proton/submitting-patches.md
Modified:
qpid/site/docs/proton/index.html
qpid/site/input/proton/index.md
Added: qpid/site/docs/proton/contributing.html
URL:
http://svn.apache.org/viewvc/qpid/site/docs/proton/contributing.html?rev=1656568&view=auto
==============================================================================
--- qpid/site/docs/proton/contributing.html (added)
+++ qpid/site/docs/proton/contributing.html Mon Feb 2 20:52:34 2015
@@ -0,0 +1,142 @@
+<!DOCTYPE html>
+<!--
+ -
+ - Licensed to the Apache Software Foundation (ASF) under one
+ - or more contributor license agreements. See the NOTICE file
+ - distributed with this work for additional information
+ - regarding copyright ownership. The ASF licenses this file
+ - to you under the Apache License, Version 2.0 (the
+ - "License"); you may not use this file except in compliance
+ - with the License. You may obtain a copy of the License at
+ -
+ - http://www.apache.org/licenses/LICENSE-2.0
+ -
+ - Unless required by applicable law or agreed to in writing,
+ - software distributed under the License is distributed on an
+ - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ - KIND, either express or implied. See the License for the
+ - specific language governing permissions and limitations
+ - under the License.
+ -
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
+ <head>
+ <title>Contributing to Proton - Apache Qpid™</title>
+ <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+ <link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
+ <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
+ <script type="text/javascript">var _deferredFunctions = [];</script>
+ <script type="text/javascript" src="/deferred.js" defer="defer"></script>
+ <!--[if lte IE 8]>
+ <link rel="stylesheet" href="/ie.css" type="text/css"/>
+ <script type="text/javascript" src="/html5shiv.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <div id="-content">
+ <div id="-top" class="panel">
+ <a id="-menu-link"><img width="16" height="16"
src="data:image/png;base64," alt="Menu"/></a>
+
+ <a id="-search-link"><img width="22" height="16"
src="data:image/png;base64," alt="Search"/></a>
+
+ <ul id="-global-navigation">
+ <li><a id="-logotype" href="/index.html">Apache
Qpid<sup>™</sup></a></li>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source Code</a></li>
+ <li><a href="/resources.html">More Resources</a></li>
+ </ul>
+ </div>
+
+ <div id="-menu" class="panel" style="display: none;">
+ <section>
+ <h3>Project</h3>
+
+ <ul>
+ <li><a href="/overview.html">Overview</a></li>
+ <li><a href="/proton/index.html">Qpid Proton</a></li>
+ <li><a href="/contributors.html">Contributors</a></li>
+ <li><a href="/get-involved.html">Get involved</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Software</h3>
+
+ <ul>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/components/index.html">Components</a></li>
+ <li><a href="/releases/index.html">Releases</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Resources</h3>
+
+ <ul>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source code</a></li>
+ <li><a href="/resources.html">More resources</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>More</h3>
+
+ <ul>
+ <li><a href="/amqp.html">AMQP</a></li>
+ <li><a href="/developer.html">Developer central</a></li>
+ <li><a
href="https://cwiki.apache.org/confluence/display/qpid/";>Wiki</a></li>
+ </ul>
+ </section>
+ </div>
+
+ <div id="-search" class="panel" style="display: none;">
+ <form action="http://www.google.com/search"; method="get">
+ <input type="hidden" name="sitesearch" value="qpid.apache.org"/>
+ <input type="text" name="q" maxlength="255" autofocus="autofocus"
tabindex="1"/>
+ <button type="submit">Search</button>
+ <p><a href="/search.html">More ways to search</a></p>
+ </form>
+ </div>
+
+ <div id="-middle" class="panel">
+ <ul id="-path-navigation"><li><a href="/proton/index.html">Qpid
Proton</a></li><li>Contributing to Proton</li></ul>
+ <h1 id="contributing-to-proton">Contributing to Proton</h1>
+
+<ul>
+<li><a href="submitting-patches.html">Submitting Patches</a></li>
+<li><a href="proton-j-proton-c.html">Proton-J/Proton-C</a></li>
+</ul>
+
+
+ <hr/>
+
+ <ul id="-apache-navigation">
+ <li><a href="http://www.apache.org/";>Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/";>License</a></li>
+ <li><a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li>
+ <li><a
href="http://www.apache.org/foundation/thanks.html";>Thanks!</a></li>
+ <li><a href="http://www.apache.org/security/";>Security</a></li>
+ <li><a href="http://www.apache.org/";><img id="-apache-feather"
width="48" height="14" src="data:image/png;base64," alt="Apache"/></a></li>
+ </ul>
+
+ <p id="-legal">
+ Apache Qpid, Messaging built on AMQP; Copyright © 2013
+ The Apache Software Foundation; Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
+ License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
+ Proton, Apache, the Apache feather logo, and the Apache Qpid
+ project logo are trademarks of The Apache Software
+ Foundation; All other marks mentioned may be trademarks or
+ registered trademarks of their respective owners
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Modified: qpid/site/docs/proton/index.html
URL:
http://svn.apache.org/viewvc/qpid/site/docs/proton/index.html?rev=1656568&r1=1656567&r2=1656568&view=diff
==============================================================================
--- qpid/site/docs/proton/index.html (original)
+++ qpid/site/docs/proton/index.html Mon Feb 2 20:52:34 2015
@@ -173,6 +173,7 @@ address.</p>
<ul>
<li><a href="development.html">Development plans</a></li>
+<li><a href="contributing.html">Contributing to Proton</a></li>
<li><a href="https://cwiki.apache.org/confluence/display/qpid/proton";>Proton
wiki pages</a></li>
</ul>
Added: qpid/site/docs/proton/proton-j-proton-c.html
URL:
http://svn.apache.org/viewvc/qpid/site/docs/proton/proton-j-proton-c.html?rev=1656568&view=auto
==============================================================================
--- qpid/site/docs/proton/proton-j-proton-c.html (added)
+++ qpid/site/docs/proton/proton-j-proton-c.html Mon Feb 2 20:52:34 2015
@@ -0,0 +1,185 @@
+<!DOCTYPE html>
+<!--
+ -
+ - Licensed to the Apache Software Foundation (ASF) under one
+ - or more contributor license agreements. See the NOTICE file
+ - distributed with this work for additional information
+ - regarding copyright ownership. The ASF licenses this file
+ - to you under the Apache License, Version 2.0 (the
+ - "License"); you may not use this file except in compliance
+ - with the License. You may obtain a copy of the License at
+ -
+ - http://www.apache.org/licenses/LICENSE-2.0
+ -
+ - Unless required by applicable law or agreed to in writing,
+ - software distributed under the License is distributed on an
+ - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ - KIND, either express or implied. See the License for the
+ - specific language governing permissions and limitations
+ - under the License.
+ -
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
+ <head>
+ <title>Proton-J/Proton-C - Apache Qpid™</title>
+ <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+ <link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
+ <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
+ <script type="text/javascript">var _deferredFunctions = [];</script>
+ <script type="text/javascript" src="/deferred.js" defer="defer"></script>
+ <!--[if lte IE 8]>
+ <link rel="stylesheet" href="/ie.css" type="text/css"/>
+ <script type="text/javascript" src="/html5shiv.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <div id="-content">
+ <div id="-top" class="panel">
+ <a id="-menu-link"><img width="16" height="16"
src="data:image/png;base64," alt="Menu"/></a>
+
+ <a id="-search-link"><img width="22" height="16"
src="data:image/png;base64," alt="Search"/></a>
+
+ <ul id="-global-navigation">
+ <li><a id="-logotype" href="/index.html">Apache
Qpid<sup>™</sup></a></li>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source Code</a></li>
+ <li><a href="/resources.html">More Resources</a></li>
+ </ul>
+ </div>
+
+ <div id="-menu" class="panel" style="display: none;">
+ <section>
+ <h3>Project</h3>
+
+ <ul>
+ <li><a href="/overview.html">Overview</a></li>
+ <li><a href="/proton/index.html">Qpid Proton</a></li>
+ <li><a href="/contributors.html">Contributors</a></li>
+ <li><a href="/get-involved.html">Get involved</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Software</h3>
+
+ <ul>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/components/index.html">Components</a></li>
+ <li><a href="/releases/index.html">Releases</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Resources</h3>
+
+ <ul>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source code</a></li>
+ <li><a href="/resources.html">More resources</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>More</h3>
+
+ <ul>
+ <li><a href="/amqp.html">AMQP</a></li>
+ <li><a href="/developer.html">Developer central</a></li>
+ <li><a
href="https://cwiki.apache.org/confluence/display/qpid/";>Wiki</a></li>
+ </ul>
+ </section>
+ </div>
+
+ <div id="-search" class="panel" style="display: none;">
+ <form action="http://www.google.com/search"; method="get">
+ <input type="hidden" name="sitesearch" value="qpid.apache.org"/>
+ <input type="text" name="q" maxlength="255" autofocus="autofocus"
tabindex="1"/>
+ <button type="submit">Search</button>
+ <p><a href="/search.html">More ways to search</a></p>
+ </form>
+ </div>
+
+ <div id="-middle" class="panel">
+ <ul id="-path-navigation"><li><a href="/proton/index.html">Qpid
Proton</a></li><li>Proton-J/Proton-C</li></ul>
+ <h1 id="proton-jproton-c">Proton-J/Proton-C</h1>
+
+<p>If you're new to proton development, you might be wondering why there
+are two apparently independent projects (proton-c and proton-j) that
+share the same git repo and release cycle.</p>
+
+<p>These projects aren't actually quite as independent as they look.
+There is a common test suite that runs against both implementations to
+help keep them in sync with each other. This is the python test suite
+that lives underneath the top level <a
href="https://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=tree;f=tests/python";>tests/python</a>
+directory. These tests have been integrated into the maven build via
+jython so that the whole java build looks like a normal maven build
+and java developers don't need to deal with cmake or getting jython
+themselves or anything that's outside of the normal java experience.</p>
+
+<p>Likewise, the cmake build will detect if java is unavailable and opt
+out of building the java code, so it's easy for C developers to
+pretend that Java doesn't exist. It also does this for all the
+different bindings, e.g. if perl or ruby isn't installed it will not
+attempt to build them.</p>
+
+<p>As a core proton developer, it's a good idea to make a point of having
+all the optional stuff enabled. This will ensure that you are testing
+any of your changes against the widest range of code possible.</p>
+
+<p>It's also good to be aware of exactly how the common test suite
+integrates with both proton-c and proton-j. The python binding
+actually consists of a hand written wrapper layer that encapsulates
+the raw swig generated API. The raw swig API is actually much lower
+level and is available in the 'cproton' module. When you run the
+python test suite in jython, the swig generated cproton doesn't
+actually exist since it is a C module. Instead, you get the cproton.py
+that resides in the java source tree underneath
+<a
href="https://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=tree;f=proton-j/src/main/resources";>proton-j/src/main/resources</a>.
+This cproton.py and its dependent files serve as a shim that adapts
+between the Java API and the C API. These files can actually be quite
+handy as a reference for how to translate a given idiom from proton-j
+into proton-c or vice versa.</p>
+
+<p>You might notice some parts of the shim are stubbed out, e.g. like
+this:</p>
+
+<pre><code>def pn_flowcontroller(window):
+ raise Skipped()
+</code></pre>
+
+<p>Throwing a Skipped exception will signal to the test runner that
+whatever code is being called is not available, and the test will be
+reported as "skipped" rather than flagged as an error.</p>
+
+
+ <hr/>
+
+ <ul id="-apache-navigation">
+ <li><a href="http://www.apache.org/";>Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/";>License</a></li>
+ <li><a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li>
+ <li><a
href="http://www.apache.org/foundation/thanks.html";>Thanks!</a></li>
+ <li><a href="http://www.apache.org/security/";>Security</a></li>
+ <li><a href="http://www.apache.org/";><img id="-apache-feather"
width="48" height="14" src="data:image/png;base64," alt="Apache"/></a></li>
+ </ul>
+
+ <p id="-legal">
+ Apache Qpid, Messaging built on AMQP; Copyright © 2013
+ The Apache Software Foundation; Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
+ License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
+ Proton, Apache, the Apache feather logo, and the Apache Qpid
+ project logo are trademarks of The Apache Software
+ Foundation; All other marks mentioned may be trademarks or
+ registered trademarks of their respective owners
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: qpid/site/docs/proton/submitting-patches.html
URL:
http://svn.apache.org/viewvc/qpid/site/docs/proton/submitting-patches.html?rev=1656568&view=auto
==============================================================================
--- qpid/site/docs/proton/submitting-patches.html (added)
+++ qpid/site/docs/proton/submitting-patches.html Mon Feb 2 20:52:34 2015
@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<!--
+ -
+ - Licensed to the Apache Software Foundation (ASF) under one
+ - or more contributor license agreements. See the NOTICE file
+ - distributed with this work for additional information
+ - regarding copyright ownership. The ASF licenses this file
+ - to you under the Apache License, Version 2.0 (the
+ - "License"); you may not use this file except in compliance
+ - with the License. You may obtain a copy of the License at
+ -
+ - http://www.apache.org/licenses/LICENSE-2.0
+ -
+ - Unless required by applicable law or agreed to in writing,
+ - software distributed under the License is distributed on an
+ - "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ - KIND, either express or implied. See the License for the
+ - specific language governing permissions and limitations
+ - under the License.
+ -
+-->
+<html xmlns="http://www.w3.org/1999/xhtml"; xml:lang="en">
+ <head>
+ <title>Submitting Patches - Apache Qpid™</title>
+ <meta http-equiv="X-UA-Compatible" content="IE=edge"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+ <link rel="stylesheet" href="/site.css" type="text/css" async="async"/>
+ <link rel="stylesheet" href="/deferred.css" type="text/css" defer="defer"/>
+ <script type="text/javascript">var _deferredFunctions = [];</script>
+ <script type="text/javascript" src="/deferred.js" defer="defer"></script>
+ <!--[if lte IE 8]>
+ <link rel="stylesheet" href="/ie.css" type="text/css"/>
+ <script type="text/javascript" src="/html5shiv.js"></script>
+ <![endif]-->
+ </head>
+ <body>
+ <div id="-content">
+ <div id="-top" class="panel">
+ <a id="-menu-link"><img width="16" height="16"
src="data:image/png;base64," alt="Menu"/></a>
+
+ <a id="-search-link"><img width="22" height="16"
src="data:image/png;base64," alt="Search"/></a>
+
+ <ul id="-global-navigation">
+ <li><a id="-logotype" href="/index.html">Apache
Qpid<sup>™</sup></a></li>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source Code</a></li>
+ <li><a href="/resources.html">More Resources</a></li>
+ </ul>
+ </div>
+
+ <div id="-menu" class="panel" style="display: none;">
+ <section>
+ <h3>Project</h3>
+
+ <ul>
+ <li><a href="/overview.html">Overview</a></li>
+ <li><a href="/proton/index.html">Qpid Proton</a></li>
+ <li><a href="/contributors.html">Contributors</a></li>
+ <li><a href="/get-involved.html">Get involved</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Software</h3>
+
+ <ul>
+ <li><a href="/download.html">Download</a></li>
+ <li><a href="/documentation.html">Documentation</a></li>
+ <li><a href="/components/index.html">Components</a></li>
+ <li><a href="/releases/index.html">Releases</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>Resources</h3>
+
+ <ul>
+ <li><a href="/discussion.html">Discussion</a></li>
+ <li><a href="/issues.html">Issues</a></li>
+ <li><a href="/source-code.html">Source code</a></li>
+ <li><a href="/resources.html">More resources</a></li>
+ </ul>
+ </section>
+
+ <section>
+ <h3>More</h3>
+
+ <ul>
+ <li><a href="/amqp.html">AMQP</a></li>
+ <li><a href="/developer.html">Developer central</a></li>
+ <li><a
href="https://cwiki.apache.org/confluence/display/qpid/";>Wiki</a></li>
+ </ul>
+ </section>
+ </div>
+
+ <div id="-search" class="panel" style="display: none;">
+ <form action="http://www.google.com/search"; method="get">
+ <input type="hidden" name="sitesearch" value="qpid.apache.org"/>
+ <input type="text" name="q" maxlength="255" autofocus="autofocus"
tabindex="1"/>
+ <button type="submit">Search</button>
+ <p><a href="/search.html">More ways to search</a></p>
+ </form>
+ </div>
+
+ <div id="-middle" class="panel">
+ <ul id="-path-navigation"><li><a href="/proton/index.html">Qpid
Proton</a></li><li>Submitting Patches</li></ul>
+ <h1 id="submitting-patches">Submitting Patches</h1>
+
+<p>All contributions are greatly appreciated, but the process can be
+significantly streamlined by taking note of the following guidelines.</p>
+
+<h2 id="run-the-full-test-suite">Run the full test suite</h2>
+
+<p>Make sure the full test suite runs with your change in place. Even if
+you think your change is very localized, there may be subtle
+repurcussions that impact other parts of the code. If your change
+causes the test suite to fail, then it can't be accepted until a more
+complete fix is prepared.</p>
+
+<h2 id="keep-it-small">Keep it small</h2>
+
+<p>Most of the people that work on proton have a day job of some kind. If
+reviewing a patch requires carving out multiple hours/days, then it is
+much less likely to happen. On the other hand if the patch is neat,
+self contained, and just works then it can be reviewed and applied
+quite quickly.</p>
+
+<p>If you happen to have a larger body of work you'd like to contribute
+and there is a good reason that it's difficult to break it down into
+small pieces, that's ok too, but expect the whole process to take a
+bit longer. In this situation you can help things along by providing
+an outline/overview in english to make the work easier to digest.</p>
+
+<h2 id="keep-it-clean">Keep it clean</h2>
+
+<p>Extraneous whitespace can clutter up diffs and make them more
+difficult to read than they need to be. It's generally good practice
+to avoid introducing extraneous whitespace into files under source
+control. Most editors can be configured to remove and/or display
+extraneous whitespace automatically.</p>
+
+
+ <hr/>
+
+ <ul id="-apache-navigation">
+ <li><a href="http://www.apache.org/";>Apache</a></li>
+ <li><a href="http://www.apache.org/licenses/";>License</a></li>
+ <li><a
href="http://www.apache.org/foundation/sponsorship.html";>Sponsorship</a></li>
+ <li><a
href="http://www.apache.org/foundation/thanks.html";>Thanks!</a></li>
+ <li><a href="http://www.apache.org/security/";>Security</a></li>
+ <li><a href="http://www.apache.org/";><img id="-apache-feather"
width="48" height="14" src="data:image/png;base64," alt="Apache"/></a></li>
+ </ul>
+
+ <p id="-legal">
+ Apache Qpid, Messaging built on AMQP; Copyright © 2013
+ The Apache Software Foundation; Licensed under
+ the <a href="http://www.apache.org/licenses/LICENSE-2.0";>Apache
+ License, Version 2.0</a>; Apache Qpid, Qpid, Qpid Proton,
+ Proton, Apache, the Apache feather logo, and the Apache Qpid
+ project logo are trademarks of The Apache Software
+ Foundation; All other marks mentioned may be trademarks or
+ registered trademarks of their respective owners
+ </p>
+ </div>
+ </div>
+ </body>
+</html>
Added: qpid/site/input/proton/contributing.md
URL:
http://svn.apache.org/viewvc/qpid/site/input/proton/contributing.md?rev=1656568&view=auto
==============================================================================
--- qpid/site/input/proton/contributing.md (added)
+++ qpid/site/input/proton/contributing.md Mon Feb 2 20:52:34 2015
@@ -0,0 +1,23 @@
+;;
+;; Licensed to the Apache Software Foundation (ASF) under one
+;; or more contributor license agreements. See the NOTICE file
+;; distributed with this work for additional information
+;; regarding copyright ownership. The ASF licenses this file
+;; to you under the Apache License, Version 2.0 (the
+;; "License"); you may not use this file except in compliance
+;; with the License. You may obtain a copy of the License at
+;;
+;; http://www.apache.org/licenses/LICENSE-2.0
+;;
+;; Unless required by applicable law or agreed to in writing,
+;; software distributed under the License is distributed on an
+;; "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+;; KIND, either express or implied. See the License for the
+;; specific language governing permissions and limitations
+;; under the License.
+;;
+
+# Contributing to Proton
+
+ - [Submitting Patches](submitting-patches.html)
+ - [Proton-J/Proton-C](proton-j-proton-c.html)
Modified: qpid/site/input/proton/index.md
URL:
http://svn.apache.org/viewvc/qpid/site/input/proton/index.md?rev=1656568&r1=1656567&r2=1656568&view=diff
==============================================================================
--- qpid/site/input/proton/index.md (original)
+++ qpid/site/input/proton/index.md Mon Feb 2 20:52:34 2015
@@ -71,6 +71,7 @@ address.
## Resources
- [Development plans](development.html)
+ - [Contributing to Proton](contributing.html)
- [Proton wiki pages](https://cwiki.apache.org/confluence/display/qpid/proton)
</div>
Added: qpid/site/input/proton/proton-j-proton-c.md
URL:
http://svn.apache.org/viewvc/qpid/site/input/proton/proton-j-proton-c.md?rev=1656568&view=auto
==============================================================================
--- qpid/site/input/proton/proton-j-proton-c.md (added)
+++ qpid/site/input/proton/proton-j-proton-c.md Mon Feb 2 20:52:34 2015
@@ -0,0 +1,68 @@
+;;
+;; Licensed to the Apache Software Foundation (ASF) under one
+;; or more contributor license agreements. See the NOTICE file
+;; distributed with this work for additional information
+;; regarding copyright ownership. The ASF licenses this file
+;; to you under the Apache License, Version 2.0 (the
+;; "License"); you may not use this file except in compliance
+;; with the License. You may obtain a copy of the License at
+;;
+;; http://www.apache.org/licenses/LICENSE-2.0
+;;
+;; Unless required by applicable law or agreed to in writing,
+;; software distributed under the License is distributed on an
+;; "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+;; KIND, either express or implied. See the License for the
+;; specific language governing permissions and limitations
+;; under the License.
+;;
+
+# Proton-J/Proton-C
+
+If you're new to proton development, you might be wondering why there
+are two apparently independent projects (proton-c and proton-j) that
+share the same git repo and release cycle.
+
+These projects aren't actually quite as independent as they look.
+There is a common test suite that runs against both implementations to
+help keep them in sync with each other. This is the python test suite
+that lives underneath the top level
[tests/python](https://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=tree;f=tests/python)
+directory. These tests have been integrated into the maven build via
+jython so that the whole java build looks like a normal maven build
+and java developers don't need to deal with cmake or getting jython
+themselves or anything that's outside of the normal java experience.
+
+Likewise, the cmake build will detect if java is unavailable and opt
+out of building the java code, so it's easy for C developers to
+pretend that Java doesn't exist. It also does this for all the
+different bindings, e.g. if perl or ruby isn't installed it will not
+attempt to build them.
+
+As a core proton developer, it's a good idea to make a point of having
+all the optional stuff enabled. This will ensure that you are testing
+any of your changes against the widest range of code possible.
+
+It's also good to be aware of exactly how the common test suite
+integrates with both proton-c and proton-j. The python binding
+actually consists of a hand written wrapper layer that encapsulates
+the raw swig generated API. The raw swig API is actually much lower
+level and is available in the 'cproton' module. When you run the
+python test suite in jython, the swig generated cproton doesn't
+actually exist since it is a C module. Instead, you get the cproton.py
+that resides in the java source tree underneath
+[proton-j/src/main/resources](https://git-wip-us.apache.org/repos/asf?p=qpid-proton.git;a=tree;f=proton-j/src/main/resources).
+This cproton.py and its dependent files serve as a shim that adapts
+between the Java API and the C API. These files can actually be quite
+handy as a reference for how to translate a given idiom from proton-j
+into proton-c or vice versa.
+
+You might notice some parts of the shim are stubbed out, e.g. like
+this:
+
+
+ def pn_flowcontroller(window):
+ raise Skipped()
+
+Throwing a Skipped exception will signal to the test runner that
+whatever code is being called is not available, and the test will be
+reported as "skipped" rather than flagged as an error.
Added: qpid/site/input/proton/submitting-patches.md
URL:
http://svn.apache.org/viewvc/qpid/site/input/proton/submitting-patches.md?rev=1656568&view=auto
==============================================================================
--- qpid/site/input/proton/submitting-patches.md (added)
+++ qpid/site/input/proton/submitting-patches.md Mon Feb 2 20:52:34 2015
@@ -0,0 +1,53 @@
+;;
+;; Licensed to the Apache Software Foundation (ASF) under one
+;; or more contributor license agreements. See the NOTICE file
+;; distributed with this work for additional information
+;; regarding copyright ownership. The ASF licenses this file
+;; to you under the Apache License, Version 2.0 (the
+;; "License"); you may not use this file except in compliance
+;; with the License. You may obtain a copy of the License at
+;;
+;; http://www.apache.org/licenses/LICENSE-2.0
+;;
+;; Unless required by applicable law or agreed to in writing,
+;; software distributed under the License is distributed on an
+;; "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+;; KIND, either express or implied. See the License for the
+;; specific language governing permissions and limitations
+;; under the License.
+;;
+
+# Submitting Patches
+
+All contributions are greatly appreciated, but the process can be
+significantly streamlined by taking note of the following guidelines.
+
+## Run the full test suite
+
+Make sure the full test suite runs with your change in place. Even if
+you think your change is very localized, there may be subtle
+repurcussions that impact other parts of the code. If your change
+causes the test suite to fail, then it can't be accepted until a more
+complete fix is prepared.
+
+## Keep it small
+
+Most of the people that work on proton have a day job of some kind. If
+reviewing a patch requires carving out multiple hours/days, then it is
+much less likely to happen. On the other hand if the patch is neat,
+self contained, and just works then it can be reviewed and applied
+quite quickly.
+
+If you happen to have a larger body of work you'd like to contribute
+and there is a good reason that it's difficult to break it down into
+small pieces, that's ok too, but expect the whole process to take a
+bit longer. In this situation you can help things along by providing
+an outline/overview in english to make the work easier to digest.
+
+## Keep it clean
+
+Extraneous whitespace can clutter up diffs and make them more
+difficult to read than they need to be. It's generally good practice
+to avoid introducing extraneous whitespace into files under source
+control. Most editors can be configured to remove and/or display
+extraneous whitespace automatically.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
