-
Notifications
You must be signed in to change notification settings - Fork 19
Developer Guidelines
The Achievo community includes Users, Builders, Developers, and Project Maintainers.
- A User uses the functionality provided by Achievo in a role distinct from the Achievo project, including administration of the Achievo system by accessing the appropriate menus.
- A Builder installs and configures an Achievo system for its users, including Core modules (included with Achievo), and potentially including Add-on modules (supported by the Achievo project but downloaded and installed separately from the GitHub atkphpframework group) and Custom modules (developed and supported separately from the Achievo project).
- A Developer contributes directly to the Achievo project, including submitting new or modified code or other files (e.g. PHP, HTML, CSS, Javascript, images and documentation), testing Achievo behavior, submitting issue reports, and providing expertise and informed input for Achievo project decisions.
- A Project Maintainer is a special type of Developer with the authority to merge submitted changes into the canonical project repositories. Project Maintainers are the official shepherds of the project, and are also responsible for providing project leadership and cohesive guidance to the Achievo community.
A Release is simply a unique assembly of files, that together make up Achievo, published by the Achievo developers for use by others. Each release is assigned a unique Version Number as a reference, and the amount of change from one release to another can be inferred from their version numbers.
A Version Number is a sequence of numbers separated by periods in the form X.Y.Z, where X is called the Major version number, Y is the Minor version number, and Z is the Maintenance version number.
- a change in maintenance version (e.g. from Achievo 1.4.5 to 1.4.6) indicates that only backwards compatible defect corrections have been made. A maintenance release corrects defects in pre-existing features, it does not introduce new features.
- a change in minor version (e.g. from Achievo 1.4.5 to 1.5.0) indicates that new backwards-compatible functionality has been introduced in a public interface, or new functionality or improvements have been introduced internally. A minor version change may include maintenance defect corrections.
- a change in major version (e.g. from Achievo 1.5.0 to 2.0.0) may indicate that changes have been made to a public interface that are NOT backwards compatible (the introduction of non-backwards compatible changes requires a major version change), or that new features of such significance have been introduced that a major version change is deemed appropriate.
- The Semantic Versioning specification: http://semver.org. The specification is authored by Tom Preston-Werner, co-founder of Github, and describes how the change in a version number indicates the amount of change in the software APIs.
- The Software Versioning article in Wikipedia: http://en.wikipedia.org/wiki/Software_versioning
From time to time, the Achievo developers may publish a Pre-release, intended to preview upcoming changes. The most common purpose of a pre-release is for testing, but a pre-release may also demonstrate new features for preliminary evaluation. A Pre-release is not intended for use in production.
Pre-releases are identified with the version number of the intended eventual release, followed by a pre-release designator and a series of dot separated numeric identifiers. The different pre-releases are:
-
Release Candidate. A release candidate is used to build confidence in code intended for eventual regular release. All features intended for the regular release have been implemented, and there are no significant known defects. Release candidates are made from a release branch in the repository.
- e.g. 1.6.0-rc.1 (the first release candidate of the code eventually to be released as 1.6.0)
-
Alpha Release. An alpha release provides an opportunity to evaluate preliminary functionality at an early stage of development, and can be used with caution for demonstrations in controlled environments. Alpha releases do not generally lead directly to a regular release (or release candidate), and alpha release version numbers do not include a maintenance version number. Alpha releases are made from a development branch in the repository.
- e.g. 2.0-alpha.1 (the first alpha release of features intended for release in 2.0.0)
-
Beta Release. A Beta release provides an opportunity to evaluate new features as they will likely be implemented, to give guidance to related activities (e.g. preliminary work on human workflows, and external software development). Beta releases are made from a development branch in the project repository, and beta release version numbers do not include a maintenance version number.
- e.g. 2.0-beta.1 (the first beta release of features intended for release in 2.0.0)
GitHub "Issues" are for managing bugs and other development tasks (re-factoring for performance isn't a bug, but it is still an issue). Issues can be assigned (even if it's to yourself), and all development tasks should preferably have an Issue created, so that other developers can easily see what needs doing, and who's already working on what.
Achievo and ATK development use the Git Distributed Version Control System (DVCS), with the canonical project repositories hosted on GitHub in the atkphpframework group.
The detailed workflow will eventually be included here, but in general it follows the Gitflow model, modified for the Fork and Pull model on GitHub. This blog post is another reference, but it is work in process and should currently be used for general guidance only).
The develop branch in the canonical project repository is stable code intended for the next production release. The master branch follows production releases, and is always the most recent minor-version production release (if more than one major version is in production at the same time, the master branch follows the highest major version).
Release branches are created from the develop branch to stabilize and release a minor version (the branch is named according to the minor release, e.g. release-x.y). Tags are used on the branch to identify the initial and subsequent maintenance releases of a specific minor release (e.g. x.y.0, x.y.1, ...).
Developers create feature branches in their local repositories for development work. If the development is complete, the developer will merge the feature branch into their personal develop branch, and issue a Pull Request to have it merged to the develop branch in the canonical project repository. If the development is not complete, but the developer wants their feature branch included in the canonical project repository for others to readily evaluate and contribute to, they will issue a Pull Request for their personal branch. All feature branches must eventually be merged into the canonical project develop branch before being included in a production release.
The general release process is as follows:
- When the development team considers the develop branch of the canonical repository ready for the next release, a new release branch is created in the repository for the final stabilization work, named according to the intended major and minor release number (e.g., release-1.6). If considerable development is expected, such as in the case of a major release - which could have many stabilizing alpha and beta releases prior to a final production release, a feature branch should be used for gross stabilization first, perhaps even named according to the intended eventual release, e.g. 2.0-alpha (a release branch should include only fine stabilization changes leading to the initial release, followed by any maintenance releases).
- When the development team considers a release branch stable and suitable for release, it is tagged with a release identifier (e.g., 1.4.6, 1.5.0) and officially published.
The following guidelines should be considered during development:
- All changes to the canonical project repository must be initiated via a Pull Request from a personal fork on GitHub, including changes from Project Maintainers. The changes in the Pull Request are reviewed by a project maintainer before being merged into the project repository. If the changes are submitted by a project maintainer, then a different project maintainer should respond to the pull request.
- Before submitting a change, consider whether it is (or will be) of general interest of the community, and serve the "greater good". If the change is specific to your own personal interests, it likely not suitable to be included in the canonical project. However, the advantage of using Git (and GitHub) is that you can still maintain changes for yourself within a Git repository, continuing to merge upstream changes into your personal repository, and still pushing changes of benefit to the community upstream.
- It is preferred to have a bug or defect identified in a GitHub project Issue first, then correct (and close) the issue with a Pull Request, referencing the issue in the commit message and Pull Request. This helps maintain the issue tracker as a useful resource for finding if an issue has been fixed, and also provides an opportunity to discuss the issue, its cause and potential solution, and show who is working on the solution (which avoids multiple people from working on the same issue). If you find a bug and fix it, please consider taking an extra moment to create an issue, then submit your fix.
- Give useful information in Git commits and Pull Requests (meaningful to someone else!). It is obvious from the Git commit history which files have been changed, but it is not obvious why they were changed. The title and description of a Pull Request needs to inform the reader a) why the change was necessary and b) the general scope of the change including the effect on use and future development. If this is difficult to explain because some changes are unrelated to each other, then consider too much is being done in the commit or Pull Request, and the work should be divided into smaller units. Consider that the commit history needs to tell a story that developers who come after you can easily (and correctly) understand.
- Explain new concepts for the benefit of other developers, preferably in advance so that everyone has the opportunity to review, comment and accept the new concepts. There are a number of places where you can do this, including in a commit message, the Pull Request description, in-line code comments, in an Issue, in a forum post, in a wiki page, etc. Consider the best location based on the complexity of the concept, and include references to the explanation in the other sources (e.g. write a forum post and then reference it in the Pull Request description). In general, the more complex the concept the more information should be provided, and the more advance notice should be given.
The ATK Framework, used by Achievo, adheres to the paradigm of Inversion of Control, also called Dependency Injection or the Hollywood Principle. This means that the main application flow is not determined by Achievo, or by you as the developer of an Achievo module, but by ATK itself. To do its work, ATK calls methods in your module classes to get things done. ATK knows when a form needs to be presented, so it calls the module essentially saying "I'm going to present a form; give me the fields you want to have in the form".
You are encouraged to study the code in Achievo and the ATK Framework and become familiar with how these principles are implemented.
We are lazy developers. This means we don't like to write too much code. ATK is completely focused on getting as much done as possible, using as few lines of code as possible. So instead of giving you many objects that can do an enormous amount of things for you, we have a very minimal API that does things that you might expect from a CRUD application, because in the end, most applications work more or less the same. This means that we do not only abstract features, we abstract the whole concept of an application. This is why we can have the slogan 'an application in 10 lines of code'. You only code what makes your app different from other apps. (In other words, you can focus on your business logic). The ATK Framework takes care of all the standard work in an application such as security, form building, session handling, templating...
To be able to minimize code, the ATK Framework adheres to what we call 'assumption driven development'. We assume a lot. We assume that when you build a CRUD application, you want to have a list of records with edit and delete buttons. We assume that if you make a field unique that you'll want to let the user know if he violates this, we'll assume that you'll want a calendar when you edit a date field. Or even for small internal details. Like "I'm assuming that if you want to hide a field for the user, that we can leave it out in the query that retrieves your record".
ATK basically says "look, I'm going to assume you'll want to have things this way; tell me if you want things otherwise". This principle makes for rapid application development with the ATK Framework, if you don't tell ATK to change its assumptions, it will assume things in such a way that it can build an app for you.
ATK provides an enormous amount of that you can implement to change its behaviour. The hooks follow the Hollywood Principle, so if they're not there it's fine, but if they're there, ATK will call your hooks and you'll be able to influence its behaviour. For more information, see the Hooks article in the ibuildings Achievo/ATK wiki for a list of methods that can be used to influence ATK's behavior.
The ATK Framework project follows a typical change management process used by other open source software projects.
Since 2014, Achievo and ATK follow standards of the PHP Framework Interop Group (FIG), thus code must be styled according to PSR-2.
- Code MUST use 4 spaces for indenting, not tabs.
- There MUST NOT be a hard limit on line length; the soft limit MUST be 120 characters; lines SHOULD be 80 characters or less.
- There MUST be one blank line after the `namespace` declaration, and there MUST be one blank line after the block of `use` declarations.
- Opening braces for classes MUST go on the next line, and closing braces MUST go on the next line after the body.
- Opening braces for methods MUST go on the next line, and closing braces MUST go on the next line after the body.
- Visibility MUST be declared on all properties and methods; `abstract` and `final` MUST be declared before the visibility; `static` MUST be declared after the visibility.
- Control structure keywords MUST have one space after them; method and function calls MUST NOT.
- Opening braces for control structures MUST go on the same line, and closing braces MUST go on the next line after the body.
- Opening parentheses for control structures MUST NOT have a space after them, and closing parentheses for control structures MUST NOT have a space before.
use FooInterface;
use BarClass as Bar;
use OtherVendor\OtherPackage\BazClass;
class Foo extends Bar implements FooInterface
{
public function sampleFunction($a, $b = null)
{
if ($a === $b) {
bar();
} elseif ($a > $b) {
$foo->bar($arg1);
} else {
BazClass::bar($arg2, $arg3);
}
}
final public static function bar()
{
// method body
}
}
Achievo and ATK class naming changed in the past. Originally, Achievo followed the 'atkClassName' naming convention. In 2009, iBuildings embarked on integrating ATK with the Zend Framework and followed Zends naming conventions. Since 2014, new development of Achievo and ATK must follow the standards of the PHP Framework Interop Group (FIG), namely PSR-0 and PSR-1 (```ATK\Achievo\ClassName```).
Nodes are considered business entities, and are named using common English words (e.g. ```\ATK\Achievo\Employee```). In the past, they were named using lowercase common English words (e.g. ```employee```).
Achievo and the ATK Framework are extensively self-documentated using PHPDoc-format comments. Many IDEs (Integrated Development Environments), such as NetBeans, Eclipse and PhpStorm, can display PHPDoc-format documentation in convenient "pop-ups" for hinting when coding with ATK Framework API functions, or when searched for directly.
Developers should strive to include documentation in their modules following the examples in Achievo and the ATK Framework. It may help to follow a Requirements Driven Development model, writing the PHPDoc documentation first (the Requirements), and then the code that implements it.
Configuration variables that are not specific to a module are defined in config.inc.php (e.g. database connection, security, etc.).
Module-specific configurations are defined in a configs/modulename.inc.php file (note that if a variable is defined in both a modulename.inc.php and config.inc.php, modulename.inc.php takes precedence). All configuration variables available in a module should be defined in a modulename.inc.php file, and with a complete explanation of both use and behavior.