How to contribute
Contributing to EPrints development
There's a number of different ways you can contribute to the EPrints project. This page covers all the ones we can think of...
Always make an entry on http://files.eprints.org/ for your contribution, even if you don't upload the files. This will make it the one-stop shop for people to find EPrints extensions.
Contents
EPrints Development
We run two mailing lists for committers: eprints-devel and eprints-changes. To receive changes to our tickets and repository, subscribe to eprints-changes (read only). eprint-devel is a lower-traffic discussion of commits (questions will probably be ignored - use ep-tech instead).
To subscribe to the lists, send a mail with one of the following lines in the message body to majordomo@ecs.soton.ac.uk
subscribe eprints-devel subscribe eprints-changes
WARNING: eprints-changes is HIGH traffic (every ticket and commit gets posted).
The list of tickets and commits is accessible via the Web on our EPrints Trac.
Coding Style
There is a definite style that eprints is written in. Please read the StyleGuide and follow it.
Development Environment
How to set up EPrints in Eclipse using EPIC and the Perl Debugger
Write a Plugin
The plugin system for EPrints 3 has been developed to make it easy and share the most common extensions to the code without having to hack the core system (and causing yourself problems with upgrades etc.)
When the system loads, it automatically loads all modules in the perl_lib/EPrints/Plugin/ directory, so for simple plugins you just drop them in that directory and you're done!
When a plugin is loaded it has a registration method which is called which tells the core EPrints system what this plugin does. EPrints then makes it available as appropriate.
Clever plugins can detect features they need and adapt to use the tools available, or disable themselves if they are missing required tools (rather than crash the system). Some specialised plugins are disabled in their default state and must be enabled in the repository configuration.
Another cool thing is that plugins are Perl Objects, which means you can subclass them. Here's an real-world example: We have a research group which uses BibTeX but over the years standardised within the group on an extra field. This is not a valid bibtex field, but are essential to their working because they have ancient and essential scripts which depend on it. To handle this we can subclass the default BibTeX Export plugin and override a single method (the data mapping one). We then just call the original parent plugins mapping method to do all the heavy lifting, then just add our non-standard extra field. Total code required: less than one screen. Number of happy researchers: none (they are never satisfied and will just demand the moon on the stick because you've already given them this nice new feature), but number of researchers able to get their work done: lots. Don't believe me? look here!
- See also Extension Packages for how to add configuration and resource files to plugins.
Types of Plugin
There are a number of different kinds of plugin for EPrints...
Export Plugin
These are used to export the data in a variety of formats. They are quite easy to write, once you get started.
Import Plugin
These are used to import data into a repository. They can take datafiles directly, or they can take an ID of a record that can be retrieved in a known way, or a URL of a file, or... whatever.
These are a bit trickier to write than export plugins as parsing data is harder than just "print"ing it, but they are still reasonably straight forward.
Screen Plugin
These handle (almost) all the user interface screens. Pages like "Review" and "Profile" are just built-in plugins. You can add your own very easily.
Examples you could create...
- Birds Eye View - a view of various statistics on the database, all in one page.
- Spellchecking Tab - an additional tab in the item control page which checks the spelling on certain fields.
- Bulk Delete tool - a tool which takes a list of eprintid's and deletes them all in a fell swoop.
Look at the existing Screen Plugins for an idea of how they work. They can be very simple.
Input Component Plugin
These handle how the workflow components are rendered. Built in components include the default (one field) component, the multiple fields component, the upload component, the subject component (which does pretty things to a field of type "subject") and the XHTML component. You can add your own or sub-class existing ones.
Convert Plugin
These are used for two things, currently.
- Converting the full text of documents into utf-8 text for search indexing
- Converting images and pdfs into thumbnails and previews
Some examples you could create:
- RTF to utf-8 to allow rich text documents to be indexed.
- Powerpoint to Thumbnail to allow thumbnail and previews of powerpoint slides
- Video to Thumbnail/Preview to make a still preview of a video file.
Write an Autocompleter script or data file
If you created a useful data file for autocompletion, or even a new script!, other may gain from using it. They'll get ideas from just knowing it exists!
- See Autocompletion
Write a Script
There are any number of useful command-line and cgi-scripts which could be written using the EPrints API.
Write a new Theme
EPrints supports "themes" for the basic layout. Creating a few variations will make the software more friendly to people using it for demos and provide some alternate starting points for peoples look and feel.
Translate EPrints into your language
A number of translations for EPrints v2 exist on http://files.eprints.org/ but these need updating for EPrints 3. Contact cjg@ecs.soton.ac.uk for advice on how to cut some corners (a good number of phrases remain unchanged from EPrints 2 so that should reduce effort. Contact us if you want a copy of the EPrints 3 phrases with as many as possible pre-translated using EPrints 2 data.
How to add your Translation
If you have translated eprints into a new language please package up the translated files with a file containing the GPL license called COPYING, and a file called COPYRIGHT which describes who owns the copyright of the translation (this may be important if we choose to package translations in the core, later).
You may also wish to add a README file adding additional details such as which files (if not all) were translated.
These files (just those you have translated, not all!) should be stored in a .tgz archive, with a name in this format:
eprints-2.3.4-translation-fr.tgz
To add the file, register on the EPrints Files repository - EPrints users should already know the rest!
Other neighbourly things to do
Report bugs
Oddly, we do like to hear about our mistakes. If you think you've found a bug then email either the eprints-tech mailing list or Chris directly at cjg@ecs.soton.ac.uk (send to the list if you feel it's useful for other people to know about it and discuss it).
Send all the information you have- what version of EPrints and instructions of how to recreate the problem. If you've figured it out, tell us how to fix it too!
Write How-to's
- Done something new or unsual with EPrints?
- Installed it on a new platform or in an unusual way?
- Got annoyed figuring out how to do something, and wished there was a how-to?
Add a How-to to this wiki! It doesn't need to spend hours working on perfect layout and grammer (we can always fix that later). Put up useful information and step-by-step guides which you feel will help the next guy (or gal).
Hire EPrints Services!
We partly fund the development and support of the software through EPrints Services which may be hired for custom configurations, hosting and creating new features (such as those described on this page).
While EPrints will remain free software, we understand that different groups work in different ways. It's more economical for some to get us to add a new plugin or feature than to build it themselves. If so, great! Get in touch. Hiring EPrints Services benefits you, us (of course) and the entire community by supporting the project!
