# Rate my project
[](https://github.com/cledouarec/rate-my-project/actions/workflows/lint.yaml)
[](https://github.com/cledouarec/rate-my-project/actions/workflows/test.yaml)
**Table of Contents**
- [Rate my project](#rate-my-project)
- [Overview](#overview)
- [Installation](#installation)
- [From PyPI (Recommended)](#from-pypi-recommended)
- [From sources](#from-sources)
- [Usage](#usage)
- [Exploration mode](#exploration-mode)
- [Report mode](#report-mode)
- [Configuration](#configuration)
- [Server configuration](#server-configuration)
- [Fields configuration](#fields-configuration)
- [Project configuration](#project-configuration)
- [Contribution](#contribution)
## Overview
**rate my project** is a tool designed to help analyze and improve the
efficiency of a project and the team working on it. It does this by integrating
with Jira, a popular project management tool from Atlassian, to retrieve data
and statistics about the project's progress and the team's performance.
By collecting this data from Jira, **rate my project** can provide an objective
view of the project's status and help identify areas for improvement. This can
include metrics such as how long tasks take to complete, how many tasks are
being completed on time, and how much work is being done by each team member.
In addition to analyzing the data, **rate my project** also offers the ability
to produce reports in Confluence, another popular collaboration tool in
Atlassian suite. These reports can help visualize the data collected by
**rate my project** and communicate it to stakeholders, team members, and other
interested parties.
Overall, **rate my project** is a useful tool for project managers and team
leaders who want to improve their team's efficiency and effectiveness. By using
data to gain an objective view of the project's progress, they can make
informed decisions and take actions that lead to better outcomes.
In developing this tool, it became clear that defining universal metrics
according to the topology of your JIRA projects was a complex task, so it was
essential to be able to provide a simple way of adding your own metrics in the
form of a plugin.
## Installation
### From PyPI (Recommended)
You can install easily with the following command or insert into your
requirements file :
```
pip install rate-my-project
```
### From sources
It is recommended to use a virtual environment :
```shell
python -m venv venv
```
To install the module and the main script, simply do :
```shell
pip install .
```
For the developers, it is useful to install extra tools like :
* [pre-commit](https://pre-commit.com)
* [pytest](http://docs.pytest.org)
* [commitizen](https://commitizen-tools.github.io/commitizen/)
These tools can be installed with the following command :
```shell
pip install '.[dev]'
```
The Git hooks can be installed with :
```shell
pre-commit install
```
The hooks can be run manually at any time :
```shell
pre-commit run --all-file
```
## Usage
The full list of arguments supported can be displayed with the following
helper :
```shell
./rate_my_project -h
Usage: rate_my_project [OPTIONS] COMMAND [ARGS]...
Swiss knife for measuring project efficiency.
Options:
-v, --verbose Enables verbose mode.
-h, --help Show this message and exit.
Commands:
explore Explore efficiency metrics with web interface from CONFIG file.
report Generate report from CONFIG file.
```
### Exploration mode
The first command is used to create a dynamic dashboard to explore the metrics.
The dashboard is a simple webapp which let the user entered a JQL query and
interact with the results.
This mode can be started by executing the following command :
```shell
./rate_my_project explore my_config.yaml
```
The dashboard will be accessible at : http://127.0.0.1:8050
### Report mode
The second command is used to create a report on Confluence for every project
in the config file.
The objective of this mode is to automate the reporting after finding the
right query in exploration mode.
This mode can be started by executing the following command :
```shell
./rate_my_project report my_config.yaml
```
## Configuration
The configuration file support 2 formats :
- [YAML format](https://yaml.org) (Recommended format)
- [JSON format](https://www.json.org)
In the configuration file, there are 4 main sections required :
- `server`
- `metrics`
- `fields`
- `projects`
Some fields could use double quotes to preserve space in their names. The YAML
syntax provides a solution by replacing with simple quote or escaping like
JSON :
**_In Yaml :_**
```yaml
jql: 'project = "MY TEST"'
```
**_In Json :_**
```json
{
"jql": "project = \"MY TEST\""
}
```
### Server configuration
The `server` node will configure the URL of the Jira and Confluence server.
The credentials could be defined with environment variables or `.env` file.
For the moment, only the username/token authentication is supported.
```
ATLASSIAN_USER=<your login>
ATLASSIAN_TOKEN=<your token>
```
**_In Yaml :_**
```yaml
server:
jira: "https://my.jira.server.com"
confluence: "https://my.confluence.server.com"
```
**_In Json :_**
```json
{
"server": {
"jira": "https://my.jira.server.com",
"confluence": "https://my.confluence.server.com"
}
}
```
| Attribute | Required | Description |
|------------|:--------:|--------------------------------------------------|
| server | ✅ | Main configuration node for server. |
| jira | ✅ | Jira server URL to retrieve tickets information. |
| confluence | ✅ | Confluence server URL to publish the report. |
### Metrics configuration
The `metrics` node will define the list of metrics to be used to avoid
unnecessary calculations or analysis.
**_In Yaml :_**
```yaml
metrics:
- status
```
**_In Json :_**
```json
{
"metrics": [
"status"
]
}
```
| Attribute | Required | Description |
|--------------|:--------:|--------------------------------------------------------|
| metrics | ✅ | Main configuration node for metrics. |
| \<metric\> | ✅ | List of metric name. At least one metric is mandatory |
### Fields configuration
The `fields` node will configure the field name to use since it could be custom
fields.
**_In Yaml :_**
```yaml
fields:
sprint: "customfield_10001"
story_points: "customfield_10002"
```
**_In Json :_**
```json
{
"fields": {
"sprint": "customfield_10001",
"story_points": "customfield_10002"
}
}
```
| Attribute | Required | Description |
|--------------|:--------:|-----------------------------------------------------------------|
| fields | ✅ | Main configuration node for fields. |
| sprint | ✅ | Field to store the current sprint. |
| story_points | ✅ | Field to store the estimation in story points of a development. |
### Project configuration
The `projects` node will provide the configuration for each project.
**_In Yaml :_**
```yaml
projects:
<project name>:
jql: "project = TEST"
report:
space: "SPACE"
parent_page: "My Parent Page"
workflow:
- name: "Backlog"
status:
- "Backlog"
- name: "In progress"
status:
- "In progress"
- "In review"
- name: "Done"
status:
- "Closed"
```
**_In Json :_**
```json
{
"projects": {
"<project name>": {
"jql": "project = TEST",
"report": {
"space": "SPACE",
"parent_page": "My Parent Page"
},
"workflow": [
{
"name": "Backlog",
"status": [
"Backlog"
]
},
{
"name": "In progress",
"status": [
"In progress",
"In review"
]
},
{
"name": "Done",
"status": [
"Closed"
]
}
]
}
}
}
```
| Attribute | Required | Description |
|------------------|:--------:|----------------------------------------------------------------------------------------------------------------------------------------|
| projects | ✅ | Main configuration node for all projects. |
| \<project name\> | ✅ | Must be replaced by the name of the project.<br/>This name will be used as a title of the report. |
| jql | ✅ | [JQL](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) query to retrieve the list of tickets. |
| report | ✅ | Configuration node for all attributes related to report generation. |
| space | ✅ | Confluence destination space. |
| parent_page | ✅ | Confluence parent page of the report page. |
| workflow | ✅ | Configuration node for defining workflow. |
#### Report configuration
Specific configuration to publish the report on Confluence.
| Attribute | Required | Description |
|-------------|:--------:|----------------------------------------------------------|
| space | ✅ | Confluence destination space. |
| parent_page | ✅ | Confluence parent page of the report page. |
| template | ❌ | Path to Jinja2 template used to produce the report page. |
#### Workflow configuration
The workflow defines a list of states. Each state permits to map several Jira
state to a "Virtual" state to simplify the metrics charts.
| Attribute | Required | Description |
|-----------|:--------:|---------------------------------------------------------------------------------------------------------------|
| name | ✅ | Confluence destination space. |
| status | ✅ | Confluence parent page of the report page. |
| start | ❌ | Boolean value to define the current state is considered as the start of the work in order to compute metrics. |
| stop | ❌ | Boolean value to define the current state is considered as the stop of the work in order to compute metrics. |
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, shall be as defined in the Apache-2.0 license
without any additional terms or conditions.
See [CONTRIBUTING.md](CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/cledouarec/rate-my-project",
"name": "rate-my-project",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "team efficiency data visualization analysis",
"author": "Christophe Le Douarec",
"author_email": "ledouarec@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/6c/d2/60ecb759e747028bb3867102b6f550eeb0ea6d7c48245aa188c1aa25249c/rate_my_project-1.2.0.tar.gz",
"platform": null,
"description": "# Rate my project\n\n[](https://github.com/cledouarec/rate-my-project/actions/workflows/lint.yaml)\n[](https://github.com/cledouarec/rate-my-project/actions/workflows/test.yaml)\n\n**Table of Contents**\n- [Rate my project](#rate-my-project)\n - [Overview](#overview)\n - [Installation](#installation)\n - [From PyPI (Recommended)](#from-pypi-recommended)\n - [From sources](#from-sources)\n - [Usage](#usage)\n - [Exploration mode](#exploration-mode)\n - [Report mode](#report-mode)\n - [Configuration](#configuration)\n - [Server configuration](#server-configuration)\n - [Fields configuration](#fields-configuration)\n - [Project configuration](#project-configuration)\n - [Contribution](#contribution)\n\n## Overview\n\n**rate my project** is a tool designed to help analyze and improve the\nefficiency of a project and the team working on it. It does this by integrating\nwith Jira, a popular project management tool from Atlassian, to retrieve data\nand statistics about the project's progress and the team's performance.\n\n\n\nBy collecting this data from Jira, **rate my project** can provide an objective\nview of the project's status and help identify areas for improvement. This can\ninclude metrics such as how long tasks take to complete, how many tasks are\nbeing completed on time, and how much work is being done by each team member.\n\nIn addition to analyzing the data, **rate my project** also offers the ability\nto produce reports in Confluence, another popular collaboration tool in\nAtlassian suite. These reports can help visualize the data collected by\n**rate my project** and communicate it to stakeholders, team members, and other\ninterested parties.\n\nOverall, **rate my project** is a useful tool for project managers and team\nleaders who want to improve their team's efficiency and effectiveness. By using\ndata to gain an objective view of the project's progress, they can make\ninformed decisions and take actions that lead to better outcomes.\n\nIn developing this tool, it became clear that defining universal metrics\naccording to the topology of your JIRA projects was a complex task, so it was\nessential to be able to provide a simple way of adding your own metrics in the\nform of a plugin.\n\n## Installation\n\n### From PyPI (Recommended)\n\nYou can install easily with the following command or insert into your\nrequirements file :\n```\npip install rate-my-project\n```\n\n### From sources\n\nIt is recommended to use a virtual environment :\n```shell\npython -m venv venv\n```\nTo install the module and the main script, simply do :\n```shell\npip install .\n```\nFor the developers, it is useful to install extra tools like :\n* [pre-commit](https://pre-commit.com)\n* [pytest](http://docs.pytest.org)\n* [commitizen](https://commitizen-tools.github.io/commitizen/)\n\nThese tools can be installed with the following command :\n```shell\npip install '.[dev]'\n```\nThe Git hooks can be installed with :\n```shell\npre-commit install\n```\nThe hooks can be run manually at any time :\n```shell\npre-commit run --all-file\n```\n\n## Usage\n\nThe full list of arguments supported can be displayed with the following\nhelper :\n```shell\n./rate_my_project -h\nUsage: rate_my_project [OPTIONS] COMMAND [ARGS]...\n\n Swiss knife for measuring project efficiency.\n\nOptions:\n -v, --verbose Enables verbose mode.\n -h, --help Show this message and exit.\n\nCommands:\n explore Explore efficiency metrics with web interface from CONFIG file.\n report Generate report from CONFIG file.\n\n```\n\n### Exploration mode\n\nThe first command is used to create a dynamic dashboard to explore the metrics.\nThe dashboard is a simple webapp which let the user entered a JQL query and \ninteract with the results.\n\nThis mode can be started by executing the following command :\n```shell\n./rate_my_project explore my_config.yaml\n```\nThe dashboard will be accessible at : http://127.0.0.1:8050\n\n### Report mode\n\nThe second command is used to create a report on Confluence for every project\nin the config file.\nThe objective of this mode is to automate the reporting after finding the \nright query in exploration mode.\n\nThis mode can be started by executing the following command :\n```shell\n./rate_my_project report my_config.yaml\n```\n\n## Configuration\n\nThe configuration file support 2 formats :\n- [YAML format](https://yaml.org) (Recommended format)\n- [JSON format](https://www.json.org)\n\nIn the configuration file, there are 4 main sections required :\n- `server`\n- `metrics`\n- `fields`\n- `projects`\n\nSome fields could use double quotes to preserve space in their names. The YAML\nsyntax provides a solution by replacing with simple quote or escaping like\nJSON :\n\n**_In Yaml :_**\n```yaml\njql: 'project = \"MY TEST\"'\n```\n**_In Json :_**\n```json\n{\n \"jql\": \"project = \\\"MY TEST\\\"\"\n}\n```\n\n### Server configuration\n\nThe `server` node will configure the URL of the Jira and Confluence server.\nThe credentials could be defined with environment variables or `.env` file.\nFor the moment, only the username/token authentication is supported.\n\n```\nATLASSIAN_USER=<your login>\nATLASSIAN_TOKEN=<your token>\n```\n\n**_In Yaml :_**\n```yaml\nserver:\n jira: \"https://my.jira.server.com\"\n confluence: \"https://my.confluence.server.com\"\n```\n**_In Json :_**\n```json\n{\n \"server\": {\n \"jira\": \"https://my.jira.server.com\",\n \"confluence\": \"https://my.confluence.server.com\"\n }\n}\n```\n\n| Attribute | Required | Description |\n|------------|:--------:|--------------------------------------------------|\n| server | \u2705 | Main configuration node for server. |\n| jira | \u2705 | Jira server URL to retrieve tickets information. |\n| confluence | \u2705 | Confluence server URL to publish the report. |\n\n### Metrics configuration\n\nThe `metrics` node will define the list of metrics to be used to avoid\nunnecessary calculations or analysis.\n\n**_In Yaml :_**\n```yaml\nmetrics:\n - status\n```\n**_In Json :_**\n```json\n{\n \"metrics\": [\n \"status\"\n ]\n}\n```\n\n| Attribute | Required | Description |\n|--------------|:--------:|--------------------------------------------------------|\n| metrics | \u2705 | Main configuration node for metrics. |\n| \\<metric\\> | \u2705 | List of metric name. At least one metric is mandatory |\n\n### Fields configuration\n\nThe `fields` node will configure the field name to use since it could be custom\nfields.\n\n**_In Yaml :_**\n```yaml\nfields:\n sprint: \"customfield_10001\"\n story_points: \"customfield_10002\"\n```\n**_In Json :_**\n```json\n{\n \"fields\": {\n \"sprint\": \"customfield_10001\",\n \"story_points\": \"customfield_10002\"\n }\n}\n```\n\n| Attribute | Required | Description |\n|--------------|:--------:|-----------------------------------------------------------------|\n| fields | \u2705 | Main configuration node for fields. |\n| sprint | \u2705 | Field to store the current sprint. |\n| story_points | \u2705 | Field to store the estimation in story points of a development. |\n\n### Project configuration\n\nThe `projects` node will provide the configuration for each project.\n\n**_In Yaml :_**\n```yaml\nprojects:\n <project name>:\n jql: \"project = TEST\"\n report:\n space: \"SPACE\"\n parent_page: \"My Parent Page\"\n workflow:\n - name: \"Backlog\"\n status:\n - \"Backlog\"\n - name: \"In progress\"\n status:\n - \"In progress\"\n - \"In review\"\n - name: \"Done\"\n status:\n - \"Closed\"\n```\n**_In Json :_**\n```json\n{\n \"projects\": {\n \"<project name>\": {\n \"jql\": \"project = TEST\",\n \"report\": {\n \"space\": \"SPACE\",\n \"parent_page\": \"My Parent Page\"\n },\n \"workflow\": [\n {\n \"name\": \"Backlog\",\n \"status\": [\n \"Backlog\"\n ]\n },\n {\n \"name\": \"In progress\",\n \"status\": [\n \"In progress\",\n \"In review\"\n ]\n },\n {\n \"name\": \"Done\",\n \"status\": [\n \"Closed\"\n ]\n }\n ]\n }\n }\n}\n```\n\n| Attribute | Required | Description |\n|------------------|:--------:|----------------------------------------------------------------------------------------------------------------------------------------|\n| projects | \u2705 | Main configuration node for all projects. |\n| \\<project name\\> | \u2705 | Must be replaced by the name of the project.<br/>This name will be used as a title of the report. |\n| jql | \u2705 | [JQL](https://www.atlassian.com/blog/jira-software/jql-the-most-flexible-way-to-search-jira-14) query to retrieve the list of tickets. |\n| report | \u2705 | Configuration node for all attributes related to report generation. |\n| space | \u2705 | Confluence destination space. |\n| parent_page | \u2705 | Confluence parent page of the report page. |\n| workflow | \u2705 | Configuration node for defining workflow. |\n\n#### Report configuration\n\nSpecific configuration to publish the report on Confluence.\n\n| Attribute | Required | Description |\n|-------------|:--------:|----------------------------------------------------------|\n| space | \u2705 | Confluence destination space. |\n| parent_page | \u2705 | Confluence parent page of the report page. |\n| template | \u274c | Path to Jinja2 template used to produce the report page. |\n\n#### Workflow configuration\n\nThe workflow defines a list of states. Each state permits to map several Jira\nstate to a \"Virtual\" state to simplify the metrics charts. \n\n| Attribute | Required | Description |\n|-----------|:--------:|---------------------------------------------------------------------------------------------------------------|\n| name | \u2705 | Confluence destination space. |\n| status | \u2705 | Confluence parent page of the report page. |\n| start | \u274c | Boolean value to define the current state is considered as the start of the work in order to compute metrics. |\n| stop | \u274c | Boolean value to define the current state is considered as the stop of the work in order to compute metrics. |\n\n## Contribution\n\nUnless you explicitly state otherwise, any contribution intentionally submitted\nfor inclusion in the work by you, shall be as defined in the Apache-2.0 license\nwithout any additional terms or conditions.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Swiss knife tool for analyzing project efficiency",
"version": "1.2.0",
"project_urls": {
"Homepage": "https://github.com/cledouarec/rate-my-project"
},
"split_keywords": [
"team",
"efficiency",
"data",
"visualization",
"analysis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d23b30d9f94eeb0b12941d7ece87740c86eaec4774afd3d81b42e88dc2b57fc2",
"md5": "88ad12bcdefca3814844e040d35a8260",
"sha256": "9a0004afba0fb8f9eb895b13bd7b285b97df17c4a579e46830214812a2aa8247"
},
"downloads": -1,
"filename": "rate_my_project-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "88ad12bcdefca3814844e040d35a8260",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26135,
"upload_time": "2024-01-31T13:31:55",
"upload_time_iso_8601": "2024-01-31T13:31:55.599847Z",
"url": "https://files.pythonhosted.org/packages/d2/3b/30d9f94eeb0b12941d7ece87740c86eaec4774afd3d81b42e88dc2b57fc2/rate_my_project-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6cd260ecb759e747028bb3867102b6f550eeb0ea6d7c48245aa188c1aa25249c",
"md5": "d6cd3f9adb8d42b5765ac71acb48f5a6",
"sha256": "864a4314118ed11dc5f7b6d443009238fc76888afe27a1ed80d41835d2e3ba6a"
},
"downloads": -1,
"filename": "rate_my_project-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d6cd3f9adb8d42b5765ac71acb48f5a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28066,
"upload_time": "2024-01-31T13:31:57",
"upload_time_iso_8601": "2024-01-31T13:31:57.280280Z",
"url": "https://files.pythonhosted.org/packages/6c/d2/60ecb759e747028bb3867102b6f550eeb0ea6d7c48245aa188c1aa25249c/rate_my_project-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-31 13:31:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cledouarec",
"github_project": "rate-my-project",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "rate-my-project"
}
JSON
