-
Notifications
You must be signed in to change notification settings - Fork 10
Developer Guidelines
The ATK Framework (ATK) community consists of Builders, Developers, and Maintainers.
- A Builder uses the ATK Framework to build an application.
- A Developer contributes to the ATK Framework project. Contributions include new or modified code (e.g. PHP, HTML, CSS, Javascript), images, documentation, tests and test results, issue (bug) reports, new translations or translation corrections, propaganda (marketing) material, and other valuable work.
- A Maintainer is a special type of Developer with write access to the project repository. Maintainers can accept pull requests for changes to merge into a project repository. Maintainers are also the official shepherds of the project, and provide project leadership and cohesive guidance to the community.
A Release is a unique assembly of files identified by the development team. A release is assigned a unique Version Number as a reference, and the degree of change between one release and another can be inferred from their respective version numbers.
A Version Number is a sequence of three numbers separated by periods in the form X.Y.Z, where X is the Major version number, Y is the Minor version number, and Z is the Maintenance version number.
The rules used by the the ATK development team for assigning version numbers are:
- a change in maintenance version (e.g. ATK 6.5.0 to 6.5.1) indicates that only backwards compatible defect corrections have been made. By its definition, a maintenance release can only correct incorrect behavior in existing features, it cannot introduce new features.
- a change in minor version (e.g. ATK 6.5.0 to 6.6.0) indicates that new functionality has been introduced in a public interface that is backwards compatible, or new functionality or improvements have been introduced internally. A minor version change may also include defect corrections.
- a change in major version (e.g. ATK 6.5.0 to 7.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 being introduced are of such significance 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
If not futher clarified, a Release generally refers to a Production release, which means it is considered suitable for general use. A release may also be made in advance of an anticipated production release for testing or evaulation, which is called a pre-release. Pre-releases are not intended for use in production, but if no issues are found the code may be subsequently released essentially unchanged as a production release.
A pre-release version number consists of the version number of the anticipated eventual production release, followed by a pre-release designator and series of dot separated numeric identifiers. THere are three types of pre-releases:
-
Release Candidate. A release candidate is made during the final stabilization process leading to a production release. All features intended for the anticipated production release have been implemented and there are no known significant defects.
- e.g. 6.7-rc.1 (the first release candidate for the 6.7.0 release)
-
Alpha Release. An alpha release provides an opportunity to evaluate potential new features at a very early stage of development.
- e.g. 7.0-alpha.1 (the first alpha release of features intended for the 7.0.0 release)
-
Beta Release. A beta release provides an opportunity to evaulate new features intended for production release, at a preliminary stage of development.
- e.g. 7.0-beta.1 (the first beta release of features intended for 7.0.0)
GitHub "Issues" are for managing bugs and other development tasks (e.g. re-factoring for performance isn't a bug, but it is still an issue). Issues can be assigned to a developer, and all development tasks should be driven from an issue for the visibility of other developers.
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 provided here, but in general it follows the Gitflow model, modified for the Fork and Pull model on GitHub.
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-6.5). 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. 7.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., 6.5.0, 7.0.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.
Achievo and ATK Framework code shall adhere to the following formatting rules:
- code is indented 2 spaces per level
- tab characters are not to be used (set your editor to "Expand Tabs to Spaces")
- parentheses used to delimit a code block are placed as follows:
function atkGroupByFilter($name, $groupbystmt, $flags=0)
{
$this->m_groupbystmt = $groupbystmt;
$this->atkFilter($name, $flags);
}
- if possible, keep lines under 80 characters by wrapping them intelligently.
Achievo and ATK were originally developed using the 'atkClassName' naming convention. In 2009, iBuildings embarked on integrating ATK with the Zend Framework and currently Achievo and ATK follow the Zend Framework naming conventions for classes, except:
- ATK classes follow the 'atkClassName' convention, and
- nodes are considered business entities, and are named using lowercase common English words (e.g., "class employee extends atkMetaNode")
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.
/** * @package atk * @subpackage ... */
Single line comments shall use "//" syntax.
/* this syntax should not be used for a single-line comment */
Although the /* ...*/ comment syntax is valid, it makes it very hard to comment out large lines of code when debugging due to the intended comment block stopping on each comment line (which means either having to comment out small blocks, using die(), or sending the data to error_log() ).
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.