| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <title>Apache Polygene™ Codebase</title> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| <meta name="description" content="Apache Polygene™ is a community based effort exploring Composite Oriented Programming for domain centric application development. This includes evolved concepts from Aspect Oriented Programming, Dependency Injection and Domain Driven Design. |
| Composite Oriented Programming allows developers to work with 'fragments', smaller than classes, and 'compose' fragments into larger 'composites' which acts like the regular objects. Apache Polygene™ also tackles the enforcement of application composition, i.e. composites are declared in modules, modules are contained in layers and access between layers are controlled/enforced. |
| "> |
| <meta name="author" content="The Apache Polygene™ Project"> |
| <meta name="keywords" content="cop, composite oriented programming, ddd, domain driven design, composite, mixin, fragment, constraint, concern, side-effect, aop, aspect oriented programming, application, layer, module, structure, java, library, toolkit, framework"> |
| |
| <!-- Le styles --> |
| <link href="/landing-resources/css/bootstrap.css" rel="stylesheet"> |
| <link href="/landing-resources/css/font-awesome.css" rel="stylesheet"> |
| <style type="text/css"> |
| body { |
| padding-top: 70px; |
| padding-bottom: 40px; |
| } |
| #home-logo p { |
| margin-top: 0.75em; |
| font-size: 2.5em; |
| font-weight: lighter; |
| } |
| </style> |
| <link href="/landing-resources/css/bootstrap-responsive.min.css" rel="stylesheet"> |
| |
| <!-- HTML5 shim, for IE6-8 support of HTML5 elements --> |
| <!--[if lt IE 9]> |
| <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script> |
| <![endif]--> |
| |
| <!-- Fav and touch icons --> |
| <link rel="shortcut icon" type="image/png" href="/landing-resources/ico/favicon.png"> |
| |
| <!-- Analytics --> |
| <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','https://www.google-analytics.com/analytics.js','ga'); |
| ga('create', 'UA-89723617-1', 'auto'); |
| ga('send', 'pageview'); |
| </script> |
| |
| </head> |
| |
| <body> |
| |
| <div class="navbar navbar-inverse navbar-fixed-top"> |
| <div class="navbar-inner"> |
| <div class="container-fluid"> |
| <a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse"> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| <span class="icon-bar"></span> |
| </a> |
| <a class="brand" href="/"><img src="/landing-resources/img/logo-234x83.png" style="height: 45px;" /></a> |
| <div class="nav-collapse collapse"> |
| <ul class="nav"> |
| <li><a href="/news.html"><i class="icon-rss"></i> News</a></li> |
| <li><a href="/download.html"><i class="icon-download"></i> Download</a></li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" role="button" data-toggle="dropdown" data-target="#" href="#"> |
| <i class="icon-book"></i> Documentation <b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu" role="menu"> |
| <li role="menuitem"><a href="/java/latest/index.html"><i class="icon-caret-right"></i> Latest release</a></li> |
| |
| |
| <li role="menuitem"><a href="/java/3.0.0/index.html"><i class="icon-caret-right"></i> 3.0.0</a></li> |
| |
| |
| <li role="menuitem"><a href="/java/2.1/index.html"><i class="icon-caret-right"></i> 2.1</a></li> |
| <li role="menuitem"><a href="/java/2.0/index.html"><i class="icon-caret-right"></i> 2.0</a></li> |
| <li role="menuitem"><a href="/java/1.4/index.html"><i class="icon-caret-right"></i> <=1.4.x</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="/java/develop/index.html"><i class="icon-caret-right"></i> develop branch</a></li> |
| </ul> |
| </li> |
| <li class="dropdown"> |
| <a class="dropdown-toggle" role="button" data-toggle="dropdown" data-target="#" href="/community"> |
| <i class="icon-group"></i> Community <b class="caret"></b> |
| </a> |
| <ul class="dropdown-menu" role="menu"> |
| <li role="menuitem"><a href="/community/get_help.html"><i class="icon-caret-right"></i> Get Help</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="/community/participate.html"><i class="icon-caret-right"></i> Participate</a></li> |
| <li role="menuitem"><a href="/community/playing_field.html"><i class="icon-caret-right"></i> Playing Field</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="/community/codebase.html"><i class="icon-caret-right"></i> Codebase</a></li> |
| <li role="menuitem"><a href="https://builds.apache.org/view/S-Z/view/Polygene/" target="_blank"><i class="icon-caret-right"></i> Continuous Integration</a></li> |
| <li role="menuitem"><a href="https://issues.apache.org/jira/browse/POLYGENE" target="_blank"><i class="icon-caret-right"></i> Issues</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="/community/maturity.html"><i class="icon-caret-right"></i> Maturity Model</a></li> |
| <li role="menuitem"><a href="/community/contributors.html"><i class="icon-caret-right"></i> People behind Apache Polygene™</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="http://www.apache.org/licenses/" target="_blank"><i class="icon-caret-right"></i> Licensing</a></li> |
| <li role="menuitem"><a href="/community/licensing_faq.html"><i class="icon-caret-right"></i> Licensing FAQ</a></li> |
| <li class="divider"></li> |
| <li role="menuitem"><a href="http://www.apache.org/foundation/sponsorship.html" target="_blank"><i class="icon-caret-right"></i> Sponsorship</a></li> |
| <li role="menuitem"><a href="http://www.apache.org/foundation/thanks.html" target="_blank"><i class="icon-caret-right"></i> Thanks</a></li> |
| <li role="menuitem"><a href="http://www.apache.org/security/" target="_blank"><i class="icon-caret-right"></i> Security</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div><!--/.nav-collapse --> |
| <!-- ApacheCon resource --> |
| <div style="float: right; padding-top: 2px;"> |
| <a href="http://www.apache.org/events/current-event.html"><img src="http://www.apache.org/events/current-event-234x60.png"/></a> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div id="content" class="container-fluid"> |
| |
| <div class="page-header"> |
| <h1>Codebase</h1> |
| <p class="lead">Apache Polygene™ codebase is hosted at the Apache Software Foundation and follow the git-flow development model.</p> |
| </div> |
| <div class="row-fluid"> |
| <div class="span2"></div> |
| <div class="span8"> |
| <div class="row-fluid"> |
| <div class="span6"> |
| <script type="text/javascript" src="//www.ohloh.net/p/13150/widgets/project_basic_stats.js"></script> |
| </div> |
| <div class="span6"> |
| <script type="text/javascript" src="//www.ohloh.net/p/13150/widgets/project_factoids.js"></script> |
| </div> |
| </div> |
| <p> |
| After the first 3 years of depending on the |
| <a href="http://team.ops4j.org" title="Open Participation for Java">OPS4J</a> project, then 5 years on |
| <a href="https://github.com/qi4j">Github</a>, the Qi4j community finally moved to the |
| <a href="https://www.apache.org/">Apache Software Foundation</a> (ASF) on March 2015. |
| The codebase history is kept in <a href="https://git-scm.com/">Git</a> repositories, mirrored to the |
| <a href="https://github.com/apache?query=polygene">ASF Github organization</a>. |
| This should simplify the learning, as not only does developers have plenty of experience with Git, and |
| tools around it, but also there are endless amount of documentation and user forums to support each |
| individual, off-loading some of that burden from us. |
| This page only contain rudimentary information. |
| </p> |
| <h2>Public Access Repository</h2> |
| <p> |
| Apache Polygene™ differs slightly from the regular project, due to our specific needs and style of development. the main |
| differences are; |
| </p> |
| <ul> |
| <li> |
| Apache Polygene™ uses the <code>develop</code> branch for the day to day changes to the project. The |
| <code>master</code> branch is used for the latest releases. See below about the 'Git Development Model'. |
| </li> |
| <li> |
| Apache Polygene™ uses a social contract to limit access to different areas of the project, instead of ACLs. The |
| driving point is to relax the contribution criteria in less critical parts, to encourage a wider |
| participation that otherwise would not be possible. |
| </li> |
| </ul> |
| <p> |
| Apache Polygene™ used to have many repositories to accommodate for the authorization issue above, but eventually |
| settled with a single Git repository, and now only have 2 repositories; |
| </p> |
| <ul> |
| <li><code>polygene-java</code></li> |
| <li><code>polygene-sandbox</code></li> |
| </ul> |
| <p> |
| The sandbox is where experimental code goes, and modules that are not ready to be shipped, or can not be |
| shipped due to licensing restrictions (e.g. Oracle doesn't provide Coherence as automatic download for our |
| testing, so can't really ship the coherence extension). The sandbox is a normal Git repository available |
| to clone as; <code>git clone https://git-wip-us.apache.org/repos/asf/polygene-sandbox.git</code> |
| </p> |
| <p> |
| The Apache Polygene™ (Java Edition) is the main development codebase, and to start working with it you simply clone it; |
| <code>git clone https://git-wip-us.apache.org/repos/asf/polygene-java.git</code> |
| </p> |
| |
| <h2>Web Access</h2> |
| <p> |
| The two repositories can be browsed on the mirrors on the ASF Github organization; |
| </p> |
| <ul> |
| <li><a href="https://github.com/apache/polygene-java">https://github.com/apache/polygene-java</a></li> |
| <li><a href="https://github.com/apache/polygene-sandbox">https://github.com/apache/polygene-sandbox</a></li> |
| </ul> |
| |
| <h2>Committer Access</h2> |
| <p class="lead"> |
| Apache Polygene™ has a 3 level committer access system. The groups are "Core", "Platform" and "Community" and the roles |
| are very clear. |
| </p> |
| |
| <h3>Core Developers</h3> |
| <p> |
| These are the guardians and stewards of the core technology and ultimate rulers of what is going on. The |
| hope is that a small group of benevolent dictators will manage to make Apache Polygene™ the best platform out there, |
| and not listen in on the voices of features and changes that derails the vision and principles of Apache Polygene™. |
| </p> |
| <div class="well"> |
| <p> |
| Over the course of Apache Polygene™'s history, there have been several occasions where brilliant developers got |
| caught up in 'feature improvements' which went against the fibers of Apache Polygene™ philosophy and technological |
| direction. IF we would have had an 'open door' policy to changes in Core, these 'improvements' would |
| have degraded the excellence of Apache Polygene™, and we are not likely to invite anyone to the Core Developer |
| team, unless the individual shows remarkable understanding of the inner workings of Apache Polygene™, the |
| philosophy that drives Apache Polygene™ and prudence in working on highly sensitive codebases. In return we will |
| strive for making the Apache Polygene™ Core as small as possible, having most features in libraries and extensions. |
| We welcome any suggestions that breaks out pluggable functionality. |
| </p> |
| <p> |
| We apologize in advance if this comes across as elitist, but the purpose is to ensure a high quality |
| Apache Polygene™ Runtime, stable over time and not bloating with unnecessary features. Thanks for understanding. |
| </p> |
| </div> |
| |
| <h3>Platform Developers</h3> |
| <p> |
| These form the work force of Apache Polygene™. They will work on the Extensions and Libraries, which eventually will |
| make Apache Polygene™ the most efficient way of programming in Java. |
| </p> |
| |
| <h3>Community Developers</h3> |
| <p> |
| Any person who is interested in helping out with Apache Polygene™ will be granted access to Sandbox, Tests, IDE |
| support, Tutorials, Samples, HowTos, documentation and other (i.e. not Core, Libraries and Extensions). |
| This will gauge their abilities and commitment to the project, with an aim to make them Platform Developers. |
| </p> |
| |
| <h3>Independents</h3> |
| <p> |
| Of course, Git's distributed nature also allows anyone to fork our repositories, and have the patches find |
| their way back to Apache Polygene™'s official repository. And GitHub's pull-request system makes the management of this |
| a lot easier, and something that we encourage. |
| </p> |
| |
| <h3>How to Join?</h3> |
| <p> |
| To become a Community Developer, just subscribe to the |
| <a href="mailto:dev-subscribe@polygene.apache.org">dev@polygene.apache.org</a> mailing list and participate, |
| nothing more than a desire to help is required. |
| </p> |
| <p> |
| Community Developers who are active and keep contributing feedback, patches and/or documentation are likely |
| to be invited as Platform Developers, who has access to everything except the delicate Core, which we |
| intend to keep a lot more clean and stable than a free-for-all repository has a tendency to become over |
| time. |
| </p> |
| |
| <h2>Commit Policy</h2> |
| <p class="lead"> |
| Apache Polygene™ generally uses a Commit-Then-Review policy on most changes. This allows a reasonable high velocity of |
| development. |
| </p> |
| <p> |
| Commits are visible in Git history and at GitHub. Active contributors should review all incoming commits to |
| ensure quality of contributions and avoidance of mistakes. |
| </p> |
| <p> |
| For any given commit, any member of the community may raise concern(s) on the <code>dev@</code> mailing |
| list. We encourage as many people as possible to review the changes that are occurring. "With enough |
| eyeballs every bug is shallow." wrote Eric S. Raymond in "The Cathedral and The Bazaar" about open source. |
| </p> |
| <p> |
| Special rules applies to changes in the Core Test suite. Adding new tests are CTR, but modifying existing |
| tests, either to accommodate for code changes in Core or to tighten the constraints of them, MUST be |
| discussed on the <code>dev@</code> mailing list, prior to committing them to the 'develop' branch. We |
| recommend that a different branch is used for these changes, unless simply codesnippets are pasted to mail. |
| This exists to ensure that we have a stable evolution of Apache Polygene™ (Java Edition) Runtime, and no surprises will occur in |
| existing applications with new versions. |
| </p> |
| |
| <h2>Git Development Model</h2> |
| <p> |
| Courtesy of Vincent Driessen, we borrowed the Git branching model from this web page; |
| <a href="http://nvie.com/posts/a-successful-git-branching-model/">http://nvie.com/posts/a-successful-git-branching-model/</a> |
| </p> |
| <p style="text-align: center"> |
| <img src="../landing-resources/img/git-model.png"/> |
| </p> |
| <p> |
| The most important part of that excellent article can be found below. |
| </p> |
| |
| <h3>Git Branching Model used at Apache Polygene™</h3> |
| <p> |
| It looks more complicated than it is. Here are the guidelines; |
| </p> |
| <ul> |
| <li>Never commit to the 'master' branch while developing!!</li> |
| <li>The 'develop' branch is the equivalent of trunk in subversion.</li> |
| <li>Any changes that are not trivial, start a feature branch.</li> |
| <li> |
| The following names are reserved for not feature branches; <code>master</code>, <code>develop</code>, |
| <code>hotfix/*</code>, <code>release/*</code> |
| </li> |
| </ul> |
| <p> |
| Day-to-day development revolves around the develop branch and it is this branch that you typically clone |
| from our repository if you intend to contribute to Apache Polygene™ itself. If you create a new feature, or make some |
| larger piece of refactoring, then please create a 'feature branch' (see article for details). |
| </p> |
| <p> |
| Please try to remember the <code>--no-fast-forward</code> option during merge, so the feature branch is |
| preserved in one piece and can be rolled back easily if needed. |
| </p> |
| <p> |
| The <code>release/*</code> and <code>hotfix/*</code> branches are for release management only, and doesn't |
| affect most contributors from a commit perspective. Release Managers - Check the article for the details. |
| </p> |
| <p> |
| For convenience you should install and use the gitflow git extension that implement this branching model |
| by adding git commands. See the gitflow web page; |
| <a href="https://github.com/nvie/gitflow">https://github.com/nvie/gitflow</a> |
| </p> |
| |
| <h3>What happened to the <code>master</code> branch?</h3> |
| <p> |
| In case you missed it above, check the model that we used for development. The intent is that the |
| <code>master</code> branch is always in a good state and the <code>HEAD</code> is at a formal release |
| (and has a tag for that). |
| </p> |
| <p> |
| Patches only enters the 'master' branch either from a <code>hotfix/*</code> or a <code>release/*</code> |
| branch, never directly from <code>develop</code> or <code>feature/*</code> branches. |
| </p> |
| |
| <h2>How do I do my first commit?</h2> |
| <p class="lead"> |
| We strongly encourage people to read up on Git basics at <a href="http://git-scm.com/">git-scm.com</a>. |
| </p> |
| <p> |
| But some basic commands are discussed here. |
| </p> |
| <pre><code>git status</code></pre> |
| <p> |
| shows you what has not been committed. |
| </p> |
| <pre><code>git add <filename></code></pre> |
| <p> |
| all files(!) must be added. Directories are not considered and generally ignored. You can add with |
| wildcards, even if some files have already been added. |
| </p> |
| <pre><code>git commit -a -m "<some message>"</code></pre> |
| <p> |
| This commits the current branch to the local repository. The <code>-a</code> means commit all files, and |
| not only the ones that are explicitly mentioned on this command. The message should be informative as it |
| will follow the patch 'forever'. |
| </p> |
| <pre><code>git push origin develop</code></pre> |
| <p> |
| Pushes the local commits back to the <code>origin</code>, i.e. the place the clone came from, or to the |
| location that you have moved the <code>origin</code> to be instead (see above). |
| </p> |
| <pre><code>git pull origin develop</code></pre> |
| <p> |
| Pulls/downloads the changes of the <code>develop</code> branch from the <code>origin</code> of your local |
| clone. In subversion terms, this roughly corresponds to a <code>svn update</code> of the trunk. |
| </p> |
| <pre><code>git branch</code></pre> |
| <p> |
| Shows which branch we are working on. |
| </p> |
| <pre><code>git checkout -b feature/my_new_feature_branch</code></pre> |
| <p> |
| Creates a new branch with the given name, unless one already exist, and make the 'current' branch to be the |
| <code>feature/my_new_feature_branch</code>. |
| </p> |
| <p> |
| When you do a checkout of a branch, the local changes in the current branch that are not committed are not |
| lost, but are also 'moved along' to the new branch. And if those changes are then committed in the |
| <code>feature/my_new_feature_branch</code> and one switch back the changes are not there, now sitting in |
| the <code>feature/my_new_feature_branch</code> only. This is very handy if one forgets to create and move |
| to a branch before modifying the <code>develop</code> branch. |
| </p> |
| |
| <h3>Using Github Pull Requests</h3> |
| <p> |
| Pull requests let you tell others about changes you've pushed to a GitHub repository. Once a pull request |
| is sent, interested parties can review the set of changes, discuss potential modifications, and even push |
| follow-up commits if necessary. |
| </p> |
| <p> |
| Github's guide to Pull Requests walks through the process of sending a hypothetical pull request and using |
| the various code review and management tools to take the change to completion. This guide can be found here; |
| <a href="https://help.github.com/articles/using-pull-requests">https://help.github.com/articles/using-pull-requests</a> |
| That article assume that we have direct control of the GitHub repository, but we don't. Instead we need to |
| pull the Pull Request to our local machine, merge it in and then push it back via the Apache GIT server. |
| </p> |
| <p> |
| The infrastructure team is working on Pull Request support on the GitHub servers directly, but it is not |
| available by default yet. |
| </p> |
| <p> |
| Example, for pull request 42, you would need to do the following; |
| <pre><code> |
| # You need to have a "remote" defined in your git configuration |
| # This is only needed once |
| git remote add github https://github.com/apache/polygene-java.git |
| |
| # Fetch the commit |
| git fetch github pull/42/head:merge-pr-42 |
| |
| # These next two steps are optional. |
| # If you choose to rebase, then the Pull Request is not automatically closed. |
| git checkout merge-pr-42 |
| git rebase develop |
| |
| # Check out 'develop' branch |
| git checkout develop |
| |
| # Merge the PR |
| git merge merge-pr-42 |
| |
| # Remove the PR branch |
| git branch -D merge-pr-42 |
| |
| # Push the result |
| git push origin develop |
| |
| </code></pre> |
| </p> |
| </div> |
| <div class="span2"></div> |
| </div> |
| |
| |
| |
| </div> |
| <div class="container-fluid"> |
| <hr> |
| <footer> |
| <p> |
| Copyright © 2015-2018 The Apache Software Foundation, Licensed under the <a href="http://www.apache.org/licenses/">Apache License, Version 2.0</a>. |
| <br/> |
| <small> |
| Apache Polygene, Polygene, Apache, the Apache feather logo, and the Apache Polygene project logo are trademarks of The Apache Software Foundation.<br/> |
| All other marks mentioned may be trademarks or registered trademarks of their respective owners. |
| </small> |
| </p> |
| </footer> |
| </div> |
| |
| <!-- Le javascript |
| ================================================== --> |
| <!-- Placed at the end of the document so the pages load faster --> |
| <script src="/landing-resources/js/jquery-1.8.3.min.js"></script> |
| <script src="/landing-resources/js/bootstrap.min.js"></script> |
| <script src="/landing-resources/js/qi4j.org.js"></script> |
| </body> |
| </html> |
