| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| |
| |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> |
| <title>PLC4X – </title> |
| <script src="../js/jquery.slim.min.js" type="text/javascript"></script> |
| <!--script src="../js/popper.min.js" type="javascript"></script--> |
| <script src="../js/bootstrap.bundle.min.js" type="text/javascript"></script> |
| <!-- The tooling for adding images and links to Apache events --> |
| <script src="https://www.apachecon.com/event-images/snippet.js" type="text/javascript"></script> |
| <!-- FontAwesome --> |
| <link rel="stylesheet" href="../css/all.min.css" type="text/css"/> |
| <!-- Bootstrap --> |
| <link rel="stylesheet" href="../css/bootstrap.min.css" type="text/css"/> |
| <!-- Some Maven Site defaults --> |
| <link rel="stylesheet" href="../css/maven-base.css" type="text/css"/> |
| <link rel="stylesheet" href="../css/maven-theme.css" type="text/css"/> |
| <!-- The PLC4X version of a bootstrap theme --> |
| <link rel="stylesheet" href="../css/themes/plc4x.css" type="text/css" id="pagestyle"/> |
| <!-- A custom style for printing content --> |
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print"/> |
| |
| <meta http-equiv="Content-Language" content="en"/> |
| |
| </head> |
| <body class="composite"> |
| <nav class="navbar navbar-light navbar-expand-md bg-faded justify-content-center border-bottom"> |
| <!--a href="/" class="navbar-brand d-flex w-50 mr-auto">Navbar 3</a--> |
| <a href="https://plc4x.apache.org/" id="bannerLeft"><img src="../images/apache_plc4x_logo_small.png" alt="Apache PLC4X"/></a> |
| <button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#collapsingNavbar3"> |
| <span class="navbar-toggler-icon"></span> |
| </button> |
| <div class="navbar-collapse collapse w-100" id="collapsingNavbar3"> |
| <ul class="navbar-nav w-100 justify-content-center"> |
| <li class="nav-item"> |
| <a class="nav-link" href="../index.html">Home</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../users/index.html">Users</a> |
| </li> |
| <li class="nav-item active"> |
| <a class="nav-link" href="../developers/index.html">Developers</a> |
| </li> |
| <li class="nav-item"> |
| <a class="nav-link" href="../apache/index.html">Apache</a> |
| </li> |
| </ul> |
| <ul class="nav navbar-nav ml-auto justify-content-end"> |
| <li class="nav-item row valign-middle"> |
| <a class="acevent" data-format="wide" data-mode="light" data-event="random" style="width:240px;height:60px;"></a> |
| </li> |
| </ul> |
| </div> |
| </nav> |
| <div class="container-fluid"> |
| <div class="row h-100"> |
| |
| |
| |
| |
| |
| |
| |
| |
| <nav class="col-sm-push col-md-2 pt-3 sidebar"> |
| <div class="sidebar-sticky"> |
| <ul class="nav flex-column"> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/index.html" class="nav-link">Section Home</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/preparing/index.html" class="nav-link">Preparing your Computer</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/preparing/linux.html" class="nav-link">Linux</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/preparing/macos.html" class="nav-link">Mac OS</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/preparing/windows.html" class="nav-link">Windows</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/building.html" class="nav-link">Building</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <strong class="nav-link">Contributing</strong> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/tutorials/index.html" class="nav-link">Tutorials</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/tutorials/writing-driver.html" class="nav-link">Writing Drivers</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/tutorials/testing-serializers-and-parsers.html" class="nav-link">Testing Drivers</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/code-gen/index.html" class="nav-link">Code Generation</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/protocol/mspec.html" class="nav-link">Protocol: MSpec Format</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/language/freemarker.html" class="nav-link">Language: Apache Freemarker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/code-gen/protocol/df1.html" class="nav-link">Example: DF1 MSpec</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/index.html" class="nav-link">Infrastructure</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/ci.html" class="nav-link">Continuous Integration</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/issues.html" class="nav-link">Bug & Issue Tracker</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/sonar.html" class="nav-link">Code Analysis</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/wiki.html" class="nav-link">Wiki</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/vm.html" class="nav-link">Build VM</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/website.html" class="nav-link">Website</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/infrastructure/vpn.html" class="nav-link">IoT VPN</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/release/index.html" class="nav-link">Releasing</a> |
| <ul class="flex-column pl-4 nav"> |
| <li class="nav-item"> |
| <a href="../developers/release/release.html" class="nav-link">Releasing</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/release/validation.html" class="nav-link">Validating</a> |
| </li> |
| <li class="nav-item"> |
| <a href="../developers/release/build-tools.html" class="nav-link">Releasing Build-Tools</a> |
| </li> |
| </ul> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/tools.html" class="nav-link">Tools</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/team.html" class="nav-link">Team</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/decisions.html" class="nav-link">Decision Making</a> |
| </li> |
| |
| |
| <li class="nav-item"> |
| <a href="../developers/maturity.html" class="nav-link">Maturity</a> |
| </li> |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| |
| </ul> |
| </div> |
| </nav> |
| <main role="main" class="ml-sm-auto px-4 col-sm-pull col-md-9 col-lg-10 h-100"> |
| <div class="sect1"> |
| <h2 id="contributing">Contributing</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="forms_of_contribution">Forms of contribution</h3> |
| <div class="paragraph"> |
| <p>There are multiple forms in which you can become involved with the PLC4X project.</p> |
| </div> |
| <div class="paragraph"> |
| <p>These usually are, but are not limited to:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Submitting Pull Requests</p> |
| </li> |
| <li> |
| <p>Filing Bug-Reports</p> |
| </li> |
| <li> |
| <p>Active communication on our mailing lists</p> |
| </li> |
| <li> |
| <p>Promoting the project (articles, blog posts, talks at conferences)</p> |
| </li> |
| <li> |
| <p>Documentation</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>We are a very friendly bunch and don’t be afraid to step forward.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="pull_requests">Pull-Requests</h3> |
| <div class="paragraph"> |
| <p>The simplest way to submit code changes, is via a GitHub pull-request.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to do this first create a GitHub account and sign into you account.</p> |
| </div> |
| <div class="paragraph"> |
| <p>After that’s done, please to to our <a href="https://github.com/apache/plc4x">GitHub site</a> and create a so-called <code>Fork</code>.</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../images/contributing-github-fork.png" alt="contributing github fork"/> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>What happens now, is that GitHub creates a full copy of the PLC4X repo in your account. Only you can commit to this.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Now ideally you check-out your cloned repository:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git clone https://github.com/{your-user-id}/plc4x.git</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Now you have a copy of PLC4X on your computer and you can change whatever you want and as it’s your copy, you can even commit these changes without any danger of breaking things.</p> |
| </div> |
| <div class="paragraph"> |
| <p>As soon as you’re finished with your changes and want us to have a look, it’s time to create a so-called <code>Pull-Request</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You do that by going to your forked repository page on GitHub.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Every forked repository has an additional button called "New Pull Request":</p> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../images/contributing-github-create-pull-request.png" alt="contributing github create pull request"/> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you click on this, we will receive a notification on your changes and can review them. |
| We also can discuss your changes and have you perfect your pull request before we accept and merge it into PLC4X.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="keeping_your_fork_up_to_date">Keeping your fork up to date</h4> |
| <div class="paragraph"> |
| <p>As we are continuously working on PLC4X and you created a copy of our repo, this will become out-of-date pretty soon.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order get the changes we introduced in the official repo you have to tell git about that.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You do this locally by adding a new so-called <code>remote</code>. |
| Per default the remote you cloned from is called <code>origin</code>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Usually you will call the second remote <code>upstream</code> but in general you can call it whatever you like.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Add the remote on the commandline (or your git gui of choice):</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git remote add upstream https://github.com/apache/plc4x.git</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you list all your remotes, with the following command:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git remote -v</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It should output something like this:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>origin https://github.com/{your-user-id}/plc4x.git (fetch) |
| origin https://github.com/{your-user-id}/plc4x.git (push) |
| upstream https://github.com/apache/plc4x.git (fetch) |
| upstream https://github.com/apache/plc4x.git (push)</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If that’s so, you’re fine to continue, if not …​ well you could ask for assistance on our dev-list.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to get all changes of our upstream-repository, just execute the following command:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git pull upstream</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>This will get all changed from upstream and merge them locally. In order to update your GitHub version, you have to push things back to <code>origin</code>. |
| You can do this by executing the following command:</p> |
| </div> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>git push</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>(If no remote is provided, git will use <code>origin</code> per default)</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="bug_reports">Bug Reports</h3> |
| <div class="paragraph"> |
| <p>We use <a href="https://issues.apache.org/jira/projects/PLC4X">JIRA</a> as our Bug & Issue Tracker.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Feel free to submit <code>feature requests</code>, <code>bug reports</code>, <code>patches</code>, <code>comment on issues</code>, …​</p> |
| </div> |
| <div class="paragraph"> |
| <p>In order to be able to do so, you need to create an account first.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Currently Apache has a separate login system for JIRA and all other services, this might change in the future, but right now it’s the way things are.</p> |
| </div> |
| <div class="paragraph"> |
| <p>So if you are considering to contribute more than just a one-time-patch, please choose a username that hasn’t been used by an existing <a href="http://people.apache.org/committer-index.html">Apache committer</a> as this will simplify things if we invite you to become part of the team.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you want to be assigned to an issue because you want to work on it, please request to be added to the JIRA groups on our <a href="http://plc4x.apache.org/mailing-lists.html">developers mailing list</a></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="documentation">Documentation</h3> |
| <div class="paragraph"> |
| <p>As our documentation and website are generated as a side-product of our build, contributing to this technically the same as contributing to the code.</p> |
| </div> |
| <div class="paragraph"> |
| <p>All our content is written in Asciidoctor and is located in <code>src/site/asciidoc</code> directories. |
| For a reference of the Asciidoctor syntax please have a look at the <a href="https://asciidoctor.org/docs/user-manual/#introduction-to-asciidoctor">Asciidoctor documentation</a>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="branching_model">Branching model</h3> |
| <div class="paragraph"> |
| <p>The PLC4X project uses the following branching model.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The same model is used for a wide variety of other projects, so it should be pretty straight forward.</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>release</code> contains the latest released state.</p> |
| </li> |
| <li> |
| <p>Development is performed on the <code>develop</code> branch.</p> |
| </li> |
| <li> |
| <p>Features are developed in Feature-Branches with a prefix <code>feature/</code></p> |
| </li> |
| <li> |
| <p>Each minor release has a corresponding release branch <code>rel/{major-version}.{minor-version}</code></p> |
| </li> |
| <li> |
| <p>A release branch is spawned from <code>develop</code> only</p> |
| </li> |
| <li> |
| <p>Bugfix releases don’t have a dedicated release branch, they are just performed on the corresponding minor versions release branch</p> |
| </li> |
| </ul> |
| </div> |
| <div class="imageblock"> |
| <div class="content"> |
| <img src="../images/plc4x-branching-model.png" alt="plc4x branching model" width="2919" height="519"/> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </main> |
| <footer class="pt-4 my-md-5 pt-md-5 w-100 border-top"> |
| <div class="row justify-content-md-center" style="font-size: 13px"> |
| <div class="col col-6 text-center"> |
| Copyright © 2017–2022 <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All rights reserved.<br/> |
| Apache PLC4X, PLC4X, Apache, the Apache feather logo, and the Apache PLC4X project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries. All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| <br/><div style="text-align:center;">Home screen image taken from <a |
| href="https://flic.kr/p/chEftd">Flickr</a>, "Tesla Robot Dance" by Steve Jurvetson, licensed |
| under <a href="https://creativecommons.org/licenses/by/2.0/">CC BY 2.0 Generic</a>, image cropped |
| and blur effect added.</div> |
| </div> |
| </div> |
| </footer> |
| </div> |
| </div> |
| |
| <!-- Bootstrap core JavaScript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="../js/jquery.slim.min.js"></script> |
| <script src="../js/popper.min.js"></script> |
| <script src="../js/bootstrap.min.js"></script> |
| <script type="text/javascript"> |
| $('.carousel .carousel-item').each(function(){ |
| var next = $(this).next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| |
| for (let i = 0; i < 3; i++) { |
| next=next.next(); |
| if (!next.length) { |
| next = $(this).siblings(':first'); |
| } |
| next.children(':first-child').clone().appendTo($(this)); |
| } |
| }); |
| </script> |
| </body> |
| </html> |
