diff --git a/README.md b/README.md index 022b89f..5e38cc7 100644 --- a/README.md +++ b/README.md @@ -8,83 +8,84 @@ models. It has been implemented in the context of the EU funded research project The goal of this project is to create a web editor and viewer for [software quality models](https://github.com/borisbaldassari/se-quality-models) that are used to show metrics in a meaningful way. Also, importers and exporters for the different quality models used in the industry will be implemented so they can be used as models or evolved for the creation of new quality models. -In the initial version, the metrics supported will be the [CROSSMINER ones](https://github.com/crossminer/crossminer/tree/dev/web-dashboards/ossmeter-metrics). - -Based on the models, visualizations and assessment for the projects are generated. In the initial version, Kibana dashboards will be created using [GrimoireLab](http://grimoirelab.github.io/). +Based on the models, visualizations and assessment for the projects are generated. In the initial version, the metrics supported will be the [CROSSMINER ones](https://github.com/crossminer/crossminer/tree/dev/web-dashboards/ossmeter-metrics) and the Kibana dashboards will be created using [GrimoireLab](http://grimoirelab.github.io/). The final goal is to have a tool for "Automatic Project Assessment and Visualization based on Evolved Quality Models". -The original name for this project was Meditor but it was changed to Prosoul because meditor already was used in pip. +## Architecture -## Source code and contributions +A draft diagram for the architecture is: +![arch-diag](doc/prosoul-arch.png?raw=true) -All the source code is available in the [Prosoul GitHub repository](https://github.com/Bitergia/prosoul). Please, upload pull requests if you have proposals to change the source code, and open an issue if you want to report a bug, ask for a new feature, or just comment something. -The [code of conduct](CODE_OF_CONDUCT.md) must be followed in all contributions -to the project. +> **NOTE**: The original name for this project was **Meditor** but it was changed to **Prosoul** because meditor already was used in pip. -## Execution -**Prosoul** is a Django application. The recommended way to execute it is inside a python virtual environment. +## Installation and Set up + +**Prosoul** is a Django application. The recommended way to execute it is inside a python virtual environment. + +### Requirements + +* Python >=3.4 +* setuptools +* django +* kidash +* requests +* python3-tk +* matplotlib -Change VENV_DIR with the path to the folder in which you want to store the virtual environment. +You can run the application by three ways, [source code](#from-source-code), [pip package](#from-pip-package) and [docker](#from-docker). -### From source code repository +### from source code This is the recommended way if you want to contribute to the development of ProSoul. ``` -git clone https://github.com/Bitergia/prosoul.git -cd prosoul/django-prosoul +$ git clone https://github.com/Bitergia/prosoul.git +$ cd prosoul/django-prosoul prosoul/django-prosoul $ mkdir -p VENV_DIR prosoul/django-prosoul $ python3 -m venv VENV_DIR prosoul/django-prosoul $ source VENV_DIR/bin/activate -prosoul/django-prosoul $ pip3 install -r requirements.txt +prosoul/django-prosoul (VENV_DIR) $ pip3 install -r requirements.txt ``` And to start the Django application: ``` -prosoul/django-prosoul $ python3 manage.py makemigrations -prosoul/django-prosoul $ python3 manage.py migrate -prosoul/django-prosoul $ python3 manage.py runserver +prosoul/django-prosoul (VENV_DIR) $ python3 manage.py makemigrations +prosoul/django-prosoul (VENV_DIR) $ python3 manage.py migrate +prosoul/django-prosoul (VENV_DIR) $ python3 manage.py runserver ``` By default, the application will be accessible in: http://127.0.0.1:8000/ -#### Demo Video - -There is a demo video in YouTube about how to install the Prosoul application from the source code. Please click to watch it. - -
- -[![Setting up Prosoul](https://img.youtube.com/vi/-wU1ck4ZrUw/0.jpg "Setting up Prosoul | YouTube")](https://www.youtube.com/watch?v=-wU1ck4ZrUw) - -
+There is a demo video in YouTube about how to install the Prosoul application from the source code. **Quick Links** 1. Setting up Prosoul with PyCharm - [0:20](https://www.youtube.com/watch?v=-wU1ck4ZrUw&t=20s) 2. Setting up Prosoul with Terminal - [3:33](https://www.youtube.com/watch?v=-wU1ck4ZrUw&t=213s) -### From pip package +### from pip package There is also a pip package with the Django application. You can just deploy it in a Django site: ``` -mkdir -p VENV_DIR -python3 -m venv VENV_DIR -source VENV_DIR/bin/activate -pip install django -pip install django-prosoul +$ mkdir -p VENV_DIR +$ python3 -m venv VENV_DIR +$ source VENV_DIR/bin/activate +(VENV_DIR) $ pip install django +(VENV_DIR) $ pip install django-prosoul ``` and you need to add the application following the normal steps in Django: ``` -django-admin startproject mysite -cd mysite -vi mysite/settings.py +(VENV_DIR) $ django-admin startproject mysite +(VENV_DIR) $ cd mysite + +mysite (VENV_DIR) $ vi mysite/settings.py ... INSTALLED_APPS = [ 'django.contrib.admin', @@ -92,7 +93,7 @@ INSTALLED_APPS = [ 'prosoul' ] -mysite (venv) $ vi mysite/urls.py +mysite (VENV_DIR) $ vi mysite/urls.py ... from django.conf.urls import include, url ... @@ -100,44 +101,61 @@ urlpatterns = [ path('admin/', admin.site.urls), path('prosoul/', include('prosoul.urls')), ] -mysite (venv) $ python manage.py migrate -mysite (venv) $ python manage.py runserver + +mysite (VENV_DIR) $ python manage.py migrate +mysite (VENV_DIR) $ python manage.py runserver ``` -### Using a docker image +### from docker + +A docker image is also available to execute the application. -A docker image is also available to execute the application: +> NOTE: The [docker-compose.yml](docker/docker-compose.yml) has the elasticsearch and kibiter configurations too +along with prosoul. ``` prosoul/docker $ docker-compose up ``` +The applications would be running on the respective allocated ports. + + ## How to -This section explains how to create a quality model (QM), visualize it in Kibana and assess it on a set of projects. +This section explains how to create a quality model (QM), view it, visualize it in Kibana and assess it on a set of +projects. A QM is identified by a title and composed of several `Goals`, which aim at measuring specific aspects of your projects, such as `Activity`, `Community` and `Processes`. Each goal is defined by a set of `Attributes`, they aim at characterizing a given goal. For instance, the `Activity` goal could include `Code` and `Bugs`, while `Community` could have `Coders` and `Reporters` as attributes. Each attribute is then mapped to one or more `Metrics`. A `Metric` has a name, a 5-level -threshold (used to rate the project wrt a metric) and the data implementing the metric. In the case of -CROSSMINER, the metric implementation is the `metric_name` field of the metrics extracted from SCAVA and stored in -the index `scava-metrics`. For example, the attribute `Code` previously created could be mapped on the SCAVA metric `Patches`, -while the attribute `Bugs` could be represented by the SCAVA metrics `Bugs`, `Won't-Fix Bugs` and `Fixed Bugs`. +threshold (used to rate the project wrt a metric) and the data implementing the metric. In the case of CROSSMINER, the +metric implementation is the `metric_name` field of the metrics extracted from SCAVA and stored in the +index `scava-metrics`. For example, the attribute `Code` previously created could be mapped on the SCAVA metric +`Patches`, while the attribute `Bugs` could be represented by the SCAVA metrics `Bugs`, `Won't-Fix Bugs` and `Fixed Bugs`. -In the following sections, the Edit, Visualize and Assess views are described. +In the following sections, the various functions of the application are described. ### Edit -The Edit view allows to create (modify and import) a QM. +The Edit function allows to create (modify and import) a QM. -To create a QM, click on the first `Add` button and set a name for -your QM (e.g., `MyFirstQM`) in the window that popped up. Then, Prosoul will automatically open a chain of windows to -to let you insert your first `Goal`, its `Attributes` and the corresponding `Metrics`. For each metric, you will have to -map it to an existing metric in your data. In the case of CROSSMINER, this is done via the `metric_name` attribute stored +To create a QM, click on the first `Add` button and set a name for your QM (e.g., `MyFirstQM`) in the window that popped up. +Then, Prosoul will automatically open a chain of windows to to let you insert your first `Goal`, its `Attributes` and the +corresponding `Metrics`. For each metric, you will have to map it to an existing metric in your data. In the case of +CROSSMINER, this is done via the `metric_name` attribute stored in the index `scava-metrics`. +### View + +The View function allows you to view the QM in the form of a tree. + +Select the QM which you would like to view in the application and you can see the tree view of the QM. You can also view +some of the information like the number ofAttributes and Metrics in the selected QM. Click on any node to know more details +about the attribute. + ### Visualize -The Visualize view allows to materialize your QM in Kibana through dashboards, which are created based on templates + +The Visualize function allows to materialize your QM in Kibana through dashboards, which are created based on templates available [here](https://github.com/Bitergia/prosoul/tree/master/django-prosoul/prosoul/panels/templates). In the form, you have just to select the target QM, the ElasticSearch and Kibana URLs, the ElasticSearch index @@ -149,69 +167,54 @@ Once the form is filled, by clicking on the `Create` button, a set of dashboards to Kibana and available in the menu `Dashboard`. ### Assess -The Assess view allows to perform an assessment of the QM over the projects included in your data. + +The Assess function allows to perform an assessment of the QM over the projects included in your data. In the form, you have just to select the target QM, the ElasticSearch URL, the index where the data is stored and -the metrics data backend. In the case of CROSSMINER, all form fields except the `Quality Model` one are already set to be used -with the default Docker configuration of the [scava-deployment](https://github.com/crossminer/scava-deployment/tree/dev#scava-deployment). +the metrics data backend. In the case of CROSSMINER, all form fields except the `Quality Model` one are already set to be +used with the default Docker configuration of the [scava-deployment](https://github.com/crossminer/scava-deployment/tree/dev#scava-deployment). Once the form is filled, by clicking on the `Create` button, you will be redirected to a page summarizing how the projects in your data comply with the QM selected. -## Tutorials - -There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model: - -* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm) -* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm) -* Creating a viz and an assessment based on a quality model: [prosoul-viz-assess.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-viz-assess.webm) +### Import / Export -## Import / Export - -Import and export for quality models can be done using the web interface or -from the command line: +Import and export for quality models can be done using the web interface or from the command line: * Import a model from a OSSMeter JSON file: - ``` prosoul/django-prosoul $ PYTHONPATH=. prosoul/prosoul_import.py -f prosoul/data/ossmeter_qm.json --format ossmeter ``` * Export a model to a GrimoireLab JSON file: - ``` prosoul/django-prosoul $ PYTHONPATH=. prosoul/prosoul_export.py -f prosoul/data/ossmeter_qm_grimoirelab.json --format grimoirelab -m "Default OSSMETER quality model" ``` -## Requirements -* Python >=3.4 -* setuptools -* django -* kidash -* requests -* python3-tk -* matplotlib +## Tutorials -## Architecture +There is a demo video about how to install the Prosoul application from the source code. -A draft diagram for the architecture is: +
-![](doc/prosoul-arch.png?raw=true) +[![Setting up Prosoul](https://img.youtube.com/vi/-wU1ck4ZrUw/0.jpg "Setting up Prosoul | YouTube")](https://www.youtube.com/watch?v=-wU1ck4ZrUw) -## Prosoul with CROSSMINER +
-There is a specific guide for [using prosoul with CROSSMINER](doc/prosoul-crossminer.md) for creating the visualization for a quality model and generating the assessment of the projects with CROSSMINER. +There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model: + +* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm) +* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm) +* Creating a viz and an assessment based on a quality model: [prosoul-viz-assess.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-viz-assess.webm) -There is a [demo online of prosoul for CROSSMINER](https://eclipse.zoom.us/recording/share/cMm_9gGMNir9UWqY0Mn7mWCETlA_9LJhcZF0uGIru_KwIumekTziMw). -## Prosoul with GrimoireLab +## Source code and contributions -There is a specific guide for [using prosoul with GrimoireLab](doc/prosoul-grimoirelab.md) for creating the visualization for a quality model and generating the assessment of the projects with GrimoireLab. +All the source code is available in the [Prosoul GitHub repository](https://github.com/Bitergia/prosoul). Please, open an issue if you want to report a bug, ask for a new feature, or just comment something or send pull requests if you have proposals to change the source code. -## ROADMAP +The [code of conduct](CODE_OF_CONDUCT.md) must be followed in all contributions to the project. -The ROADMAP for Prosoul is based on [GitHub milestones](https://github.com/Bitergia/prosoul/milestones). The current active work is done in the issues related to the current milestone. ## License diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..f148bd6 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,20 @@ +## Tutorials + +There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model: + +* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm) +* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm) +* Creating a viz and an assessment based on a quality model: [prosoul-viz-assess.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-viz-assess.webm) + +## Prosoul with CROSSMINER + +There is a specific guide for [using prosoul with CROSSMINER](prosoul-crossminer.md) for creating the visualization +for a quality model and generating the assessment of the projects with CROSSMINER. + +There is a +[demo online of prosoul for CROSSMINER](https://eclipse.zoom.us/recording/share/cMm_9gGMNir9UWqY0Mn7mWCETlA_9LJhcZF0uGIru_KwIumekTziMw). + +## Prosoul with GrimoireLab + +There is a specific guide for [using prosoul with GrimoireLab](prosoul-grimoirelab.md) for creating the visualization +for a quality model and generating the assessment of the projects with GrimoireLab.