Skip to content

Commit 988618a

Browse files
smirnoffmgMaksim Smirnov
smirnoffmg
and
Maksim Smirnov
authored
Add cumulative queue time metrics (#6)
* Add cumulative queue time metrics * Update codebase --------- Co-authored-by: Maksim Smirnov <maksim.g.smirnov@raiffeisen.ru>
1 parent cec2a01 commit 988618a

17 files changed

Lines changed: 919 additions & 145 deletions

‎.pre-commit-config.yaml‎

Lines changed: 2 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,6 @@
11
repos:
2-
- repo: https://github.com/pre-commit/pre-commit-hooks
3-
rev: v4.5.0
2+
- repo: https://github.com/charliermarsh/ruff-pre-commit
3+
rev: v0.4.4
44
hooks:
5-
- id: check-yaml
6-
- id: end-of-file-fixer
7-
- id: trailing-whitespace
8-
- repo: https://github.com/psf/black
9-
rev: 24.2.0
10-
hooks:
11-
- id: black
12-
- repo: https://github.com/astral-sh/ruff-pre-commit
13-
# Ruff version.
14-
rev: v0.3.0
15-
hooks:
16-
# Run the linter.
175
- id: ruff
18-
args: [--fix]
19-
# Run the formatter.
206
- id: ruff-format
21-
- repo: https://github.com/codespell-project/codespell
22-
rev: v2.2.6
23-
hooks:
24-
- id: codespell
25-
additional_dependencies:
26-
- tomli

‎Makefile‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,26 @@
1+
include .env
2+
export
3+
4+
.PHONY: all
5+
16
help:
27
poetry install
38
poetry run python -m metrics --help
49

10+
install:
11+
pip install -r requirements.txt
12+
513
test:
6-
poetry run pytest --cov=metrics --cov-report=term-missing:skip-covered tests/
14+
pytest -v
715

816
lint:
9-
pre-commit run --all
17+
ruff check metrics/ tests/
18+
19+
format:
20+
ruff format metrics/ tests/
21+
22+
coverage:
23+
pytest --cov=metrics --cov-report=term-missing
24+
25+
clean:
26+
rm -rf .pytest_cache .coverage htmlcov output/*.png

‎README.md‎

Lines changed: 162 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,188 @@
1-
[![Maintainability](https://api.codeclimate.com/v1/badges/33ff71914506ebc13bdd/maintainability)](https://codeclimate.com/github/smirnoffmg/metrics/maintainability)
1+
# Metrics: Jira Engineering Analytics Toolkit
2+
3+
[![Build Status](https://img.shields.io/badge/build-passing-brightgreen)](https://github.com/your/repo/actions)
4+
[![Coverage Status](https://img.shields.io/badge/coverage-80%25-brightgreen)](https://github.com/your/repo/actions)
5+
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6+
7+
---
8+
9+
## 🚀 Vision
10+
**Metrics** empowers engineering teams to understand, visualize, and improve their software delivery process using real Jira data. It’s designed for:
11+
- Engineering managers and leads
12+
- Data-driven teams
13+
- Process improvement advocates
14+
- Anyone who wants actionable insights from Jira
15+
16+
---
17+
18+
## ✨ Features
19+
- **Fetches issues from Jira** using JQL (supports cloud and server)
20+
- **Calculates key metrics:**
21+
- Cycle time
22+
- Lead time
23+
- Queue time (per status)
24+
- Throughput (weekly)
25+
- Cumulative queue time (p50 per status)
26+
- Return to testing (how often issues return to QA)
27+
- **Visualizes metrics** as clear PNG charts (histograms, bar charts, etc.)
28+
- **Flexible configuration:** CLI, environment variables, or YAML/JSON config file
29+
- **Fast, robust, and fully tested**
30+
- **Extensible:** Modular architecture for adding new metrics or data sources
31+
32+
---
33+
34+
## 🏗️ Architecture Overview
35+
- **CLI entrypoint:** `metrics/__main__.py` (uses Click)
36+
- **Dependency injection:** Clean, testable services via `dependency_injector`
37+
- **Services:** Metrics calculation, visualization, and Jira repository
38+
- **Entities:** Strongly-typed Issue model
39+
- **Config:** Merges CLI, env, and config file (YAML/JSON)
40+
- **Output:** All charts saved to `output/` directory
41+
42+
---
43+
44+
## ⚡ Quickstart
45+
46+
### 1. Install dependencies
47+
```sh
48+
poetry install
49+
```
250

3-
# Development team metrics
51+
### 2. Run metrics analysis
52+
```sh
53+
python -m metrics --jira-server https://your-jira --jira-token <token> --jira-jql 'project=MYPROJ'
54+
```
455

5-
Measure your dev team metrics using python and your task tracker.
56+
Or with a config file:
57+
```sh
58+
python -m metrics --config config.yaml
59+
```
660

7-
## Supported task trackers
61+
---
862

9-
- Jira
63+
## ⚙️ Configuration Matrix
1064

11-
## Supported metrics
65+
| Option | CLI Option | Env Var | Config File Key | Required |
66+
| ----------- | ------------- | ----------- | --------------- | -------- |
67+
| Jira Server | --jira-server | JIRA_SERVER | jira.server | Yes |
68+
| Jira Token | --jira-token | JIRA_TOKEN | jira.token | Yes |
69+
| Jira JQL | --jira-jql | JIRA_JQL | jira.jql | Yes |
70+
| Config File | --config | N/A | N/A | No |
1271

13-
- Throughput
14-
- Lead time
15-
- Cycle time
16-
- Queue time
72+
- **Priority:** CLI > Env > Config file
73+
- **Config file format:** YAML or JSON
1774

18-
## Articles
75+
### Example YAML
76+
```yaml
77+
jira:
78+
server: https://your-jira
79+
token: your-token
80+
jql: project=MYPROJ
81+
```
1982
20-
* [Метрики команды разработки](https://habr.com/ru/articles/788930/)
21-
* [Software engineering metrics](https://medium.com/@maximsmirnov/software-engineering-metrics-613be9b99ccd)
83+
### Example JSON
84+
```json
85+
{
86+
"jira": {
87+
"server": "https://your-jira",
88+
"token": "your-token",
89+
"jql": "project=MYPROJ"
90+
}
91+
}
92+
```
2293

23-
## How to run?
94+
---
2495

25-
```shell
26-
poetry install
27-
poetry run python -m metrics --help
96+
## 🖥️ Usage
97+
98+
Show help and examples:
99+
```sh
100+
python -m metrics --help
28101
```
29102

30-
```shell
31-
poetry run python -m metrics --jira-server YOUR_SERVER_URL --jira-token YOUR_PERSONAL_TOKEN --jira-jql "project = Dev (for example)"
103+
Typical run:
104+
```sh
105+
python -m metrics --jira-server https://your-jira --jira-token <token> --jira-jql 'project=MYPROJ'
32106
```
33107

34-
## Example output
108+
**Output:**
109+
- PNG charts for each metric in the `output/` directory
110+
111+
---
112+
113+
## 📊 Example Output
114+
115+
Below are sample charts generated by Metrics:
35116

36117
### Throughput
118+
![Throughput](docs/images/throughput.png)
119+
120+
### Lead Time
121+
![Lead Time](docs/images/lead_time.png)
122+
123+
### Cycle Time
124+
![Cycle Time](docs/images/cycle_time.png)
125+
126+
### Queue Time (per status)
127+
**Status: New**
128+
![Queue Time New](docs/images/queue_time_new.png)
129+
130+
**Status: Test**
131+
![Queue Time Test](docs/images/queue_time_test.png)
132+
133+
---
134+
135+
## 🧪 Testing & Development
136+
137+
- **Run all tests:**
138+
```sh
139+
make test
140+
```
141+
- **Check coverage:**
142+
```sh
143+
make coverage
144+
```
145+
- **Lint and format:**
146+
```sh
147+
make lint
148+
make format
149+
```
150+
- **Pre-commit hooks:**
151+
```sh
152+
pre-commit install
153+
# Now every commit will be checked by Ruff
154+
```
37155

38-
![image](docs/images/throughput.png)
156+
---
39157

40-
### Lead time
158+
## 🛠️ Troubleshooting
159+
- **Missing dependencies:** Install with `pip install -r requirements.txt` or `poetry install`.
160+
- **YAML config error:** Install PyYAML: `pip install pyyaml`.
161+
- **Jira connection error:** Check your server URL, token, and network access.
162+
- **No output:** Check the `output/` directory and logs for errors.
41163

42-
![image](docs/images/lead_time.png)
164+
---
43165

44-
### Cycle time
166+
## ❓ FAQ
167+
**Q: Can I use this with Jira Cloud?**
168+
A: Yes! Just use your cloud URL and a valid API token.
45169

46-
![image](docs/images/cycle_time.png)
170+
**Q: Can I add new metrics or visualizations?**
171+
A: Yes! The code is modular—add new services or extend existing ones.
47172

48-
### Queue time for every status
173+
**Q: How do I contribute?**
174+
A: Fork, branch, run `make test` and `make lint`, and open a PR!
49175

50-
#### Status "New"
176+
---
51177

52-
![image](docs/images/queue_time_new.png)
178+
## 🤗 Contributing
179+
We welcome contributions! Please:
180+
- Follow the code style (enforced by Ruff)
181+
- Add/maintain docstrings and tests
182+
- Document new features in the README
183+
- Open a clear, descriptive pull request
53184

54-
#### Status "Test"
185+
---
55186

56-
![image](docs/images/queue_time_test.png)
187+
## 📄 License
188+
MIT License. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)