General Requirements

ⓕ A FIWARE GE MUST fit well in the architecture of a “Powered by FIWARE” solution:

  • Integrate well with architectures where context management is cornerstone and addressed using FIWARE NGSI (currently FIWARE NGSIv2, compliant with ETSI NGSI-LD in the future).
  • Be able to fit within one of the defined FIWARE chapters.

Licensing and IPR Management

ⓒ The source code of the product MUST be licensed under one of the well-recognized open source licenses approved by the Open Source Initiative.

ⓒ The open source license under which source code of the product is licensed MUST be clearly mentioned in a first-level section of the README.md file included in the main GitHub repository.

ⓕ When using a copyleft open source license, the following explanatory paragraph of legal opinion MUST be added in the section where the open source license is mentioned:

Please note that software derived as a result of modifying the source code of the software in order to fix a bug or incorporate enhancements IS considered a derivative work of the product. Software that merely uses or aggregates (i.e. links to) an otherwise unmodified version of existing software IS NOT considered a derivative work.

The legal opinion paragraph above is aimed at giving users confidence they can use FIWARE components even if they have been licensed under a copyleft license without this requiring that their applications have to be released as open source. Incorporation of this paragraph is valid for this purpose as per the report produced by Across Legal/ID law partners (see summary report).

ⓕ The legal opinion paragraph above SHOULD be accompanying the text describing the adopted open source license in the headers of all source code files for the product.

ⓒ Every enabler MUST be open to third party contributions. All offered contributions MUST be reviewed within a "reasonable" timeframe.

ⓒ There MUST be a document (CONTRIBUTING.md guidelines) clearly describing the terms under which the IPR of contributions to the source code of the product will be managed. Such document MUST be made accessible in (or map to) a first-level section of the README.md file included in the associated GitHub repositories.

ⓕ The CONTRIBUTING.md guidelines MUST include the template of the Contribution License Agreement for individuals and entities contributing code to the component. As a reference for producing these templates, the following templates derived from the Harmony Agreements project are provided:

In any case the provided templates MUST align with clauses 2.1, 2.2 and 2.3 of the recommended templates above.

ⓕ When using a copyleft open source license, IPR Management rules for contributions MUST include clauses as follows:

  • There should be at least one organization which can exercise IPRs on the whole software.
  • There is a commitment to transfer to the FIWARE Foundation the IPRs on the whole software in case that the software is no longer supported by the organization(s) that currently own(s) IPR on the whole software.

SCM Tool

ⓒ The SCM Tool MUST be GitHub. Accompanying tools or plugins that integrate well with GitHub (ex. Gerrit) MAY be used.

ⓒ GitHub MUST be used during the whole development lifecycle. See Development Lifecycle Recommendations in FIWARE which describes a set of best practices for collaborative open source development.

Additionally, refer to the checklist for publishing FIWARE Generic Enablers for a list of onboarding tasks to be completed in order to publish a new GE.

README.md

ⓒ A README.md MUST be always present in the root folder of any repository associated to the Generic Enabler. The purpose of such a document associated to a Generic Enabler is to document:

  • Generic Enabler overall description.
  • How to Deploy the Generic Enabler (basic/default installation procedure).
  • How to run tests.
  • A walkthrough guide on using the main APIs.
  • How to get access to the advanced API and Documentation topics.

In general the structure of the README.md SHOULD follow a standard format such as standard-readme.

ⓒ The README.md file of the GitHub repository must start by summarizing the usage of the enabler (for example duplicating the elevator pitch).

ⓕ The README.md file MUST include an Introduction/About section at the beginning which includes the following paragraph, introducing FIWARE, clearly showing that the product has been labeled as a FIWARE GE:

This project is part of [FIWARE](https://www.fiware.org/). For more information check the FIWARE Catalogue entry for
[<chapter>](https://github.com/Fiware/catalogue/tree/master/<chapter>).

General

ⓕ The README.md file MUST include the Project Badges which are stated as mandatory.

ⓒ Links to proper places on the FIWARE site (or related repositories) where planned roadmap of the product with respect to future releases of FIWARE is described (see sections on Releases and Roadmap below).

ⓕ More specifically, the referred README.md SHOULD follow standard-readme and include:

  • ⓒ Simple Generic Enabler/Service Description and purpose:

    • The first paragraph SHOULD be an elevator pitch about the purpose of the repository (since this is displayed on GitHub on mobile).
    • Include direct Read the Docs links to the User Guide, Admin Guide in a subsequent introductory paragraph (to allow users to navigate directly between code and documentation).
    • Include information about testbed environments if available.

  • Then add a Table of Contents to make navigation through the rest of the document easier.

  • ⓒ How to Build & Install:

    • Make your simplest full stack deployment as easy as possible.
    • Include System requirement info: Operative System, CPU/Storage Capacity, ...
    • Include installation support for your dependencies.
    • Provide a “Hello World” example using curl (basic acceptance test).
    • Include troubleshooting information for the whole process.

  • ⓒ API Overview of the main data flow:

    • It is a tutorial, not a reference. It does not need to be exhaustive, it needs to guide the user.
    • Provide always curl examples for this section.

  • ⓒ More API Examples:

    • Just the important bits of your API used in examples.

  • A link to the API Reference Documentation. Open API SHOULD be used.

  • ⓒ How to run tests:

    • End-to-end tests (SHOULD). This will be part of the sanity checks included in the "Installation & Administration Guide", thus a link will be needed.
    • Unit tests (SHOULD).
    • Performance tests (MAY).

  • List of links to Advanced topics (/doc folder):

    • User & Programmers Manual (MUST).
    • Installation & Administration Guide (MUST).
    • Other documents, for instance: high availability deployment, detailed architecture, advanced configuration topics, advanced functionalities, ...

Quality Assurance

ⓕ a section within the README SHOULD display the GE ratings defined in the template.

Tutorials/Training

ⓕ GE's repository README.md file MUST include a linkbox of relevant training courses:

As an example, in Markdown adding links to learning materials as shown:

| [Documentation] | [Academy] | ...etc |

Functional Testing

ⓒ A FIWARE Generic Enabler MUST include a suite of functional tests that allow to verify the proper integration with the FIWARE Context Broker GE.

Commitment to Quality

ⓕ The Community behind each FIWARE Generic Enabler (owner, other contributors) SHOULD bring support to requests submitted through standard FIWARE Help Desk channel and QA testings executed by QA Lab team.

The following assessments will be conducted:

  • Assessment on support, to be performed by automated monitoring tools defined by the FIWARE Foundation.
  • Assessment on functionality, (software and documentation), non-functional requirements, etc. to be performed by the FIWARE QA Lab team.

Results of these assessments lead to the assignment of a QA label based on FIWARE QA labeling schema. QA labels of a given FIWARE Generic Enabler will always be associated to a minor release of FIWARE. In the event of not meeting the minimal QA requirements:

  • Yellow card reprimand will be issued when overall QA label is B or lower.
  • Red card reprimand when overall QA label is C or lower or keeps being B in two consecutive minor releases of FIWARE.

Software Releases

FIWARE Generic Enabler Owners can release their software at their own release schedule:

ⓒ The codebase MUST be tagged with a semantic release number.

ⓒ Every release MUST have a unique version number.

ⓒ Every FIWARE Generic Enabler release MUST have an associated Release Notes entry at the GitHub Releases section.

As an example see the following release note.

FIWARE Catalogue Releases

Periodically the FIWARE Foundation will annouce a catalogue release, every time there is a FIWARE Release:

ⓕ FIWARE Generic Enabler owners MUST tag the FIWARE Generic Enabler release pertaining to such FIWARE Release with FIWARE_<major>.<minor>. Please note that this imply that certain FIWARE Generic Enabler releases could be double tagged. The referred tag will be intended to mark clearly that such FIWARE Generic Enabler Release is part of and compatible with the corresponding FIWARE Release. Docker images or other associated artefacts MUST also be properly tagged with the referred FIWARE tag.

"Compatibility" with a release means compatibility with the FIWARE Context Broker in that release, i.e. the FIWARE Generic Enabler owner commits to do the relevant functional and integration testing. This also implies that breaking changes within the FIWARE Context Broker should be scheduled and announced beforehand (i.e. roadmapped) to give FIWARE Generic Enablers a chance to catch up.

A "FIWARE Release" shall contain versioned releases of all FIWARE Generic Enablers found within the catalogue. All FIWARE Generic Enablers pertaining to a FIWARE Release must work seamlessly with the version of the FIWARE Orion Context Broker corresponding to that FIWARE Release. In case of ETSI NGSI-LD support, these FIWARE Generic Enablers must work seamlessly with the version of FIWARE Scorpio, FIWARE Orion-LD, and/or FIWARE Incubated Stellio.

The following rules apply for numbering FIWARE Releases:

  • Major release number: to be increased by decision at TSC level, typically linked with a major achievement (e.g., support to NGSI-LD).
  • Minor release number: to be incremented with relevant milestones agreed at TSC level. Milestones will be usually aligned with the celebration of FIWARE Summits. Additional releases can be added if strictly needed and agreed at TSC level.

Project Roadmap

ⓒ A FIWARE Generic Enabler MUST describe its planned roadmap. A link to the roadmap MUST be found in the README.md.

ⓕ For describing a FIWARE Generic Enabler roadmap the following template MUST be used: GE_roadmap_template.md.

ⓕ Representatives of the FIWARE Generic Enabler community MUST attend F2F roadmap meetings to take place at FIWARE Summits (not overlapping with agenda, day or day and a half before the Summit or after the Congress part).

The page on the FIWARE site in which it is described the overall work is the FIWARE Roadmap.