Skip to content

Commit c52b420

Browse files
Morry98Morry98
committed
Add community health files and streamline CLAUDE.md
Add GitHub issue templates (bug report, feature request), PR template, CONTRIBUTING.md, and SECURITY.md to support open-source contributions. Simplify CLAUDE.md by removing redundant details already covered in config files.
1 parent 75710cd commit c52b420

7 files changed

Lines changed: 352 additions & 30 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Bug Report
2+
description: Report a bug or unexpected behavior
3+
title: "[Bug]: "
4+
labels: ["bug"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thank you for taking the time to report a bug. Please fill out the form below to help us investigate.
10+
11+
- type: textarea
12+
id: description
13+
attributes:
14+
label: Description
15+
description: A clear and concise description of the bug.
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: reproduction
21+
attributes:
22+
label: Steps to Reproduce
23+
description: Minimal steps to reproduce the behavior.
24+
placeholder: |
25+
1. Configure TaskManager with ...
26+
2. Register a task with cron expression ...
27+
3. Start the application
28+
4. Observe ...
29+
validations:
30+
required: true
31+
32+
- type: textarea
33+
id: expected
34+
attributes:
35+
label: Expected Behavior
36+
description: What you expected to happen.
37+
validations:
38+
required: true
39+
40+
- type: textarea
41+
id: actual
42+
attributes:
43+
label: Actual Behavior
44+
description: What actually happened. Include error messages or logs if available.
45+
validations:
46+
required: true
47+
48+
- type: input
49+
id: version
50+
attributes:
51+
label: Package Version
52+
description: "Output of: pip show fastapi-task-manager"
53+
placeholder: "1.0.0"
54+
validations:
55+
required: true
56+
57+
- type: input
58+
id: python-version
59+
attributes:
60+
label: Python Version
61+
description: "Output of: python --version"
62+
placeholder: "3.14.0"
63+
validations:
64+
required: true
65+
66+
- type: input
67+
id: redis-version
68+
attributes:
69+
label: Redis Version
70+
description: "Output of: redis-server --version"
71+
placeholder: "7.2.0"
72+
validations:
73+
required: false
74+
75+
- type: input
76+
id: os
77+
attributes:
78+
label: Operating System
79+
placeholder: "Ubuntu 24.04 / macOS 15 / Windows 11"
80+
validations:
81+
required: false
82+
83+
- type: textarea
84+
id: additional
85+
attributes:
86+
label: Additional Context
87+
description: Any other context, screenshots, or logs that might help.
88+
validations:
89+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Security Vulnerability
4+
url: https://github.com/Morry98/fastapi-task-manager/blob/main/SECURITY.md
5+
about: Please report security vulnerabilities privately. Do NOT open a public issue.
6+
- name: Documentation
7+
url: https://fastapi-task-manager.morry98.com
8+
about: Check the documentation before opening an issue.

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
name: Feature Request
2+
description: Suggest a new feature or improvement
3+
title: "[Feature]: "
4+
labels: ["enhancement"]
5+
body:
6+
- type: markdown
7+
attributes:
8+
value: |
9+
Thank you for suggesting a feature! Please describe your idea below.
10+
11+
- type: textarea
12+
id: problem
13+
attributes:
14+
label: Problem or Use Case
15+
description: What problem does this feature solve? What use case does it address?
16+
placeholder: "I'm always frustrated when ..."
17+
validations:
18+
required: true
19+
20+
- type: textarea
21+
id: solution
22+
attributes:
23+
label: Proposed Solution
24+
description: Describe your proposed solution or feature.
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: alternatives
30+
attributes:
31+
label: Alternatives Considered
32+
description: Any alternative solutions or features you've considered.
33+
validations:
34+
required: false
35+
36+
- type: textarea
37+
id: additional
38+
attributes:
39+
label: Additional Context
40+
description: Any other context, mockups, or examples that might help.
41+
validations:
42+
required: false

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
## Summary
2+
3+
<!-- Brief description of the changes -->
4+
5+
## Related Issue
6+
7+
<!-- Link to the related issue, e.g., Closes #123 -->
8+
9+
## Type of Change
10+
11+
- [ ] Bug fix
12+
- [ ] New feature
13+
- [ ] Refactoring (no functional changes)
14+
- [ ] Documentation update
15+
- [ ] Other (describe below)
16+
17+
## Checklist
18+
19+
- [ ] My code follows the project's code style
20+
- [ ] I have added/updated comments where necessary
21+
- [ ] I have added/updated tests for my changes
22+
- [ ] All tests pass (`uv run pytest`)
23+
- [ ] Pre-commit hooks pass (`pre-commit run --all-files`)
24+
- [ ] I have updated the documentation (if applicable)

‎CLAUDE.md‎

Lines changed: 8 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
44

55
## Project Overview
66

7-
FastAPI Task Manager is a Python library (v1.0.0) that provides scheduled task management for FastAPI applications using Redis for distributed locking and task state. It enables cron-based task scheduling with single-instance execution safety across multiple app instances.
7+
FastAPI Task Manager is a Python library that provides scheduled task management for FastAPI applications using Redis for distributed locking and task state. It enables cron-based task scheduling with single-instance execution safety across multiple app instances.
88

9-
- **Package**: `fastapi-task-manager` on PyPI (also published to TestPyPI)
9+
- **Package**: `fastapi-task-manager` on PyPI
1010
- **Python**: >=3.10 (supports 3.10–3.14)
1111
- **License**: MIT
1212
- **Build system**: `uv_build`
@@ -43,24 +43,10 @@ uv build
4343

4444
## Pre-commit
4545

46-
This project uses **pre-commit** to enforce code quality on every commit. The configuration is in `.pre-commit-config.yaml`.
46+
This project uses **pre-commit** to enforce code quality on every commit. Hooks include formatting (Ruff), security (Bandit), type checking (ty), and more. See `.pre-commit-config.yaml` for the full configuration.
4747

48-
### Hooks (run automatically on `git commit`)
49-
50-
1. **pre-commit-hooks** (v6.0.0): `check-added-large-files`, `check-merge-conflict`, `end-of-file-fixer`, `check-toml`, `check-yaml`, `mixed-line-ending`, `trailing-whitespace`
51-
2. **remove-tabs** (Lucas-C, v1.5.6)
52-
3. **uv-lock** (astral-sh): ensures `uv.lock` stays in sync
53-
4. **ruff-check** + **ruff-format** (astral-sh): lint with `--fix --unsafe-fixes` and format
54-
5. **bandit** (v1.9.4): security linter
55-
6. **ty check** (local hook): type checking with Astral's ty
56-
57-
### Exclusions
58-
59-
Pre-commit excludes test files (`.*test.*\.py`, `.*/test/.*`) and markdown (`*.md`) from most hooks.
60-
61-
### Manual-stage hooks
62-
63-
- **prune-stale-tags**: `git fetch origin --prune --prune-tags --tags` (run with `pre-commit run --hook-stage manual prune-stale-tags`)
48+
- Run manually: `pre-commit run --all-files`
49+
- Prune stale tags: `pre-commit run --hook-stage manual prune-stale-tags`
6450

6551
## Architecture
6652

@@ -115,17 +101,10 @@ The library exports from `__init__.py`:
115101
- `Config`
116102
- `HealthResponse`
117103

118-
## Testing
119-
120-
- Framework: **pytest** with **pytest-asyncio** (asyncio_mode = "auto")
121-
- Coverage: **coverage** package
122-
- Tests use `pytest-asyncio` for async test support
123-
124-
## Documentation
104+
## Testing & Documentation
125105

126-
- Built with **MkDocs** + **Material for MkDocs**
127-
- Plugins: awesome-pages, glightbox, macros, termynal
128-
- Serve locally: `uv run mkdocs serve`
106+
- Tests: **pytest** with **pytest-asyncio** (asyncio_mode = "auto"), coverage via **coverage** package
107+
- Docs: **MkDocs** + **Material for MkDocs** — serve locally with `uv run mkdocs serve`
129108

130109
## Code Style
131110

@@ -134,6 +113,5 @@ The library exports from `__init__.py`:
134113
- Type checking with `ty` (Astral's type checker)
135114
- McCabe complexity limit: 12
136115
- Max function arguments: 8
137-
- Pre-commit excludes test files and markdown from some checks
138116
- **Code must always be commented**: Add clear and concise comments to explain non-obvious logic
139117
- **Language requirement**: All code (including comments) and documentation must be written in English

‎CONTRIBUTING.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Contributing to FastAPI Task Manager
2+
3+
Thank you for your interest in contributing to FastAPI Task Manager! This guide will help you get started.
4+
5+
## Getting Started
6+
7+
### Prerequisites
8+
9+
- Python 3.10+
10+
- [uv](https://docs.astral.sh/uv/) (package manager)
11+
- Redis (for running the full test suite)
12+
- [pre-commit](https://pre-commit.com/)
13+
14+
### Setup
15+
16+
1. Clone the repository:
17+
```bash
18+
git clone https://github.com/Morry98/fastapi-task-manager.git
19+
cd fastapi-task-manager
20+
```
21+
2. Install dependencies:
22+
```bash
23+
uv sync
24+
```
25+
3. Install pre-commit hooks:
26+
```bash
27+
pre-commit install
28+
```
29+
4. Create a branch for your changes:
30+
```bash
31+
git checkout -b your-branch-name
32+
```
33+
34+
> **Tip:** This project includes a `CLAUDE.md` file with detailed instructions for [Claude Code](https://claude.ai/code). If you use Claude Code as your development tool, it will automatically pick up project context, commands, and conventions.
35+
36+
## Development Workflow
37+
38+
### Running Tests
39+
40+
```bash
41+
uv run pytest
42+
```
43+
44+
With coverage:
45+
```bash
46+
uv run coverage run -m pytest && uv run coverage report
47+
```
48+
49+
### Code Quality
50+
51+
The project uses pre-commit hooks that run automatically on `git commit`. You can also run them manually:
52+
53+
```bash
54+
pre-commit run --all-files
55+
```
56+
57+
This includes:
58+
- **Ruff** for linting and formatting (line length: 120)
59+
- **Bandit** for security checks
60+
- **ty** for type checking
61+
62+
### Pruning Stale Tags
63+
64+
Before pushing tags, run the manual pre-commit hook to remove local tags that have been deleted on the remote:
65+
66+
```bash
67+
pre-commit run --hook-stage manual prune-stale-tags
68+
```
69+
70+
It's good practice to run this periodically to keep your local tags in sync with the remote.
71+
72+
### Code Style
73+
74+
- Line length: 120 characters
75+
- Add clear and concise comments to explain non-obvious logic
76+
- All code, comments, and documentation must be in **English**
77+
- Follow existing patterns in the codebase
78+
79+
### Documentation
80+
81+
Documentation is built with MkDocs Material. To preview locally:
82+
83+
```bash
84+
uv run mkdocs serve
85+
```
86+
87+
## How to Contribute
88+
89+
### Reporting Bugs
90+
91+
Use the [Bug Report](https://github.com/Morry98/fastapi-task-manager/issues/new?template=bug_report.yml) issue template. Include:
92+
- Steps to reproduce
93+
- Expected vs actual behavior
94+
- Python version and OS
95+
- Relevant logs or error messages
96+
97+
### Suggesting Features
98+
99+
Use the [Feature Request](https://github.com/Morry98/fastapi-task-manager/issues/new?template=feature_request.yml) issue template. Please describe:
100+
- The problem your feature would solve
101+
- Your proposed solution
102+
- Any alternatives you considered
103+
104+
### Submitting Pull Requests
105+
106+
1. **Open an issue first** to discuss the change, unless it's a small fix
107+
2. Create a branch from `main`
108+
3. Write your code following the project's code style
109+
4. Add or update tests as needed
110+
5. Ensure all checks pass (`pre-commit run --all-files` and `uv run pytest`)
111+
6. Update documentation if your change affects the public API
112+
7. Submit your PR against the `main` branch
113+
114+
#### PR Guidelines
115+
116+
- Keep PRs focused — one feature or fix per PR
117+
- Write a clear title and description
118+
- Reference related issues (e.g., `Closes #123`)
119+
- Be responsive to review feedback
120+
121+
## Project Structure
122+
123+
```
124+
src/fastapi_task_manager/
125+
├── task_manager.py # Entry point, FastAPI lifespan integration
126+
├── task_group.py # Task grouping and registration
127+
├── runner.py # Stream mode orchestrator
128+
├── leader_election.py # Distributed leader election via Redis
129+
├── coordinator.py # Task scheduling and stream publishing
130+
├── stream_consumer.py # Redis Streams consumer groups
131+
├── reconciler.py # Stale/failed task recovery
132+
├── statistics.py # Execution history tracking
133+
├── config.py # Pydantic configuration model
134+
├── redis_keys.py # Redis key pattern definitions
135+
├── task_router_services.py # Management API service layer
136+
├── async_utils.py # Shared async utilities
137+
└── schema/ # Pydantic response models
138+
```
139+
140+
## License
141+
142+
By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

0 commit comments

Comments
 (0)