Xi Project

Project overview

The Xi project contains multiple components, represented as repositories under the xi-project organization in Github. Each of these components has a designated maintainer, whose job is to upkeep quality and cohesion within the component. (In practice, this boils down to accepting pull requests.)

For contributing to an existing project, you should create a fork of a component and send your updates as pull requests on Github. If you want to contribute an entirely new component, you must assign the repository's ownership to the xi-project account, in which case the repository will be shown in the organization's Github page. You, of course, will be implicitly designated as the component's maintainer.

Guidelines

Tool support

Components should use Composer for autoloading and dependency management and Travis CI for Continuous Integration.

Directory layout

Components should follow a predictable structure.

/

README and LICENSE files

/library

The classes defined by your component.

/tests

Test case classes and bootstraps, with a directory structure mirroring /library.

Versioning

Tag release versions using git tags. Use semantic versioning:

• A normal version number MUST take the form X.Y.Z where X, Y, and Z are integers. X is the major version, Y is the minor version, and Z is the patch version. Each element MUST increase numerically.
• Bump the patch version if you apply small tweaks or include small additional features.
• Bump the minor version if you make changes that break backwards compatibility.
• Bump the major version if you make significant refactorings; however, if you're in major version 0, bumping the minor version should be sufficient.

For working with Git, we recommend the Git branching model, implemented by git-flow for your convenience.

Standards

Coding standards

We're not making our own - all projects should adhere to the PSR-2 coding standard. There's just a few points to make explicit.

• Organize your classes under a single component-level namespace. This namespace should be the same as your component's name, eg. the classes in xi-collections reside under Xi\Collections.
• For exceptions, create a component level marker interface, then create concrete classes that implement the marker interface and preferably extend a semantic PHP Exception type instead of the plain Exception class.
• Do not define global functions and depend on them internally; the choice of which global functions to define should be for the component's user to make.

Architectural standards

• Document at least your core architectural design decisions. Why was the component structured the way it is? What were your main considerations? Inability to understand your design motivations tends to induce a high WTF factor.
• Do not depend directly on externals if you can avoid it. Instead, provide a suitable abstraction for integration with the externality. This allows for a greater potential degree of generalization and reusability.
• Prefer TDD (or derivatives) and high code path coverage to praying it will work. If you can't have high code path coverage, have smoke tests in the very least.
• Please stay DRY.

Other

Recommendations

Most of us use PhpStorm as our IDE. We are happy to recommend it.