View source for YAML Specification for EPrints Ingredients

{{Template: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 [[EPrints Ingredients|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 [[EPrints Flavours|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 <code>ingredient:richtext</code>.

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

=== type ===
The type of component.  Although this will likely be captured in the prefix of the '''id''', this should be explicitly specified as either <code>ingredient</code>, <code>flavour</code>. <code>core</code> or <code>other</code>.  <code>core</code> represents the core codebase and is used in EPrints 3.5's <code>lib/component.yml</code>.  <code>other</code> 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 <code>component.yml</code> files and the '''includes''' attribute of an archive's <code>cfg/package.yml</code> 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 <code>&lt;</code>, <code>&lt;=</code>, <code>=</code> <code>&gt;=</code>, <code>&gt;</code> and <code>~</code>, to represent less than, less than or equal to, equal to, greater than or equal to, greater than or same version family.  When using <code>~</code>, if the version needs to be some version of 2, then specifying <code>~ 2</code> 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"
 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"