Difference between revisions of "How to contribute"
(Fix my linking syntax) |
|||
| (10 intermediate revisions by 6 users not shown) | |||
| Line 1: | Line 1: | ||
| + | [[Category:Contribute]] | ||
''Contributing to EPrints development'' | ''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... | + | 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. | 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. | ||
| − | == EPrints Development == | + | == Writing EPrints Code == |
| + | |||
| + | === EPrints Core API === | ||
| + | |||
| + | Documentation describing the EPrints API is available from this Wiki at [[:Category:API|API]]. This is generated from the inline comments in the source code. | ||
| + | |||
| + | === Coding Style === | ||
| + | |||
| + | There is a definite ''style'' that Eprints is written in. Please read the [[StyleGuide]] and follow it. | ||
| + | |||
| + | === IDE-based Development === | ||
| + | |||
| + | [[EclipseEpicPerlDebug|How to set up EPrints in Eclipse using EPIC and the Perl Debugger]] | ||
| + | |||
| + | === Core Committers === | ||
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). | 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). | ||
| Line 16: | Line 31: | ||
WARNING: eprints-changes is HIGH traffic (every ticket and commit gets posted). | 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 [http:// | + | The list of tickets and commits is accessible via the Web on our [https://github.com/eprints/eprints/ Github]. |
| + | |||
| + | == Developer User Group == | ||
| + | |||
| + | A [http://eprintsug.github.io communal development space] has been set up on [https://github.com/eprintsug GitHub] to help facilitate 3rd party contributions to EPrints. Many plugins and Bazaar packages are maintained there ; so keep this option in mind when reading below! | ||
== Write a Plugin == | == Write a Plugin == | ||
| Line 28: | Line 47: | ||
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. | 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 | + | 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? [[BibTeX Extension Example|Look here]]! |
* See also [[Extension Packages]] for how to add configuration and resource files to plugins. | * See also [[Extension Packages]] for how to add configuration and resource files to plugins. | ||
| Line 42: | Line 61: | ||
==== Import Plugin ==== | ==== Import Plugin ==== | ||
| − | These are used to import data into a repository. They can take | + | These are used to import data into a repository. They can take data files 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. | 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. | ||
| Line 90: | Line 109: | ||
== Translate EPrints into your language == | == 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 | + | A number of translations for EPrints v2 exist on http://files.eprints.org/ but these need updating for EPrints 3. |
===How to add your Translation=== | ===How to add your Translation=== | ||
| − | If you have translated | + | 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. | You may also wish to add a README file adding additional details such as which files (if not all) were translated. | ||
| Line 108: | Line 127: | ||
== Report bugs == | == Report bugs == | ||
| − | Oddly, we do like to hear about our mistakes. If you think you've found a bug then email | + | Oddly, we do like to hear about our mistakes. If you think you've found a bug then email the eprints-tech mailing list. |
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! | 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! | ||
| Line 114: | Line 133: | ||
== Write How-to's == | == Write How-to's == | ||
| − | * Done something new or | + | * Done something new or unusual with EPrints? |
* Installed it on a new platform or in an unusual way? | * 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? | * Got annoyed figuring out how to do something, and wished there was a how-to? | ||
| − | Add a [[ | + | Add a [[:Category:Howto|Howto]] to this wiki! It doesn't need to spend hours working on perfect layout and grammar (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! == | == Hire EPrints Services! == | ||
Latest revision as of 01:37, 23 August 2018
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
Writing EPrints Code
EPrints Core API
Documentation describing the EPrints API is available from this Wiki at API. This is generated from the inline comments in the source code.
Coding Style
There is a definite style that Eprints is written in. Please read the StyleGuide and follow it.
IDE-based Development
How to set up EPrints in Eclipse using EPIC and the Perl Debugger
Core Committers
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 Github.
Developer User Group
A communal development space has been set up on GitHub to help facilitate 3rd party contributions to EPrints. Many plugins and Bazaar packages are maintained there ; so keep this option in mind when reading below!
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 data files 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.
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 the eprints-tech mailing list.
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 unusual 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 Howto to this wiki! It doesn't need to spend hours working on perfect layout and grammar (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!
