Skip to content

Commit 5935338

Browse files
vtemianclaude
vtemian
and
claude
committed
Modernize project with comprehensive tooling and CI/CD improvements
Major improvements include: - Migrate from Python 2.7 to Python 3.10+ with modern dependencies - Replace Travis CI with GitHub Actions for faster, more reliable CI - Implement Ruff for code formatting and linting (replaces multiple tools) - Add automated PyPI publishing with trusted publishing (no API tokens) - Migrate to uv for fast dependency management and builds - Switch to VCS-based versioning using git tags - Add comprehensive release management tools and documentation Technical changes: - Replace requirements.dev.txt with modern pyproject.toml configuration - Add matrix testing across Python 3.10-3.12 and Django 3.2-5.1 - Implement security scanning with pip-audit - Add code coverage reporting to Codecov - Create version bumping scripts and release automation - Add pre-release validation with make release-check - Comprehensive documentation in RELEASING.md and updated CLAUDE.md All tests pass and code quality checks enforced in CI. 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <[email protected]>
1 parent 61499fd commit 5935338

28 files changed

+1611
-198
lines changed

‎.github/workflows/ci.yml

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [ master, main ]
6+
tags: [ 'v*' ]
7+
pull_request:
8+
branches: [ master, main ]
9+
10+
jobs:
11+
test:
12+
runs-on: ubuntu-latest
13+
strategy:
14+
fail-fast: false
15+
matrix:
16+
include:
17+
# Test with Python 3.10
18+
- python-version: "3.10"
19+
django-version: "3.2"
20+
- python-version: "3.10"
21+
django-version: "4.2"
22+
- python-version: "3.10"
23+
django-version: "5.0"
24+
25+
# Test with Python 3.11
26+
- python-version: "3.11"
27+
django-version: "4.2"
28+
- python-version: "3.11"
29+
django-version: "5.0"
30+
- python-version: "3.11"
31+
django-version: "5.1"
32+
33+
# Test with Python 3.12
34+
- python-version: "3.12"
35+
django-version: "5.0"
36+
- python-version: "3.12"
37+
django-version: "5.1"
38+
39+
steps:
40+
- uses: actions/checkout@v4
41+
42+
- name: Set up Python ${{ matrix.python-version }}
43+
uses: actions/setup-python@v4
44+
with:
45+
python-version: ${{ matrix.python-version }}
46+
47+
- name: Install uv
48+
uses: astral-sh/setup-uv@v3
49+
with:
50+
version: "latest"
51+
52+
- name: Set up project
53+
run: uv sync --dev
54+
55+
- name: Install specific Django version
56+
run: uv add "django~=${{ matrix.django-version }}.0" --dev
57+
58+
- name: Run tests
59+
run: uv run pytest --cov=server_timing --cov-report=xml
60+
61+
- name: Upload coverage to Codecov
62+
uses: codecov/codecov-action@v3
63+
with:
64+
file: ./coverage.xml
65+
flags: unittests
66+
name: codecov-umbrella
67+
fail_ci_if_error: false
68+
69+
lint:
70+
runs-on: ubuntu-latest
71+
steps:
72+
- uses: actions/checkout@v4
73+
74+
- name: Set up Python
75+
uses: actions/setup-python@v4
76+
with:
77+
python-version: "3.11"
78+
79+
- name: Install uv
80+
uses: astral-sh/setup-uv@v3
81+
with:
82+
version: "latest"
83+
84+
- name: Set up project
85+
run: uv sync --dev
86+
87+
- name: Run Ruff linting
88+
run: uv run ruff check .
89+
90+
- name: Run Ruff format check
91+
run: uv run ruff format --check .
92+
93+
- name: Check Django configuration
94+
run: |
95+
cd example
96+
uv run python manage.py check
97+
98+
- name: Validate package build
99+
run: uv build
100+
101+
- name: Upload build artifacts
102+
uses: actions/upload-artifact@v3
103+
with:
104+
name: dist
105+
path: dist/
106+
107+
security:
108+
runs-on: ubuntu-latest
109+
steps:
110+
- uses: actions/checkout@v4
111+
112+
- name: Set up Python
113+
uses: actions/setup-python@v4
114+
with:
115+
python-version: "3.11"
116+
117+
- name: Install uv
118+
uses: astral-sh/setup-uv@v3
119+
with:
120+
version: "latest"
121+
122+
- name: Set up project
123+
run: uv sync --dev
124+
125+
- name: Install pip-audit
126+
run: uv pip install pip-audit
127+
128+
- name: Run safety check
129+
run: uv run pip-audit || true # Don't fail CI on security issues, just report
130+
131+
publish:
132+
needs: [test, lint]
133+
runs-on: ubuntu-latest
134+
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
135+
environment:
136+
name: pypi
137+
url: https://pypi.org/p/django-server-timing
138+
permissions:
139+
id-token: write
140+
141+
steps:
142+
- uses: actions/download-artifact@v3
143+
with:
144+
name: dist
145+
path: dist/
146+
147+
- name: Publish to PyPI
148+
uses: pypa/gh-action-pypi-publish@release/v1

‎.travis.yml

Lines changed: 0 additions & 19 deletions
This file was deleted.

‎CLAUDE.md

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
Django Server Timing is a middleware library that exposes performance metrics via the HTTP Server-Timing header. The header allows browsers to display timing information in the Network tab's Timing section (Chrome 65+).
8+
9+
## Key Commands
10+
11+
### Testing
12+
```bash
13+
# Run all tests with coverage using uv
14+
uv run pytest
15+
16+
# Alternative using Makefile
17+
make test
18+
```
19+
20+
### Development
21+
```bash
22+
# Install development dependencies with uv
23+
uv sync --dev
24+
25+
# Install production dependencies only
26+
uv sync
27+
28+
# Run the example Django app
29+
make run
30+
# or manually:
31+
cd example && uv run python manage.py runserver
32+
33+
# Build the package
34+
uv build
35+
```
36+
37+
### Code Quality
38+
```bash
39+
# Run linting with Ruff
40+
make lint
41+
42+
# Check code formatting
43+
make format-check
44+
45+
# Auto-format code
46+
make format
47+
48+
# Fix auto-fixable lint issues
49+
make lint-fix
50+
```
51+
52+
### Release Management
53+
```bash
54+
# Check if ready for release (lint, format, test, build)
55+
make release-check
56+
57+
# Bump version
58+
make version-patch # 0.0.3 -> 0.0.4
59+
make version-minor # 0.0.3 -> 0.1.0
60+
make version-major # 0.0.3 -> 1.0.0
61+
62+
# Or use the script directly
63+
python scripts/bump_version.py patch
64+
python scripts/bump_version.py --dry-run minor
65+
```
66+
67+
## Architecture
68+
69+
### Core Components
70+
71+
1. **`server_timing/middleware.py`** - Main middleware implementation
72+
- `ServerTiming` class - Django middleware that adds Server-Timing headers
73+
- `TimedService` class - For timing individual operations
74+
- `timed` context manager - For timing code blocks
75+
- `timed_wrapper` decorator - For timing functions
76+
- Uses thread-local storage for request isolation
77+
78+
2. **`server_timing/silk.py`** - Optional django-silk integration
79+
- `ServerTimingSilkMiddleware` - Adds SQL query timing
80+
- `ServerTimingSilkViewOnlyMiddleware` - Times only view execution
81+
82+
### How It Works
83+
84+
1. Middleware intercepts Django requests/responses
85+
2. Timing services collect metrics during request processing
86+
3. On response, all collected timings are formatted into Server-Timing header
87+
4. Browser displays timings in DevTools Network tab
88+
89+
Example header output:
90+
```
91+
Server-Timing: index;desc="Index View";dur=800,first;desc="First service";dur=300,second;desc="Second service";dur=500
92+
```
93+
94+
### Django Compatibility
95+
96+
- Supports Django 3.2+ through 5.0+
97+
- Handles Django 3.2+ header API changes in `server_timing/middleware.py:62-65`
98+
- Python 3.10+ required
99+
100+
### Package Management
101+
102+
- Uses `uv` for fast dependency management and virtual environments
103+
- `pyproject.toml` defines project configuration and dependencies
104+
- `uv.lock` provides reproducible dependency resolution
105+
- Development dependencies include Django 5.0+, pytest 8.2+, django-silk, and Ruff
106+
- Ruff configuration in `pyproject.toml` enforces code style and quality
107+
108+
## Testing Guidelines
109+
110+
- Tests use pytest with mocked `time.sleep()` for timing verification
111+
- Unit tests in `tests/test_unit.py` cover timing services, decorators, context managers
112+
- Integration tests in `tests/test_integration.py` verify header generation
113+
- Always run tests before committing changes
114+
115+
## CI/CD
116+
117+
- Uses GitHub Actions for continuous integration (`.github/workflows/ci.yml`)
118+
- Matrix testing across Python 3.10-3.12 and Django 3.2-5.1
119+
- Automated security scanning with pip-audit
120+
- Code coverage reporting to Codecov
121+
- Package build validation on every commit
122+
- Automated code quality checks with Ruff (linting + formatting)
123+
- **Automated PyPI publishing** on version tags via trusted publishing
124+
125+
### Release Process
126+
127+
1. **Prepare**: `make release-check` - runs all quality checks
128+
2. **Version bump**: `make version-patch/minor/major` - updates version
129+
3. **Commit & tag**: Commit changes and create `v*` tag
130+
4. **Automatic publish**: GitHub Actions publishes to PyPI on tag push
131+
132+
See `RELEASING.md` for detailed release instructions.
133+
134+
## Important Notes
135+
136+
- License discrepancy: setup.py mentions Apache, but LICENSE file is GPL v3
137+
- Uses modern Python packaging with `pyproject.toml` and `uv`
138+
- Build process uses `uv build` to create wheel distributions
139+
- Code formatting and linting enforced with Ruff
140+
- Minimum Python version increased to 3.10 due to Django 5.0+ and django-silk requirements
141+
- Migrated from Travis CI to GitHub Actions for modern CI/CD
142+
- Automated release management with version bumping scripts and PyPI publishing
143+
- Release documentation in `RELEASING.md` with detailed instructions

‎Makefile

Lines changed: 37 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,48 @@
11
full-test: test
22

33
test:
4-
pytest --cov=server_timing tests/
4+
uv run pytest
55

66
run:
77
cd example && \
8-
python manange.py runserver
8+
uv run python manage.py runserver
99

1010
build:
11-
echo "No need to build someting"
11+
uv build
12+
13+
install:
14+
uv sync --dev
15+
16+
install-prod:
17+
uv sync
1218

1319
lint:
14-
echo "TBA"
20+
uv run ruff check .
21+
22+
format:
23+
uv run ruff format .
24+
25+
format-check:
26+
uv run ruff format --check .
27+
28+
lint-fix:
29+
uv run ruff check --fix .
30+
31+
version-patch:
32+
python scripts/bump_version.py patch
33+
34+
version-minor:
35+
python scripts/bump_version.py minor
36+
37+
version-major:
38+
python scripts/bump_version.py major
39+
40+
release-check:
41+
@echo "Running pre-release checks..."
42+
make lint
43+
make format-check
44+
make test
45+
uv build
46+
@echo "✅ All checks passed - ready for release!"
1547

16-
.PHONY: test full-test build lint run
48+
.PHONY: test full-test build lint format format-check lint-fix run install install-prod version-patch version-minor version-major release-check

‎README.md

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,26 @@
11
# django-server-timing
2+
3+
[![CI](https://github.com/vtemian/django-server-timing/actions/workflows/ci.yml/badge.svg)](https://github.com/vtemian/django-server-timing/actions/workflows/ci.yml)
4+
[![codecov](https://codecov.io/gh/vtemian/django-server-timing/branch/master/graph/badge.svg)](https://codecov.io/gh/vtemian/django-server-timing)
5+
26
Django middleware that exposed collected metrics into [HTTP Server Timing](https://www.w3.org/TR/server-timing/) header.
37

48
This headers is used by browser to display several metrics into the `Timing` tab of the `Network` interface.
5-
Right now, this header is not supported properlly by all browser. It works pretty good on **Chrome 65+** and on **Firefox there is a bug** [report](https://bugzilla.mozilla.org/show_bug.cgi?id=1403051).
9+
Right now, this header is not supported properlly by all browser
610

711
It doesn't effect unsupported browser.
812

913
This middleware will send the entire header value since not all browsers supports sending it via [HTTP Trailer](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Trailer).
1014

1115
## Install
1216

13-
It works on **Python >= 2.7** and **Django >= 1.8**
17+
It works on **Python >= 3.10** and **Django >= 3.2**
1418

15-
Install easly via `pip`
19+
Install easily via `pip` or `uv`
1620
```bash
1721
pip install django-server-timing
22+
# or with uv
23+
uv add django-server-timing
1824
```
1925
And configure `MIDDLEWARES`
2026

0 commit comments

Comments
 (0)