-
Notifications
You must be signed in to change notification settings - Fork 0
Development Philosophy
This section outlines the general development philosophies that we use in order to ensure that code in the Islandora repositories meets our standards. Having this in black and white allows us to point new developers in the right direction when they start on the project.
The source code will be written to conform with Drupal coding standards, so that we can host on Drupal.org in the future, and to allow others to work on the project easily. All of the PHP code should conform to the coding standards available here http://drupal.org/coding-standards. Drupal development has a reasonably well defined set of coding standards available that are designed mostly to ensure consistency without being overly onerous on developers. The Drupal coding standards are, in turn, based on the PEAR coding standards (http://pear.php.net/manual/en/standards.php). When doing development, Drupal coding standards should be used as a primary reference, with the PEAR coding standards used in cases of ambiguity.
We will use test driven design to create new parts of the framework going forward. This will be supported by a Continuous Integration development style. We use Hudson as our continuous integration server. This server is hosted by WHO. This test server will use automated tools in order to ensure that our code conforms with coding standards and all of the relevant test
With respect to automated tools for ensuring conformance to the PHP standard, a number of tools are available in addition to CodeSniffer, including Coder (http://drupal.org/project/coder) which is mentioned in the Drupal standards document. The Coder module is a combination of two modules: Coder Review for aiding in code review (cleverly enough) and Coder Upgrade to manipulate existing code into standards conformant code. Some brief documentation on Coder exists at http://drupal.org/node/144172.
There are two types of comments: in-line and headers. In-line comments are comments that are within functions. In Islandora, documentation headers on functions, classes, constants, etc. are specially-formatted comments used to build the API and developer documentation. The system for extracting documentation from the header comments uses the Doxygen generation system, and since the documentation is extracted directly from the sources, it is much easier to keep the documentation consistent with the source code.
There is an excellent Doxygen manual at the Doxygen site. This page describes the Islandora implementation of Doxygen, and our standards for both in-line and header comments. The Islandora Github wikipages have a current list of coding standards. This page can be found here https://github.com/Islandora/islandora/wiki/Coding-Standards.
Islandora needs to have a standard error handling protocol. This will allow us to have reasonable behaviour in the case where an error occurs when things are being ingested, the repository goes down, or a groundhog severs the fiber line in New York, bringing down the connection to the remote fedora server based in the cloud. Things happen in the real world that don’t meet our expectations and these need to be handled appropriately.
There are two levels for error handling: 1) error handling in the API layers and 2) error handling in the user facing software. Errors should generate exceptions. Each layer of the API will define its own exceptions. It should be treated as an error for a exception from a lower layer to bubble up, they should be handled, or chained together so that it makes the exceptions easy to catch at higher layers. Exceptions that make it to user facing display code, should display and/or log an appropriate error message, and take any appropriate action. It should be treated like an error to let exceptions go uncaught, causing PHP whitescreens for the end user.
Dependency Injection is a design pattern that help to improve testability and maintainability. The pattern separates the modules interface from the implementations allowing the implementation to be easily swapped.
The interface and implementation details are separate classes allowing the implementations to be injected at runtime. This allows us to pick the best solutions or create new solutions for the current situation. Islandora will use constructor injection meaning that on the creation of an interface an implementation will also need to be created and passed in. This allows us to do all sorts of interesting things, like making sure the correct implementation for the Fedora RAW Api is used depending on the Fedora version, or let programmers request certain versions of the API.
The API design for Islandora has been created in a layered fashion, this allows each layer not to care about the concrete implementations above or below it. It is very important that we keep this data encapsulation in mind when designing software around the Islandora API.
The API is designed so that Drupal sits at a fairly high level in the API, this was done on purpose so that we can replace drupal with other implementations of our front end in the future. This was also done with the idea of being able to call the Islandora APIs from backend services using CLI PHP without having to bootstrap a Drupal install using Drush.
This is a very important part of the Islandora API design philosophy and should be referenced anytime that changes are being made to the API. The specific design of the layered API that we are creating is described farther in this document.
The design laid out in this series of design documents is bound to be wrong. There is nothing we can do about it, some ground shattering new technology will be released tomorrow that we will need to use to stay competitive. This isn’t defeatism, its the truth. The only thing that we can do is design the best we can for today, and try to future-proof the design as much as possible. To this end we need to version as many components as possible, this will make the best of a painful situation when core components need to change in the future.
All APIs that are created for Islandora should be versioned. Many API changes can be made by adding new methods or properties, or adding arguments, but the day will come when we realize that an API needs to be rewritten. When this happens, and it should happen as rarely as possible so as the project moves forward and everyone realizes that I was dumb when I wrote something in this document, we can expose new functionality through a new version of an API.
Modules can request which version of the API they would like, allowing us to make a potentially breaking change, and then move modules slowly over to the new API. The old APIs will be deprecated after a certain amount of time, a policy we will likely have to address when it happens. The time may be when we do another major version change.
All of the XML datastreams that are used in Islandora NEED to be versioned. This will allow us to do several things: Create XML datastream parsers/generators that are injected depending on the proper version of the datastream, so we can support old formats without needing strict migrations with every version. Allow us to create class hierarchies to achieve the above. Where we cannot easily continue to support old version this allows migration to be done, either as a batch process or on demand.
The version of the XML configuration file should be stated in the root element as an attribute called version. This number can be a simple integer representing the implementation that should be used.
Modules provide the user interaction layer by combining the lower level APIs.
Application Programming Interfaces is an interface used to communicate with a software component. The features found in the API should be generic and required by multiple projects.
Modules are meant to be used by drupal users. They use the API to accomplish a task and expose features to the users.
All modules should have there own git repository?
APIs should live in Islandora Core?
The version numbers of the Islandora project are managed as such: Drupal6 Drupal7, how do we version non-drupal components.
I was thinking we name them appropriately:
Islandora 11.2.x ( major minor patch ) Drupal 6 Islandora Wrapper x.y.z Drupal 7 Islandora Wrapper x.y.z Wordpress Islandora Wrapper x.y.z REST Islandora Wrapper x.y.z