Codebase

Build System

Contributors

Mailing Lists

Participate

Playing Field

RoadMap

RSS Feed

Website Editing

Codebase

After the first 3 years of depending on the OPS4J external link

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 Git submodules, which allows us to have different authorizations in different part of the source tree. 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 the Git submodule feature, and now only have 2 repositories that you are supposed to access directly;

qi4j-sdk
qi4j-sandbox

The Qi4j SDK repository is a straight forward and regular GitHub repository available to clone as:

git clone https://github.com/Qi4j/qi4j-sdk.git

So is the Qi4j Sandbox repository:

git clone https://github.com/Qi4j/qi4j-sandbox.git

Web Access

http://github.com/Qi4j/qi4j-sdk external link

http://github.com/Qi4j/qi4j-sandbox external link

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.

IMPORTANT: 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

People who are interested in helping out with Qi4j will be granted commit rights to Sandbox, Tests, IDE support, Tutorials, Samples, HowTos, documentation and other. 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@lists.ops4j.org mailing list 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:

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

Commit Policy

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

Commits are emailed to qi4j-notify@lists.ops4j.org, and active contributors should subscribe to this list. Send a mail to qi4j-notify-subscribe@lists.ops4j.org to start subscription.

For any given commit, any member of the community may raise concern(s) on the qi4j-dev@lists.ops4j.org 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.

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@ 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 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 (click for larger image).

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.

How do I do my first commit?

We strongly encourage people to read up on Git basics at for instance kernel.org. 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 my_new_feature_branch

Creates a new branch with the given name, unless one already exist, and make the 'current' branch to be the "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 'my_new_feature_branch' and one switch back the changes are not there, now sitting in the 'my_new_feature_branch' only. This is very handy if one forgets to create and move to a branch before modifying the 'develop' branch.

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_xyz' or a 'release_' branch, never directly from 'develop' or feature branches.

Qi4j and the Qi4j logo are trademarks of Richard Öberg, Niclas Hedhman and the members of the Qi4j Core Team. See Qi4j licensing for more information.