| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta charset="utf-8"/> |
| <title>Apache Tamaya: Development Guide</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"/> |
| <meta name="description" content="Homepage of Apache Tamaya (incubating)"/> |
| <meta name="author" content="Apache Tamaya Project Team"/> |
| <meta name="keywords" content="Apache Tamaya Incubating, configuration, Java, ASF, Apache Software Foundation"/> |
| <meta name="generator" content="JBake ${content.version}"/> |
| |
| <!-- Le styles --> |
| <link href="css/bootstrap.min.css" rel="stylesheet"/> |
| <link href="css/asciidoctor.css" rel="stylesheet"/> |
| <link href="css/base.css" rel="stylesheet"/> |
| <link href="css/prettify.css" rel="stylesheet"/> |
| |
| <!-- HTML5 shim, for IE6-8 support of HTML5 elements --> |
| <!--[if lt IE 9]> |
| <script src="js/html5shiv.min.js"></script> |
| <![endif]--> |
| |
| <!-- Fav and touch icons from ASF --> |
| <link rel="shortcut icon" href="favicon.ico"/> |
| <link rel="apple-touch-icon" sizes="57x57" href="favicons/apple-touch-icon-57x57.png"/> |
| <link rel="apple-touch-icon" sizes="60x60" href="favicons/apple-touch-icon-60x60.png"/> |
| <link rel="apple-touch-icon" sizes="72x72" href="favicons/apple-touch-icon-72x72.png"/> |
| <link rel="apple-touch-icon" sizes="76x76" href="favicons/apple-touch-icon-76x76.png"/> |
| <link rel="apple-touch-icon" sizes="114x114" href="favicons/apple-touch-icon-114x114.png"/> |
| <link rel="apple-touch-icon" sizes="120x120" href="favicons/apple-touch-icon-120x120.png"/> |
| <link rel="apple-touch-icon" sizes="144x144" href="favicons/apple-touch-icon-144x144.png"/> |
| <link rel="apple-touch-icon" sizes="152x152" href="favicons/apple-touch-icon-152x152.png"/> |
| <link rel="apple-touch-icon" sizes="180x180" href="favicons/apple-touch-icon-180x180.png"/> |
| <link rel="icon" type="image/png" href="favicons/favicon-32x32.png" sizes="32x32"/> |
| <link rel="icon" type="image/png" href="favicons/favicon-194x194.png" sizes="194x194"/> |
| <link rel="icon" type="image/png" href="favicons/favicon-96x96.png" sizes="96x96"/> |
| <link rel="icon" type="image/png" href="favicons/android-chrome-192x192.png" sizes="192x192"/> |
| <link rel="icon" type="image/png" href="favicons/favicon-16x16.png" sizes="16x16"/> |
| <link rel="manifest" href="favicons/manifest.json"/> |
| <link rel="shortcut icon" href="favicons/favicon.ico"/> |
| <meta name="msapplication-TileColor" content="#603cba"/> |
| <meta name="msapplication-TileImage" content="favicons/mstile-144x144.png"/> |
| <meta name="msapplication-config" content="favicons/browserconfig.xml"/> |
| <meta name="theme-color" content="#303284"/> |
| </head> |
| <body onload="prettyPrint()"> |
| <div id="wrap"> |
| <div> |
| |
| <!-- Fixed navbar --> |
| <div class="navbar navbar-default navbar-fixed-top" role="navigation"> |
| <div class="container"> |
| <div class="navbar-header"> |
| <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse"> |
| <span class="sr-only">Toggle navigation</span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </button> |
| <a class="navbar-brand" href="index.html">Tamaya Home</a> |
| </div> |
| <div class="navbar-collapse collapse"> |
| <ul class="nav navbar-nav"> |
| <li><a href="start.html">Tamaya in 5 minutes</a></li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Documentation <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="documentation/usecases.html">Use Cases and Requirements</a></li> |
| <li><a href="documentation/quickstart.html">Quickstart</a></li> |
| <li><a href="documentation/api.html">API</a></li> |
| <li><a href="documentation/core.html">Core</a></li> |
| <li><a href="documentation/extensions.html">Extension Guide</a></li> |
| <li class="divider"></li> |
| <li><a href="apidocs/stable/index.html">Javadoc 0.4-incubating (release/stable)</a></li> |
| <li><a href="apidocs/development/index.html">Javadoc 0.5-incubating-SNAPSHOT (development)</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Development <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="development/source.html">Sources</a></li> |
| <li><a href="development/community.html">Community</a></li> |
| <li><a href="development/team.html">Project Team</a></li> |
| <li><a target="_blank" href="https://builds.apache.org/view/S-Z/view/Tamaya/">CI / ASF Jenkins</a></li> |
| <li><a target="_blank" href="https://issues.apache.org/jira/browse/TAMAYA">Issues / ASF Jira</a></li> |
| <li><a href="devguide.html">Development Guide</a></li> |
| <li><a href="release-guide.html">Release Guide</a></li> |
| <li class="divider"></li> |
| <li><a href="development/possible-contributions.html">Possible Contributions</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Releases <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="download.html">Download</a></li> |
| <li><a href="history.html">Release History</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">ASF <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="https://www.apache.org/">Apache Software Foundation (ASF)</a></li> |
| <li><a href="https://www.apache.org/foundation/how-it-works.html">How the ASF works</a></li> |
| <li><a href="https://www.apache.org/foundation/getinvolved.html">Get Involved</a></li> |
| <li><a href="https://www.apache.org/dev/">Developer Resources</a></li> |
| <li><a href="https://www.apache.org/foundation/policies/conduct.html">Code of Conduct</a></li> |
| <li><a href="https://www.apache.org/foundation/sponsorship.html">Sponsorship</a></li> |
| <li><a href="https://www.apache.org/licenses/">License</a></li> |
| <li><a href="https://www.apache.org/security">Security</a></li> |
| <li><a href="https://www.apache.org/foundation/thanks.html">Thanks</a></li> |
| <hr/> |
| <li><a href="https://www.apache.org/events/current-event.html"><img src="https://www.apache.org/events/current-event-125x125.png" alt="Current Apache event"/></a></li> |
| </ul> |
| </li> |
| <!-- Example: |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Dropdown <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="#">Action</a></li> |
| <li><a href="#">Another action</a></li> |
| <li><a href="#">Something else here</a></li> |
| <li class="divider"></li> |
| <li class="dropdown-header">Nav header</li> |
| <li><a href="#">Separated link</a></li> |
| <li><a href="#">One more separated link</a></li> |
| </ul> |
| </li> |
| --> |
| <li><a href="sitemap.xml">Sitemap</a></li> |
| <li><a href="feed.xml">Subscribe</a></li> |
| <li><a href="https://incubator.apache.org/guides/website.html" style="border:0px;" target="_target"> |
| <img class="incubator-logo" src="logos/apache-incubator.png"/></a></li> |
| </ul> |
| |
| </div><!--/.nav-collapse --> |
| </div> |
| </div> |
| |
| </div> |
| <div class="container"> |
| |
| <div class="page-header"> |
| <h1>Apache Tamaya: Development Guide</h1> |
| </div> |
| |
| <p><em>2019-11-17</em></p> |
| |
| <p><div class="sect1"> |
| <h2 id="_suggested_git_workflows">1. Suggested Git Workflows</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="_avoid_git_pull">1.1. Avoid git pull!</h3> |
| <div class="paragraph"> |
| <p><code>git pull</code> should never get invoked if you have dirty files lying around |
| or if your branch is ahead of master. This will always lead to |
| some dirty artifacts in the commit history:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>Merge branch 'master' of https://github.com/apache/incubator-tamaya into master</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_use_git_pull_rebase">1.2. Use git pull --rebase</h3> |
| <div class="paragraph"> |
| <p>An easy version for getting rid of the auto-merges is using</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git pull --rebase</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Please note that this sometimes trashes your working tree if there |
| are unmergeable files around. Cleaning this up with a forced manual |
| rebase is not something we would recommend for a git beginner.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_working_in_an_own_branch">1.3. Working in an own branch</h3> |
| <div class="paragraph"> |
| <p>This is actually the suggested way to prevent auto-merges. Create an own |
| branch where you do your feature work. Either do all your work in one |
| branch or create one branch per feature you are working on.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git branch mybranch</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After you finished your feature, first add (<code>git add</code>) and commit (<code>git commit</code>) your work. |
| Check with <code>git status</code> that you don’t have any dirty files and uncommitted |
| changes around. You can use <code>git stash</code> to 'backup' unfinished work.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Then switch back to the master branch and pull changes |
| done by other committers in the meantime.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout master |
| $ git pull --rebase</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You should now get all the changes done by other committers and |
| the will get applied to your local master branch. Now go back to |
| your private branch and rebase your locally performed work to the HEAD of master.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout mybranch |
| $ git rebase master</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you got conflicts, you will get lines with ">>>>" added to those |
| files. Resolve those conflicts manually, add them and finish the rebase.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Check with <code>git-status</code> and <code>gitk</code> if the merge went well and the history now contains your changes. |
| If all is well, go back to the master branch and merge your changes in.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git pull --rebase // (just for safety, you should see no changes) |
| $ git checkout master |
| $ git merge mybranch</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Finally you can push your changes to the ASF git repo</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git push</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="contributing-workflow">2. Contribution workflow</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="_creating_patches">2.1. Creating patches</h3> |
| <div class="paragraph"> |
| <p>You should use the following workflow, if you plan to contribute |
| patches or new features to Tamaya.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First update you local copy of the repository:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout master |
| $ git pull --rebase</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Then create a new local branch for your work. It’s good practice to name |
| it after the corresponding JIRA issue.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout -b TAMAYA-XXX</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Now you can start to work on your patch. When you are finished, commit your changes. But don’t forget to <strong>add the name |
| of the JIRA issue to the commit message</strong>.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git add -am "TAMAYA-XXX: Fixed some issue"</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For small patches we recommend to do a single commit containing your changes. For larger contributions you should try |
| to group your work into separate sub-tasks that you can commit one by one.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Before you create your patch you should make sure that your local repository is up to date with the master repository. |
| This is very important especially if you work on your branch for a long time. Use the following commands to pull the |
| latest changes from the upstream repository and rebase your branch against the current master.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout master |
| $ git pull --rebase |
| $ git checkout TAMAYA-XXX |
| $ git rebase master</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Now you are ready to create your patch:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout TAMAYA-XXX |
| $ git format-patch --stdout master > ../TAMAYA-XXX.patch</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Please attach the resulting patch file to the correspoding JIRA issue.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_applying_patches">2.2. Applying patches</h3> |
| <div class="paragraph"> |
| <p>If you are a committer and want to apply a patch you should do so in a separate branch.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout -b TAMAYA-XXX</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Then apply the patch using <code>git am</code> and rebase it against the master branch.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git am < ../TAMAYA-XXX.patch |
| $ git rebase master</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>After reviewing the changes and testing the code, the changes are ready to |
| be merged into the master branch:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout master |
| $ git merge TAMAYA-XXX |
| $ git branch -d TAMAYA-XXX</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_discussion_workflow_optional">2.3. Discussion workflow (optional)</h3> |
| <div class="paragraph"> |
| <p>All discussions which lead to a decision take place on the mailing list. |
| Sometimes it’s required to show-case an idea esp. if the solution is |
| more than few lines. As shown above it makes sense to use local branches |
| for developing new parts. Git allows to push such local branches to a |
| public repository. So it’s easier to share it with the community |
| for discussing it. The following listings show an example in combination |
| with GitHub - for sure it works with any hosting platform like BitBucket, |
| Google-Code,…​ The only important part here is that such branches |
| <strong>NEVER</strong> get pushed to the main Apache repository to keep the commit history |
| as clean as possible.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_initial_setup">2.4. Initial setup</h3> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git clone https://github.com/apache/incubator-tamaya.git |
| $ git remote add discuss https://[username]@github.com/[username]/[repo-name].git |
| $ git push -u discuss master</pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_branches_for_discussions">2.5. Branches for discussions</h3> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git checkout -b TAMAYA-XXX # 1-n commits |
| $ git push discuss TAMAYA-XXX # share the link to the branch for the discussions</pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p><strong>If the community agrees on the suggested change, the implementation will be applied to the origin master. A committer |
| has to follow the steps described above for the basic workflow to keep the commit history simple, clean and straight. |
| A contributor has to follow the steps described above for creating a patch.</strong></p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="_delete_the_branch_again">2.6. Delete the branch again</h3> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre>$ git push discuss :TAMAYA-XXX |
| $ git branch -d TAMAYA-XXX</pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div></p> |
| |
| <hr /> |
| </div> |
| </div> |
| <div> |
| <div id="push"></div> |
| |
| <div id="footer"> |
| <div class="container"> |
| <p class="muted credit">© 2014-<span>2019</span> Apache Software Foundation | Mixed with <a href="https://getbootstrap.com/">Bootstrap v3.1.1</a> |
| | Baked with <a href="https://jbake.org">JBake <span>v2.6.4</span></a> |
| at <span>2019-11-17</span> | |
| <a class="twitter-follow-button" data-show-count="false" href="https://twitter.com/tamayaconf">Follow @tamayaconf</a><script async src="//platform.twitter.com/widgets.js" charset="utf-8"></script> |
| </p> |
| <p> |
| <b>Disclaimer</b> |
| Apache Tamaya (incubating) is an effort undergoing |
| incubation at |
| The Apache Software Foundation (ASF), sponsored by |
| the Apache Incubator. Incubation is required of |
| all newly accepted projects until a further review indicates |
| that the infrastructure, communications, and decision making |
| process have stabilized in a manner consistent with other |
| successful ASF projects. While incubation status is not |
| necessarily a reflection of the completeness or stability of |
| the code, it does indicate that the project has yet to |
| be fully endorsed by the ASF.<br /> |
| Apache, Apache Tamaya, and the Apache Tamaya logo are registered trademarks or trademarks of The Apache Software Foundation in the U.S. and/or other countries.<br /> |
| <a href="https://incubator.apache.org/guides/website.html" style="border:0px;" target="_target"> |
| <img class="incubator-logo" src="logos/apache-incubator.png" style="height: 50px;"/> |
| </a> |
| </p> |
| </div> |
| </div> |
| |
| <!-- Le javascript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="js/jquery-1.11.1.min.js"></script> |
| <script src="js/bootstrap.min.js"></script> |
| <script src="js/prettify.js"></script> |
| </div> |
| </body> |
| </html> |
