The Scientific Web Applications group of the American Museum of Natural History develops web-based applications for the Science Divisions at the Museum. It is also partly responsible for running the webservers that host most of the Museum's scientific websites. It acts in this capacity as a resource for all of the Science departments as a group.
This document concerns those website development projects that are hosted on the Research webservers (and which rely on the services of the Scientific Web Applications group for application environment support) but which are developed either internally within the departments, or externally by independent contractors.
Projects that are hosted on the AMNH Research webservers, even when their software development work is to be performed by outside contractors, need to be discussed at the earliest possible phase of conception, in a meeting with the Scientific Web Applications Group and Robert Duffy, the AMNH Webmaster. For initiating work, please have in hand, or be willing to discuss, a plan that covers all of the points mentioned below in this document.
The Scientific Web Applications Group will manage the software development tasks of any outside contractors who develop work that runs on the Research webserver, in conjunction with the input of the project's contact personnel for matters of needs- and quality-assessment. The SWA Group will vet the contractor's code and will receive and install updates from the contractor, discussed in more detail below.
A written statement of mutual understanding will be made, between the Science department client, the outside contractor, the Scientific Web Applications Group, and Linda Perry-Lube. The document will contain a scope of work and a schedule of deliverables (see also the "roadmap" discussed elsewhere in this document).
Software and webserver platform: We support PHP, MySQL, and Apache. Use standard, well-supported libraries, classes, etc. (E.g. PEAR). No prerequisites on alpha-level code, or code that the Scientific Web Applications group deems is not actively and well-supported. We do not support proprietary application platforms, such as ColdFusion.
Developer access (accounts, servers): We will decide whether the contractor really needs remote access. We maintain a Subversion repository, which is a superior means of delivering and organizing code updates.
Disk space: Please ascertain, at the earliest possible stage of project planning, how much disk space you will need. Our ability to support your project depends on the ability of our servers to meet its storage needs.
A detailed scope of work needs to be cleared with the Scientific Web Applications group and Linda Perry-Lube, even if all of the work is going to be done by the contractor.
Enumerate the desired features of the application in as much detail as possible. Give examples. Provide a roadmap, detailing the versions or stages of the project.
Timeframe: Are there reporting deadlines? Can the project roadmap satisfy these deadlines?
Responsibilities: There needs to be a detailed list of all of the parties involved in the project (the contractor, the departmental client, and the people in the Scientific Web Applications group). There must be a contact chain, detailing who contacts whom for technical inquiries, quality-assurance testing, and so on.
Before work begins on the project, we will produce a written document (an email will suffice) that notes our understandings of the topics enumerated above.
Coding standards: The Scientific Web Applications group will provide coding standards for the developer to follow. This is partly because of the possibility of the group having to maintain or configure the code to some degree in the future. Code must be commented, down to at least the level of variables and function declarations. For PHP, use the PEAR coding standards for formatting your code.
Change management: Our Subversion revision control system must be used for code developed on projects hosted on our servers. Developers must log comments for commits.
Developers must contact us to get started with a Subversion account on our SVN server. We will provide them with a repository to use for their project. We will also provide more detailed help and guidelines on using the repository specific to their project.
More information on Subversion and SCM in general:
Portability: Please write your application to be portable, even if you think it will only reside in one place on the webserver. We need for it to be installable on a testing / staging server in addition to its final destination. We also need to be able to change its location in the future with a minimum of fuss. Therefore, there should be no hardcoded values that refer to filesystem locations, URLs, and so on. Please put configuration variables into separate configuration files, and make sure that these files can not be read by anonymous website users. Do not check configuration files with customized settings into the Subversion repository. Instead, make default configuration files with endings like ".dist" and check these in, instead. Make it so that the person installing your application needs to rename the ".dist" file to ".conf" (or whatever) and so that someone updating a working copy of the application will not overwrite the custom settings that they have put in the config file. We should be able to install your web application on our server by making customizations limited to your configuration files, and, perhaps, our Apache configuration. We should not have to modify your PHP code.
Documentation: User-level documentation is important, as is also documentation for the system administrators who have to install it and keep it running. Include instructions on how the software is configured to run on the server, the locations of configuration files, and so on. Documentation must be specific down to the following details:
Documentation as described above is a requirement for the Scientific Web Applications Group to accept the role of supporting your application!