Developing for Evergreen can be a challenge for those new to it. Each piece of Evergreen requires different skills, and many things will require multiple parts of the system be modified.
A basic overview of the system shows three distinct areas that one would develop in:
See also the Evergreen Technical Diagram.
Evergreen is built upon the Open Scalable Request Framework, or OpenSRF (pronounced "open surf"). OpenSRF provides communication between various "Applications" and the clients that wish to call them. Each application provides a service, and usually the applications are referred to as services because of this.
OpenSRF currently works by passing JSON messages over XMPP, although in the future that could change. In general the inner workings of OpenSRF are not exposed to clients and services written on top of it, so that the underlying elements can change without having to re-implement the entire system.
A very basic view of how a message passes through the system is as follows:
The Staff Client, OPAC, and some other parts of Evergreen are technically OpenSRF clients. The Staff Client and JSPac talk through the HTTP Translator, and the TPac is a Perl client embedded in the HTTP server.
Perl clients intended for use via HTTP protocols tend to be implemented in the OpenILS::WWW namespace.
In addition, OpenSRF Applications are clients as well, able to make requests to other running applications.
Most OpenSRF development will be in the OpenSRF Application area. Most OpenSRF and Evergreen services are written in Perl, but a few are written in C for performance reasons.
The list below is an overview of each application by the service name it is assigned. Included is the language the application is implemented in and which (if any) of the Public and XML-RPC interfaces it is exposed via. Public exposed services are available via the HTTP gateways.
Evergreen uses PostgreSQL as a storage backend and makes somewhat heavy use of many PostgreSQL features. PostgreSQL databases are split into schemas, allowing for logical groupings of related information. For configuration recommendations, see Optimizing the performance of your Evergreen server.
In addition to PostgreSQL itself one should also be aware of the Fieldmapper IDL, which is one of the ways Evergreen is told how to interact with the database.
Many of the schemas are obviously named, and as such do not need much description. Others cover things that are more abstract. Below is a list of all schemas currently used by Evergreen.
Fieldmapper maps database fields to Evergreen objects.
The Fieldmapper IDL, or just IDL for short, is the Fieldmapper configuration file (fm_IDL.xml) which tells Evergreen about all of the important aspects of the database. It is comprised of a set of class nodes, each of which contains at minimum a list of fields. In addition, each class may contain links, permissions, and in the case of fully virtual classes a block of SQL that defines the data to be retrieved.
An important note: For the most part, clients and services can only talk to database elements that are defined within the IDL. The notable exception is stored procedures, which are not listed in the IDL.
One of the benefits of using Fieldmapper is that it generates object code for each of the objects defined in the IDL, which allows us to create those objects from within Evergreen and use them to access their respective database tables and views. Also, for classes in the IDL with a controller of "open-ils.cstore", the CStoreEditor creates CRUD methods (to Create, Retrieve, Update, and Delete) and a search method (e.g. $editor->search_biblio_record_entry(), or $editor->update_actor_user()).
TPAC development thus comes in two flavors:
To start with, at this point it is recommended that new features not be developed for the JSPAC unless they involve security or limiting patron actions. Otherwise development should be targeted at TPAC.
Though JSPAC supports multiple skins only one is currently shipped with Evergreen.
The Evergreen browser-based (or "web") staff client is now the main client, and the XUL client will be removed from Evergreen releases as of version 3.2 (expected Fall 2018). Circulation features were released as a preview with Evergreen 2.8(?), and the full browser client was released with Evergreen 3.0 in October 2017. XUL interfaces have been converted to AngularJS, while most Dojo interfaces have been embedded in the web client with hopes to convert them to AngularJS eventually. (NOTE: We are making plans to upgrade from AngularJS to Angular 5.)
In addition to the core OpenSRF and Evergreen code there are other projects commonly used with Evergreen that may require work for development projects. The most common is currently SIPServer, which provides a SIP2 interface for Evergreen that can be used with Self Check units, Automated Materials Handlers, PC Reservation systems, and some third party services for authentication.
SIPServer is maintained as a separate project, is written in Perl, and interacts with Evergreen through the OpenILS::SIP Perl package.
In addition to the information listed in the contributing document at http://evergreen-ils.org/dokuwiki/doku.php?id=contributing there are a number of things to consider.
First and foremost, stay visible and communicate so that others watching your work know you are making progress. If you don't, and are hard to contact, your project may be deemed "abandoned" and someone else may jump in. This is not only potentially frustrating for you if they release their code first, but to them if you suddenly "return" with your work. Either way someone has likely wasted effort that could have gone to other tasks.
As part of that, if you are having issues ask questions, be it on IRC or via the mailing lists. IRC is most useful during the day in the United States/Canada Eastern Time Zone (GMT-5, or -4 during DST), but the mailing lists are usable anytime (though can be slow to get responses).
If you have opened a Launchpad bug keep it up to date. In addition, excepting security issues, you should prefer the public channels over direct communication with individuals. Not only does that ensure that others know you are still there and working on the issue, but you also get the benefit of the community's knowledge (and contribute to it via archives).
As a note on communication via Launchpad, when responding to things on Launchpad via email sometimes Launchpad "eats" messages, grabbing the wrong part of the message for one reason or another, usually signature-related. Thus it is recommended that you double-check your first few email responses to ensure that they made it through to the bug in question.