Projects Site Documentation

Introduction

The site projects.ow2.org is used for displaying information about projects as well as their OSCAR dashboard, for submitting new projects and for managing the mature upgrade workflow.

Data model

All XWiki classes used by the site are stored in the ow2 space.

General project classes

Quality assessment classes

In addition, a set of quality assessment classes were added in the frame of the RISCOSS project, in order to compute some maturity level indicators for each project. The computation of these indicators is based on 4 data sources: OMM form, Fossology, SonarQube, OpenHub. The way the data is retrieved from these sources is described in the paragraph "Oscar Scorecard application" below.

Projects home page

Project directory tab

In order to manage the filtering and the display of the projects' table, the data is handled in JavaScript by calling an API endpoint which returns the data in JSON format.

Latest news tab

The news displayed in the "Latest News" tab are gathered from each project "news" attribute. This attribute needs to contain a bullet list of news with the following format: * YYYY/MM/DD - [[Version xyz is out!>>version-xyz-is-out]]. All news are then grouped together and sorted by date in reverse order. The "news" attribute can also be filled in automatically by specifying a news feed URL in the "newsFeed" field of the Project class. The page NewsUpdater is then called daily via a dedicated XWiki scheduler for retrieving the corresponding items and for creating page entries in the projects wiki.

NB: not all project leaders use the news section of the site to actually publish news. A way to retrieve the news about the projects is to use this Twitter list feed: https://twitter.com/ow2/lists/ow2-projects

Adding a new project

A project is added to the marketplace once it has been discussed and approved by the Technology Council. Once the TC has approved the project indeed, create a page in a dedicated space, named after the project's title in lowercase with hyphens replacing spaces, and add an object of class "ow2.Project" to it. In order to have the project's page display a link to the project's submission, make sure to move the submission page to the project's folder (e.g. project-xyz.submission-xyz).

Upgrading a project to the mature level

Projects willing to upgrade to the mature level must go through the steps described on the TC wiki at Mature level. A helper page is available as a template at MatureLevelFormTemplate for checking each criteria. Examples of filled-in forms include the following pages: FusionDirectory, Prelude. The OMM form is meant to be made available as an XWiki form by creating an 'omm' page in the project's folder and by attaching an 'ow2.OMM' object to it. See examples at FusionDirectory OMM and Prelude OMM. Once all the criteria are met and the OMM form is filled in, the OSCAR Scorecard application described below can be executed in order to produce a "metrics.json" file that has to be attached to the project's page. Then the project's "status" field can be updated to "Mature".

OSCAR Scorecard application

The OSCAR Scorecard application was developed to scrape data from various sources such as Fossology, SonarQube, OpenHub. The app repository is at https://gitlab.ow2.org/ow2-platform/oscar-scorecard (restricted access). The application contains two main folders: "xwiki-app" and "data-collectors". "xwiki-app" contains the XWiki classes and pages needed to perform the display. The namespace used there is "oscar" while it's "ow2" on the production site. The "data-collectors" folder contains the scripts that perform the actual data scraping. Each project is configured using a YAML file such as the following one: sat4j.yaml:

Each data collector has a configuration file located in the "tools" folder.

Install the app dependencies:

In order to execute the scrapers, modify the variable "project" in each data collector script, as follows:

Then, run each scraper as follows:

The output of each scraper is appended to a JSON file named after the project, e.g. "sat4.json". Once all scrapers have been executed, the JSON file has to be renamed to "metrics.json" and to be added as an attachment to the project's page on projects.ow2.org. See for instance Sat4j attachments.

All the metrics contained in the "metrics.json" file are then displayed in the "Quality Drivers" tab of the related project, see for instance the one of Sat4j.

The metrics are also used to compute the market readiness of the project, by applying a risk model. See for instance the Sat4j market readiness levels.

ProjectSheet page

The ProjectSheet page page contains the sections below:

Macros and risk level computation

Two macros are declared at the top of ProjectSheet:

• ommAverage: this macro computes the average score of the OMM form in each top level category. For instance it computes the documentation score as the average of the OMM indicators PDOC-1.1, PDOC-1.2, ..., PDOC-3.4. The average scores are used to display the OMM histogram.
• ommEqualsOneCount: this macro computes, for each OMM top level category, the number of items whose score equals to 1 (max). This indicator is the one used to compute the risk level in the normalize function.

Tabs declaration

Then, the ProjectSheet defines the available tabs: only an "Overview" tab for projects at the incubation or archive levels, completed by three tabs in case of a mature project: "Quality Assessment Tools", "Quality Drivers", "Market Readiness"

Overview tab

This tab contains all the main properties of the project. The "awards" field has to be formatted in YAML as follows (example taken from the ProActive dashboard):

OMM and risk histograms

Two histograms are generated for mature projects using the XWiki D3js extension: one for OMM, one for displaying the top level category risks.

Deployment tab

In case some AppHub cloud images are available for the current project, a deployment tab shows up with the list of available images. See for instance Prelude's deployment tab.

The list of images is populated by a script launched from the page AppHubUtils by adding the parameter "op=true". The page calls a script "uforge-client.sh" provided by UShareSoft to retrieve all the available images.