API Gardening Project

This is the homepage of API cleanup project for 2.3.

Goals

• Tests
• Documentation
• Defining conventions and sticking to them

Project plan

milestone met
work in progress
needs discussion

• CiviCRM 2.3
  1. Add PhpDocumentor and PHPUnit to packages/ in the CiviCRM repository. Adapt existing scripts and configuration files now in the DB Tools package to CiviCRM. Add docs/. tutorials/ and report/ directories to the repository to receive the generated documentation and testing reports.
  2. Begin adding doc comments to API files - Contact, Activity and Constant are chosen for the first run. Publish manual on appropriate style of comments, and how to run the script that generates documentation
  3. Establish the initial package tutorial files and examples of tutorials for phpdoc. Provide guidelines on writing tutorials for the APIs
  4. Establish a framework for API testing with PHPUnit. Write a few example unit tests where the design of CiviCRM makes this feasible, starting with the existing tests written for Simpletest and leveraging the greater capabilities of PHPUnit.

Expressing above in more specific terms:

• documentation in solid state for 3 API groups (Contact, Activity and Constant)
• a collection of good test examples based on 3 mentioned API groups
• live sites with automatically generated API docs and tests results (not sure about code coverage report, but aiming for this as well)

• CiviCRM 2.4
  1. Initiate the practice of using the API documentation and regression tests to assure the stability of the APIs as CiviCRM evolves
  2. Initiate the practice of generating test coverage reports for the APIs (a feature of PHPUnit not available in Simpletest) and studying these reports to judge the effectiveness of testing.
  3. Initiate the practice of designing API modules for testability, with changes suggested by sections of the code that are not test as indicated by the coverage reports.
  4. Establish the practice of including the PhpDocumentor and PHPUnit code in the distributed tarball. Distribute the generated documentation and test reports in the tarball but don't check the generated code into the repository. Encourage users of platforms other than the usual Ubuntu 8.04 to run the tests on their own platform and report the results to the community.

Project check-ins

Every Wednesday at 8:30am MDT (Salt Lake City, US), 7:30am PDT (San Francisco, US), 10:30 EDT (New York, US), 4:30pm CEST (Warsaw, PL) on #civicrm channel on irc.freenode.net