After the first 3 years of depending on the OPS4J project, the Qi4j community finally moved to GitHub on the 1 November 2010. This should simplify the learning, as not only does developers have plenty of experience with GitHub external link and the tools it provides, 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.

Public Access Repository

Qi4j differs slightly from the regular project, due to our specific needs and style of development. the main differences are;

  • Qi4j uses the develop branch for the day to day changes to the project. The master branch is used for the latest releases. See below about the 'Git Development Model'.
  • Qi4j 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.

Qi4j used to have many repositories to accommodate for the authorization issue above, but eventually settled with a single GitHub repository, and now only have 2 repositories;

  • qi4j-sdk
  • qi4j-sandbox

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 GitHub repository available to clone as; git clone git://github.com/Qi4j/qi4j-sandbox.git

The Qi4j SDK is the main development codebase, and to start working with it you simply clone it; git clone git://github.com/Qi4j/qi4j-sdk.git

Web Access

The two repositories can be browsed here;

Committer Access

Qi4j has a 3 level committer access system. The groups are "Core", "Platform" and "Community" and the roles are very clear.

Core Developers

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 Qi4j the best platform out there, and not listen in on the voices of features and changes that derails the vision and principles of Qi4j.

Over the course of Qi4j's history, there have been several occasions where brilliant developers got caught up in 'feature improvements' which went against the fibers of Qi4j 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 Qi4j, and we are not likely to invite anyone to the Core Developer team, unless the individual shows remarkable understanding of the inner workings of Qi4j, the philosophy that drives Qi4j and prudence in working on highly sensitive codebases. In return we will strive for making the Qi4j Core as small as possible, having most features in libraries and extensions. We welcome any suggestions that breaks out pluggable functionality.

We apologize in advance if this comes across as elitist, but the purpose is to ensure a high quality Qi4j Runtime, stable over time and not bloating with unnecessary features. Thanks for understanding.

Platform Developers

These form the work force of Qi4j. They will work on the Extensions and Libraries, which eventually will make Qi4j the most efficient way of programming in Java.

Community Developers

Any person who is interested in helping out with Qi4j 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.

Independents

Of course, Git's distributed nature also allows anyone to fork our repositories, and have the patches find their way back to Qi4j's official repository. And GitHub's pull-request system makes the management of this a lot easier, and something that we encourage.

How to Join?

To become a Community Developer, just subscribe to the qi4j-dev at Google Group and request it together with your GitHub user id. For Community Developer, the bar is really, really low and nothing more than a desire to help is required.

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 qi4j-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.

How to get Access to the writable central repositories?

Once you have commit access to a repository, you will access it differently. This is the clone command needed, and after that you will need to do the same as above for pubic access;

git clone git@github.com:Qi4j/qi4j-sdk.git
cd qi4j-sdk

Commit Policy

Qi4j generally uses a Commit-Then-Review policy on most changes. This allows a reasonable high velocity of development.

Commits are visible at GitHub and active contributors should review all incoming commits to ensure quality of contributions and avoidance of mistakes.

For any given commit, any member of the community may raise concern(s) on the qi4j-dev forum at Google Groups. 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.

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 qi4j-dev forum at Google Groups, 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 Qi4j Runtime, and no surprises will occur in existing applications with new versions.

Git Development Model

Courtesy of Vincent Driessen, we borrowed the Git branching model from this web page; http://nvie.com/posts/a-successful-git-branching-model/

The most important part of that excellent article can be found below.

Git Branching Model used at Qi4j

It looks more complicated than it is. Here are the guidelines;

  • Never commit to the 'master' branch while developing!!
  • The 'develop' branch is the equivalent of trunk in subversion.
  • Any changes that are not trivial, start a feature branch.
  • The following names are reserved for not feature branches; master, develop, hotfix/*, release/*

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 Qi4j itself. If you create a new feature, or make some larger piece of refactoring, then please create a 'feature branch' (see article for details).

Please try to remember the --no-fast-forward option during merge, so the feature branch is preserved in one piece and can be rolled back easily if needed.

The release/* and hotfix/* branches are for release management only, and doesn't affect most contributors from a commit perspective. Release Managers - Check the article for the details.

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; https://github.com/nvie/gitflow

What happened to the master branch?

In case you missed it above, check the model that we used for development. The intent is that the master branch is always in a good state and the HEAD is at a formal release (and has a tag for that).

Patches only enters the 'master' branch either from a hotfix/* or a release/* branch, never directly from develop or feature/* branches.

How do I do my first commit?

We strongly encourage people to read up on Git basics at git-scm.com.

But some basic commands are discussed here.

git status

shows you what has not been committed.

git add <filename>

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.

git commit -a -m "<some message>"

This commits the current branch to the local repository. The -a 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'.

git push origin develop

Pushes the local commits back to the origin, i.e. the place the clone came from, or to the location that you have moved the origin to be instead (see above).

git pull origin develop

Pulls/downloads the changes of the develop branch from the origin of your local clone. In subversion terms, this roughly corresponds to a svn update of the trunk.

git branch

Shows which branch we are working on.

git checkout -b feature/my_new_feature_branch

Creates a new branch with the given name, unless one already exist, and make the 'current' branch to be the feature/my_new_feature_branch.

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 feature/my_new_feature_branch and one switch back the changes are not there, now sitting in the feature/my_new_feature_branch only. This is very handy if one forgets to create and move to a branch before modifying the develop branch.

Using Github Pull Requests

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.

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; https://help.github.com/articles/using-pull-requests