Skip to content

Commit 6c0ba9d

Browse files
vchrombievaleriocos
vchrombie
authored and
valeriocos
committed
[docs] Revamp README.md
This commit revamps the existing README structure and moved a few contents inside doc folder. Signed-off-by: Venu Vardhan Reddy Tekula <venuvardhanreddytekula8@gmail.com>
1 parent 398b36d commit 6c0ba9d

File tree

2 files changed

+110
-87
lines changed

2 files changed

+110
-87
lines changed

‎README.md

+90-87
Original file line numberDiff line numberDiff line change
@@ -8,136 +8,154 @@ models. It has been implemented in the context of the EU funded research project
88

99
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.
1010

11-
In the initial version, the metrics supported will be the [CROSSMINER ones](https://github.com/crossminer/crossminer/tree/dev/web-dashboards/ossmeter-metrics).
12-
13-
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/).
11+
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/).
1412

1513
The final goal is to have a tool for "Automatic Project Assessment and Visualization based on Evolved Quality Models".
1614

17-
The original name for this project was Meditor but it was changed to Prosoul because meditor already was used in pip.
15+
## Architecture
1816

19-
## Source code and contributions
17+
A draft diagram for the architecture is:
18+
![arch-diag](doc/prosoul-arch.png?raw=true)
2019

21-
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.
2220

23-
The [code of conduct](CODE_OF_CONDUCT.md) must be followed in all contributions
24-
to the project.
21+
> **NOTE**: The original name for this project was **Meditor** but it was changed to **Prosoul** because meditor already was used in pip.
2522
26-
## Execution
2723

28-
**Prosoul** is a Django application. The recommended way to execute it is inside a python virtual environment.
24+
## Installation and Set up
25+
26+
**Prosoul** is a Django application. The recommended way to execute it is inside a python virtual environment.
27+
28+
### Requirements
29+
30+
* Python >=3.4
31+
* setuptools
32+
* django
33+
* kidash
34+
* requests
35+
* python3-tk
36+
* matplotlib
2937

30-
Change VENV_DIR with the path to the folder in which you want to store the virtual environment.
38+
You can run the application by three ways, [source code](#from-source-code), [pip package](#from-pip-package) and [docker](#from-docker).
3139

32-
### From source code repository
40+
### from source code
3341

3442
This is the recommended way if you want to contribute to the development of ProSoul.
3543

3644
```
37-
git clone https://github.com/Bitergia/prosoul.git
38-
cd prosoul/django-prosoul
45+
$ git clone https://github.com/Bitergia/prosoul.git
46+
$ cd prosoul/django-prosoul
3947
prosoul/django-prosoul $ mkdir -p VENV_DIR
4048
prosoul/django-prosoul $ python3 -m venv VENV_DIR
4149
prosoul/django-prosoul $ source VENV_DIR/bin/activate
42-
prosoul/django-prosoul $ pip3 install -r requirements.txt
50+
prosoul/django-prosoul (VENV_DIR) $ pip3 install -r requirements.txt
4351
```
4452

4553
And to start the Django application:
4654

4755
```
48-
prosoul/django-prosoul $ python3 manage.py makemigrations
49-
prosoul/django-prosoul $ python3 manage.py migrate
50-
prosoul/django-prosoul $ python3 manage.py runserver
56+
prosoul/django-prosoul (VENV_DIR) $ python3 manage.py makemigrations
57+
prosoul/django-prosoul (VENV_DIR) $ python3 manage.py migrate
58+
prosoul/django-prosoul (VENV_DIR) $ python3 manage.py runserver
5159
```
5260

5361
By default, the application will be accessible in: http://127.0.0.1:8000/
5462

55-
#### Demo Video
56-
57-
There is a demo video in YouTube about how to install the Prosoul application from the source code. Please click to watch it.
58-
59-
<div align="center">
60-
61-
[![Setting up Prosoul](https://img.youtube.com/vi/-wU1ck4ZrUw/0.jpg "Setting up Prosoul | YouTube")](https://www.youtube.com/watch?v=-wU1ck4ZrUw)
62-
63-
</div>
63+
There is a demo video in YouTube about how to install the Prosoul application from the source code.
6464

6565
**Quick Links**
6666

6767
1. Setting up Prosoul with PyCharm - [0:20](https://www.youtube.com/watch?v=-wU1ck4ZrUw&t=20s)
6868
2. Setting up Prosoul with Terminal - [3:33](https://www.youtube.com/watch?v=-wU1ck4ZrUw&t=213s)
6969

70-
### From pip package
70+
### from pip package
7171

7272
There is also a pip package with the Django application. You can just deploy it in a Django site:
7373

7474
```
75-
mkdir -p VENV_DIR
76-
python3 -m venv VENV_DIR
77-
source VENV_DIR/bin/activate
78-
pip install django
79-
pip install django-prosoul
75+
$ mkdir -p VENV_DIR
76+
$ python3 -m venv VENV_DIR
77+
$ source VENV_DIR/bin/activate
78+
(VENV_DIR) $ pip install django
79+
(VENV_DIR) $ pip install django-prosoul
8080
```
8181

8282
and you need to add the application following the normal steps in Django:
8383

8484
```
85-
django-admin startproject mysite
86-
cd mysite
87-
vi mysite/settings.py
85+
(VENV_DIR) $ django-admin startproject mysite
86+
(VENV_DIR) $ cd mysite
87+
88+
mysite (VENV_DIR) $ vi mysite/settings.py
8889
...
8990
INSTALLED_APPS = [
9091
'django.contrib.admin',
9192
...
9293
'prosoul'
9394
]
9495
95-
mysite (venv) $ vi mysite/urls.py
96+
mysite (VENV_DIR) $ vi mysite/urls.py
9697
...
9798
from django.conf.urls import include, url
9899
...
99100
urlpatterns = [
100101
path('admin/', admin.site.urls),
101102
path('prosoul/', include('prosoul.urls')),
102103
]
103-
mysite (venv) $ python manage.py migrate
104-
mysite (venv) $ python manage.py runserver
104+
105+
mysite (VENV_DIR) $ python manage.py migrate
106+
mysite (VENV_DIR) $ python manage.py runserver
105107
```
106108

107-
### Using a docker image
109+
### from docker
110+
111+
A docker image is also available to execute the application.
108112

109-
A docker image is also available to execute the application:
113+
> NOTE: The [docker-compose.yml](docker/docker-compose.yml) has the elasticsearch and kibiter configurations too
114+
along with prosoul.
110115

111116
```
112117
prosoul/docker $ docker-compose up
113118
```
114119

120+
The applications would be running on the respective allocated ports.
121+
122+
115123
## How to
116124

117-
This section explains how to create a quality model (QM), visualize it in Kibana and assess it on a set of projects.
125+
This section explains how to create a quality model (QM), view it, visualize it in Kibana and assess it on a set of
126+
projects.
118127
A QM is identified by a title and composed of several `Goals`, which aim at measuring specific aspects of your projects,
119128
such as `Activity`, `Community` and `Processes`. Each goal is defined by a set of `Attributes`, they aim at characterizing
120129
a given goal. For instance, the `Activity` goal could include `Code` and `Bugs`, while `Community` could have `Coders` and
121130
`Reporters` as attributes. Each attribute is then mapped to one or more `Metrics`. A `Metric` has a name, a 5-level
122-
threshold (used to rate the project wrt a metric) and the data implementing the metric. In the case of
123-
CROSSMINER, the metric implementation is the `metric_name` field of the metrics extracted from SCAVA and stored in
124-
the index `scava-metrics`. For example, the attribute `Code` previously created could be mapped on the SCAVA metric `Patches`,
125-
while the attribute `Bugs` could be represented by the SCAVA metrics `Bugs`, `Won't-Fix Bugs` and `Fixed Bugs`.
131+
threshold (used to rate the project wrt a metric) and the data implementing the metric. In the case of CROSSMINER, the
132+
metric implementation is the `metric_name` field of the metrics extracted from SCAVA and stored in the
133+
index `scava-metrics`. For example, the attribute `Code` previously created could be mapped on the SCAVA metric
134+
`Patches`, while the attribute `Bugs` could be represented by the SCAVA metrics `Bugs`, `Won't-Fix Bugs` and `Fixed Bugs`.
126135

127-
In the following sections, the Edit, Visualize and Assess views are described.
136+
In the following sections, the various functions of the application are described.
128137

129138
### Edit
130139

131-
The Edit view allows to create (modify and import) a QM.
140+
The Edit function allows to create (modify and import) a QM.
132141

133-
To create a QM, click on the first `Add` button and set a name for
134-
your QM (e.g., `MyFirstQM`) in the window that popped up. Then, Prosoul will automatically open a chain of windows to
135-
to let you insert your first `Goal`, its `Attributes` and the corresponding `Metrics`. For each metric, you will have to
136-
map it to an existing metric in your data. In the case of CROSSMINER, this is done via the `metric_name` attribute stored
142+
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.
143+
Then, Prosoul will automatically open a chain of windows to to let you insert your first `Goal`, its `Attributes` and the
144+
corresponding `Metrics`. For each metric, you will have to map it to an existing metric in your data. In the case of
145+
CROSSMINER, this is done via the `metric_name` attribute stored
137146
in the index `scava-metrics`.
138147

148+
### View
149+
150+
The View function allows you to view the QM in the form of a tree.
151+
152+
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
153+
some of the information like the number ofAttributes and Metrics in the selected QM. Click on any node to know more details
154+
about the attribute.
155+
139156
### Visualize
140-
The Visualize view allows to materialize your QM in Kibana through dashboards, which are created based on templates
157+
158+
The Visualize function allows to materialize your QM in Kibana through dashboards, which are created based on templates
141159
available [here](https://github.com/Bitergia/prosoul/tree/master/django-prosoul/prosoul/panels/templates).
142160

143161
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
149167
to Kibana and available in the menu `Dashboard`.
150168

151169
### Assess
152-
The Assess view allows to perform an assessment of the QM over the projects included in your data.
170+
171+
The Assess function allows to perform an assessment of the QM over the projects included in your data.
153172

154173
In the form, you have just to select the target QM, the ElasticSearch URL, the index where the data is stored and
155-
the metrics data backend. In the case of CROSSMINER, all form fields except the `Quality Model` one are already set to be used
156-
with the default Docker configuration of the [scava-deployment](https://github.com/crossminer/scava-deployment/tree/dev#scava-deployment).
174+
the metrics data backend. In the case of CROSSMINER, all form fields except the `Quality Model` one are already set to be
175+
used with the default Docker configuration of the [scava-deployment](https://github.com/crossminer/scava-deployment/tree/dev#scava-deployment).
157176

158177
Once the form is filled, by clicking on the `Create` button, you will be redirected to a page summarizing how the projects
159178
in your data comply with the QM selected.
160179

161-
## Tutorials
162-
163-
There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model:
164-
165-
* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm)
166-
* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm)
167-
* 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)
180+
### Import / Export
168181

169-
## Import / Export
170-
171-
Import and export for quality models can be done using the web interface or
172-
from the command line:
182+
Import and export for quality models can be done using the web interface or from the command line:
173183

174184
* Import a model from a OSSMeter JSON file:
175-
176185
```
177186
prosoul/django-prosoul $ PYTHONPATH=. prosoul/prosoul_import.py -f prosoul/data/ossmeter_qm.json --format ossmeter
178187
```
179188

180189
* Export a model to a GrimoireLab JSON file:
181-
182190
```
183191
prosoul/django-prosoul $ PYTHONPATH=. prosoul/prosoul_export.py -f prosoul/data/ossmeter_qm_grimoirelab.json --format grimoirelab -m "Default OSSMETER quality model"
184192
```
185193

186-
## Requirements
187194

188-
* Python >=3.4
189-
* setuptools
190-
* django
191-
* kidash
192-
* requests
193-
* python3-tk
194-
* matplotlib
195+
## Tutorials
195196

196-
## Architecture
197+
There is a demo video about how to install the Prosoul application from the source code.
197198

198-
A draft diagram for the architecture is:
199+
<div align="center">
199200

200-
![](doc/prosoul-arch.png?raw=true)
201+
[![Setting up Prosoul](https://img.youtube.com/vi/-wU1ck4ZrUw/0.jpg "Setting up Prosoul | YouTube")](https://www.youtube.com/watch?v=-wU1ck4ZrUw)
201202

202-
## Prosoul with CROSSMINER
203+
</div>
203204

204-
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.
205+
There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model:
206+
207+
* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm)
208+
* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm)
209+
* 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)
205210

206-
There is a [demo online of prosoul for CROSSMINER](https://eclipse.zoom.us/recording/share/cMm_9gGMNir9UWqY0Mn7mWCETlA_9LJhcZF0uGIru_KwIumekTziMw).
207211

208-
## Prosoul with GrimoireLab
212+
## Source code and contributions
209213

210-
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.
214+
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.
211215

212-
## ROADMAP
216+
The [code of conduct](CODE_OF_CONDUCT.md) must be followed in all contributions to the project.
213217

214-
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.
215218

216219
## License
217220

‎doc/README.md

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
## Tutorials
2+
3+
There are two introductory videos: showing the import and view feature, and how to use the editor for adding a new quality model:
4+
5+
* Import and view of quality models: [prosoul-intro.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-intro.webm)
6+
* Adding a new quality model: [prosoul-editor.webm](https://raw.githubusercontent.com/Bitergia/prosoul/master/doc/meditor-editor.webm)
7+
* 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)
8+
9+
## Prosoul with CROSSMINER
10+
11+
There is a specific guide for [using prosoul with CROSSMINER](prosoul-crossminer.md) for creating the visualization
12+
for a quality model and generating the assessment of the projects with CROSSMINER.
13+
14+
There is a
15+
[demo online of prosoul for CROSSMINER](https://eclipse.zoom.us/recording/share/cMm_9gGMNir9UWqY0Mn7mWCETlA_9LJhcZF0uGIru_KwIumekTziMw).
16+
17+
## Prosoul with GrimoireLab
18+
19+
There is a specific guide for [using prosoul with GrimoireLab](prosoul-grimoirelab.md) for creating the visualization
20+
for a quality model and generating the assessment of the projects with GrimoireLab.

0 commit comments

Comments
 (0)