Contributions Guidelines

AjaXplorer is an open source software, and the code is published under the AGPL License. As such, the code is publicly available on GitHub, and forking is particularly recommanded! Still, contribution must be done following some guidelines.

Contributor License Agreement

The CLA is an agreement commonly used in major open source project, which aims at protecting all parties implied by a contribution : the contributor, the main code author, and above all, the community. The CLA model we have chosen basically tells the following : the contribution’s copyright is shared between the contributor and the main author. This means each party can do whatever she want in term of relicensing with this contributed piece of code. This is important, because, if in the future, the author wants to change the license in something more in favor of the community, a singular contributor cannot block the process.

To ease the process, the CLA is directly signable online using the clever service CLAHub. Please first register to Github (if not already), and then go to http://www.clahub.com/agreements/ajaxplorer/ajaxplorer-core to sign the CLA electronically.

Coding guidelines

Read before contributing!

AjaXplorer currently does not impose some PSR norm for the PHP coding. Still, every contribution will be reviewed very carefully, and we want to draw your attention on the following

  • If you are fixing a simple bug, through some kind of one-line commit, please test the changes you made in many contexts. With modularity, comes the variety of situation in which AjaXplorer can be deployed, and as such, having a working patch for a given set of plugins do not necessarily means it will be working well when switching to other plugins. E.g. switching between DB-based & Serial-based configs storage, testing with various workspaces access drivers, etc…
  • If you want to provide a brand new feature, the very first step will be to understand the plugin architecture, and the events that are triggered to “communicate” between them. That way, for most feature, you should be able to provide a unique self-containing plugin with all necessary data. When accepted, plugins will first be published as “contributed” plugins, from the website and not directly available in the core package. If the feature is successful, plugins may integrate the core at one point.
  • Take me to the developer guide!

Pulling requests

The code is located at https://github.com/ajaxplorer/. From here, you can fork to write your own plugins or provide bug fixes.

Once you are happy with your code, please use the now standard Github “Pull Request” mechanism to submit your changes. If you are not familiar with git, reading https://help.github.com/articles/using-pull-requests is a good start.

Understanding versions numbering

The version numbering is fairly simple. Based on the Major.Branch.Minor, all even branches are considered stable (2.2, 2.4, 3.0.1, 3.0.2, etc.) and all odd branches are considered development branches.

Adding translations

In AjaXplorer, internationalisation (i18n) is part of the core design of the application. Thus, we already provide more than 20 languages, but as many features are added along the years, they are not all up-to-date. If you want to contribute on this, please do the following :

  • First, “fork” the code by registering to Github and create your own “branch” of AjaXplorer to work with. Set up your own working install by cloning your branch on your server, and create a VirtualHost pointing to the ajaxplorer-core/core/src/ folder.
  • Each plugin can eventually provide its own i18n files, generally located in res/ or i18n/ . This “i18n libraries” are declared inside the manifest.xml file of the plugin.
  • The language files are all structured as follow
    • Naming : [lang_code].php , where lang_code is the two-letter language code, lowercase. E.g en.php, fr.php, de.php, etc…
    • Content : a PHP array called $mess containing a set of key=>values.
    • The reference is always the en.php file. Thus, any other language file must contain at least the same keys.
    • Usage : except for the core.ajaxplorer library, a plugin library is declared with a namespace, and inside the application, accessing a message will be done using the namespace and the message key. For example, “share_center.1″, “meta_watch.23″, etc…
  • To add support for new languages inside a plugin, simply duplicate the en.php file using the language code, and replace the values with the correct translations. Make sure to use UTF-8 for the charset.
  • There is a cache for this part. Manually delete the content of data/cache/i18n/*.ser to make sure that the cache is regenerated at next application loaded.
  • Once you are set up, submit your changes as a Pull Request on GitHub. Make sure to submit one PR, not one per file…