A proposal to establish base guidelines on the codebase that would constitute TikiCore. This proposal is still in early stages and comments are welcome.
Background
The current code base does not provide a sufficient confidence level. The design behind most of the current libraries renders them difficult to test in automated test suites. As a result, many functionalities are brittle and can only be maintained by a few core developers. Libraries have overgrown and no longer have a central purpose.
The idea of beginning a new set of libraries with well defined responsibilities was proposed in TikiFestStrasbourg and agreed on by the present participants. This proposal is a formalized version of the initial proposal. It aims to get wider community acceptance and define guidelines that will drive development.
What is TikiCore
TikiCore will be a long-term effort to improve the backend of Tikiwiki. On the long run, it will contain fully tested libraries of all the central functionalities of the project.
Early candidates are:
- Permission management
- TikiObject data management layer
Process
Beyond obtaining clean code, the purpose of TikiCore is to improve communication among developers in large development efforts. In this sense, TikiCore defines a process to accept and incorporate new components, and changes to components.
- Write a proposal
- Obtain acceptance from peers
- Develop the proposal in a public experimental branch
- Submit branch for acceptance
Write a proposal
Writing the proposal will ensure that the ideas and objectives are clear and structured. It will avoid drastic design changes from being made during the development. It will allow other developers to propose improvements and obtain a better final result.
Ideally, the proposal should contain code samples demonstrating how the component will be used and diagrams or interfaces explaining how it will be implemented.
Proposal authors are expected to take active part in the development effort. Proposals must contain commitments by individuals to accomplish the task.
Obtain acceptance from peers
Before development goes too far, it is mandatory that the proposal be accepted by the community. TikiCore will only accept changes that are desired by the community. A rejected proposal can still be implemented in Tikiwiki, only it will not be part of the core.
To be accepted, the proposal must have a clear scope. All pending questions and suggestions must be answered. Quality attributes like security, performance and scalability will be part of the evaluation.
Everyone is allowed to comment, question and vote on the proposal. However, a group of individuals will take the final pass/fail decision based on the discussions. Until a formal process to select the group of individuals, the administrator group will be in charge of selecting them.
A proposal can be rejected for two distinct reasons:
- Component rejection: The proposed component is not desirable in TikiCore. It could be because of conflicting developments or issues that need to be clarified. The proposal would be discarded. However, it may be re-evaluated at a later time.
- Design rejection: The component's design does not suit the standards or does not cover all use cases. Design rejections must be accompanied by constructive comments as the component is desired.
Develop the proposal in a public experimental branch
No changes will be accepted directly on the development branch. Before being added, the code will need to be reviewed to make sure it respects the accepted proposal and the conventions.
The branch must be part of the Tikiwiki source code repository to be publicly visible. Commit early, commit often still applies. It will allow the community to review the development, to correct the course and to participate.
Submit the branch for acceptance
Before being accepted in the trunk, the code will need to pass a final review. The following items will be verified:
- Conformance to the proposal
- Conformance to the coding standard
- Code quality
- Code documentation
- Unit testing coverage
Code quality includes security, performance, readability, presence of hacks, etc. A list of guidelines should be created as components are reviewed.
Tool support
- A wiki-plugin to keep track of acceptance may be used.
- PHPUnit will be used as the unit testing framework
- PHPDocumentor will be used as the documentation generator/standard
- Various scripts to handle branches are available:
- doc/devtools/svnbranch.php to create a new experimental branch
- doc/devtools/svnbranchupdate.php to synchronize the experimental branch from trunk
- doc/devtools/svnbranchreview.php to review all changes made in the branch
- doc/devtools/svnmerge.php to incorporate the branch changes
Standards
- Coding standards for TikiCore must be defined. As a basis of discussion, the Zend Framework Coding Standard for PHP should be used.
- While TikiCore is built to be independant from the output, some components specialized in formatting may be included. In the case of HTML output, the portion generated should be XHTML 1.0 Strict compliant.
Known exceptions:
- Indentation using tabs rather than spaces
- Code alignment with spaces
Commitments
Who | What | When |
lphuberdeau | Set-up the environment for unit testing and documentation generation. | upon acceptace |
missing, from admin group | Define the list of individuals who will take the final decisions on proposal acceptance. | |
missing | Review the Zend Framework coding standards and create the TikiCore standard. |