Development Guidelines
Preferred development practices are documented here for consistency.
When developing a new feature, consider whether it will likely serve the "greater good" of the Maestro community. If the feature is specific to your needs but not likely those of others, merging it into the project repository may not be appropriate.
- Share your intentions with the community at a preliminary stage, and be prepared to accept that your idea may need refinement, or may not even be in the best interests of the Maestro project.
- Structure Commits and Pull Requests to tell a natural and useful story to other developers.
Before starting development on a new feature development or fixing a bug, check to see if a related issue already exists in the Maestro issue tracker, and if not, create one and assign it to yourself. This allows the project team to easily understand who is working on what.
All changes to the project repository must be initiated using a Pull Request from a fork on GitHub, referencing the associated issue in the commit message and Pull Request.
Pull Requests are reviewed by a project maintainer before being merged into the project repository.
The following is paraphrased from a forum post by Qiang Xue (creator of Yii), which helps explain Yii's coding style.
In general, be frugal writing code, no spacing around brackets and operators, no extra brackets enclosing single if-statements, and use tabs instead of spaces for indentation (with a tab set to 4 spaces). Yii doesn't add spaces around brackets and operators because it requires more typing (about 20% more), and it makes code less consistent because people sometimes omit spaces in some places - which makes global searching a pain..
For more specific information, refer to:
- Yii Core Framework Coding Style.
- The Definitive Guide to Yii - Conventions (also included with Yii framework distribution).
Basically 4 spaces per indent, and replace spaces with tabs. Use Unix-style EOL for all text files, unless the file is generated by a Windows application (e.g. a CSV file exported from Excel).
The tab-vs-space rule has changed over time. Originally spaces were preferred, but Gii now generates code using tabs and the GitHub Yii Coding Style also indicates tabs.
Maestro (and the Yii framework) are extensively self-documented using PHPDoc-format comments. Many IDEs (e.g. NetBeans) conveniently display PHPDoc-format documentation in pop-up for hinting when coding.
Strive to include documentation in your code that follows the examples in Maestro and the Yii framework. Some developers write PHPDoc documentation first, following a type of Requirements Driven Development.
Single line comments shall use "//" syntax.
//this is the correct syntax for a single-line comment
The basic development process is:
- Fork the maestro project repo to your GitHub account
- Clone your fork to your development system
- Push local changes to your fork
- Send a Pull Request from your fork to the maestro project
All development is currently done in the master branch of the project repository. The procedure described below will be adopted after the Maestro project has matured further.
The Maestro project follows the Gitflow model, and uses the following standard branches:
- master - always the most recent minor-version release (if more than one major version is in active development at the same time, the master branch follows the highest major version).
- develop - stable code intended for the "next" release.
- release-xxx - for pre-release stabilization.
- ad hoc topic - for specific feature development outside of the develop branch when appropriate.
Create feature branches in your local repository for development work. When development is complete, merge the local feature branch into your 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.
When a fork is cloned, a default remote called origin is created that points to the fork on GitHub, which is not the master maestro repo. To keep track of the original repository, add a remote called "upstream" to your local clone repo.
$ cd maestro $ git remote add upstream https://github.com/dalers/maestro.git $ git fetch upstream
For more information, see Fork A Repo on GitHub.
The commit message should be no more than 60 characters, or start with a summary line of no more than 60 characters, followed by additional detail as needed on a new line (many Git-related tools show only the first line of the commit message, and limit the length shown).
It is important to periodically pull from "origin" (the official Maestro project repo) and merge any new changes in the project repo into your local project. After merging, pay particular attention to testing the merged code in light other changes you have made.
When you are satisfied with your local code, push your changes back to your personal fork on GitHub, and then issue a Pull Request in GitHub to have your commit merged into the Maestro repo.
To push code from a Git Bash shell to your personal fork:
# cd /c/xampp/htdocs/maestro # git push
Push commits
To push commits made in your cloned fork to your fork on GitHub:
$ git push origin master # Pushes commits to your remote repository stored on GitHub
Pull in upstream changes
Add changes from the master Maestro repo to your cloned fork:
$ git fetch upstream # Fetches any new changes from the original repository $ git merge upstream/master # Merges any changes fetched into your working files
"git pull upstream master" will fetch and then merge automatically without review, but can result in conflicts if you're not closely managing changes.
Create branches
Branching allows you to build new features or test out ideas without putting your main project at risk. In git, branch is a sort of bookmark that references the last commit made in the branch. This makes branches very small and easy to work with.
Creates a new branch called "mybranch" and make it the active branch:
$ git checkout -b mybranch
Use git checkout to switch between branches:
$ git checkout master $ git checkout mybranch
To merge the work in the new branch back into the master branch (before, for example, pushing the master branch back to your fork on GitHub), and then delete the new branch:
$ git checkout master $ git merge mybranch $ git branch -d mybranch
Pull Requests
To contribute your work back to the Maestro project, send the GitHub maestrobpm/maestro project a pull request.
A Release is a unique collection of Maestro files, referred to by a unique Version Number (e.g. "The widget feature was added in version 3.1"). The degree of change between one release and another can be inferred by comparing their respective version numbers (e.g. v3.1 compared to v2.4).
Maestro releases follow the Semantic Versioning specification (the Wikipedia Software Versioning article provides a nice review of versioning practices).
When the code in the develop branch is almost ready to be released, a new release branch is created for final stabilization work - named according to the intended major and minor release number (e.g., "release-1.6"). A release branch should include only fine stabilization changes leading to the release, followed by any maintenance releases. If stabilization is expected to require considerable effort, a feature branch should be used first for gross stabilization, named according to the eventual release (e.g. "2.0-alpha").
When the release branch is deemed suitable for release, it is tagged with a release identifier (e.g., "1.4.6") and announced.
This wiki intends to provide well-organized consistent information firstly for Maestro developers, but also Maestro administrators and end users. Articles in this Wiki can be viewed by anyone, and currently any GitHub member can create and edit articles.
Articles should be written assuming a technical audience, one familiar with developing and hosting PHP web applications.
Article formats and syntax should use MediaWiki syntax for consistency (also MediaWiki syntax by default provides a table-of-contents).
Use English only, spelling according to the Standard American spelling, except for proper names and places. Set your spellchecker to US English and use it.
- Use non-English words only when an English equivalent does not exist (and include an English translation in brackets).
- Capitalize acronyms (e.g. PLM), and defined where first used (e.g., "PLM (product lifecycle management) is a key Maestro feature.").
Punctuation within numbers should follow the American standard, with digits in groups of 3 separated by a comma and a period used as a decimal separator (e.g., 10,000.00).
References for provided information should be cited whenever possible, both for reference and to give credit (include the access date for information obtained from the internet).
Start each line of code with a space, and surround with nowiki tags if necessary for correct formatting.
function atkGroupByFilter($name, $groupbystmt, $flags=0)
{
$this->m_groupbystmt = $groupbystmt;
$this->atkFilter($name, $flags);
}
When pasting in example code, be careful NOT to include unintentional HTML formatting tags (e.g. providing syntax color coding, keyword italicization, etc.) because it prevents easy copying of your code. The code should also preferably use spaces (instead of tabs) for indentation. If necessary, paste your example code into a pure text editor first to remove and correct formatting, then copy and paste from the text editor into the article.
Trust and TransparencyTM, MaestroTM, and The ERP for EngineersTM are used under license.