YAML Specification for EPrints Ingredients

Work in Progress
The page is a work in progress.

The YAML specification for EPrints Ingredients is a work in progress. Do not assume the information currently provided below is complete or not subject to change.

For future versions of ingredients for EPrints to better support release numbers, which will be more strictly controlled in EPrints 3.5. A YAML specification for an ingredient has been defined. This specification must be used to create a component.yml file in the top-level directory of each ingredient. The same or very similar YAML specification will also be used for other components that make up an EPrints such as flavours, which will also have component.yml files in their top-level directories. In addition to component.yml files, each repository archive will contain a cfg/package.yml that specifies the components (flavour, ingredients, etc.) it uses.

Specification

id

The unique identifier for the component. This should be made up of two parts, the type of component followed by a descriptive identifier for the component. The latter would typically be the same as the Git repository it comes from. (E.g. the richtext ingredient at https://github.com/eprints/richtext has the id of ingredient:richtext.

name

A short descriptive name for the component. Typically this will be a more human-readable version of the id, (e.g. ingredient:richtext has the name Rich Text Ingredient).

type

The type of component. Although this will likely be captured in the prefix of the id, this should be explicitly specified as either ingredient, flavour. core or other. core represents the core codebase and is used in EPrints 3.5's lib/component.yml. other does not yet have a specific use but is a catch-all for anything that does not fall under one of the other three types.

version

The version of the component. As well as being useful information, the value can be checked against the requirements of other components (e.g. ingredients) and that of the archive (under the requires attribute or component.yml files and the includes attribute of an archive's cfg/package.yml file.

maintainers

Specifies sub-attributes of name and email of all the people or organisations responsible for maintaining the component.

description

A description of the purpose of the component, such as explaining what functionality it provides.

requires

Any dependencies on other components and what particular versions of those components are required. This has two sub attributes component, which is the id of the component required and version that specifies the version required. version has special syntax, such as <, <=, = >=, > and ~, to represent less than, less than or equal to, equal to, greater than or equal to, greater than or same version family. When using ~, if the version needs to be some version of 2, then specifying ~ 2 would cover all versions from 2.0 up to 2.9 or whatever the last version of 2 is, including sub-versions (e.g. 2.3.4 or 2.4.5).

notes

This typically covers basic installation instructions or critical information the installer should be aware.

readme

This should be a URL pointing at a large readme file that provided more comprehensive installation instructions and information. Typically, this might be the readme file in the Git repository.

Example

---
id: "ingredient:richtext"
name: "Rich Text Ingredient"
type: "ingredient"
version: 2.0
maintainers: 
  - name: "A. Developer"
    email: "developer@example.org"
  - name: "A.N. Other"
    email: "another@example.org"
description: "This is an ingredient that provides rich text (i.e. HTML markup) fields for workflows."
requires:
  - component: "core"
    version: ">= 3.5.0"
  - component: "flavour:pub"
    version: ">= 3.5.0"
notes: "This can be installed by dropping into the ingredients sub-directory and adding to your archive's package.yml"
readme: "https://github.com/eprints/richtext/blob/master/README.md"