Metadata-Version: 2.4
Name: oss-issue-scout
Version: 0.2.0
Summary: Find worthwhile open-source issues.
Author: Ruifeng Xue
License: MIT License
        
        Copyright (c) 2026 Ruifeng Xue
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# oss-issue-scout

Find worthwhile open-source issues

The current version calls the GitHub API, searches open issues, and applies a simple score based on repository activity, issue activity, comments, labels, and related signals.
It is currently aimed at junior to intermediate developers who want a faster way to find approachable issues.

## Features

- Search GitHub open issues
- Filter by language, label, stars, and update recency
- Skip issues that already have linked PRs
- Recommend only unassigned issues by default
- Skip repositories with fewer than 100 stars by default
- Render results as `table`, `markdown`, or `json`
- No third-party dependencies

## Usage

```powershell
python -m pip install -e .
oss-issue-scout search --language python --label "good first issue" --limit 5
```

## Options

```text
--language            Repository primary language, such as python
--stars-min           Minimum repository stars; defaults to at least 100
--label               Issue label, such as "good first issue"
--updated-days        Issue updated within the last N days
--repo-updated-days   Repository had issue activity within the last N days
--limit               Number of results, default 10
--format              Output format: table, markdown, json
```

Examples:

```powershell
oss-issue-scout search --language python
oss-issue-scout search --language python --label "help wanted" --stars-min 500 --limit 10
oss-issue-scout search --language python --format json
oss-issue-scout search --language "C++" --label "good first issue" --repo-updated-days 7
```

## Scoring

The current score is intentionally simple. It considers:

- Repository stars: moderately active repos get a boost; very large repos may be penalized
- Issue update recency: recently updated issues get a boost; stale issues are penalized
- Repository issue activity: recent issue activity gets a boost
- Beginner-friendly labels: `good first issue` / `help wanted` only add points when the repo has at least 3 open issues with those labels
- Comment count: low discussion volume gets a boost; long discussions are penalized

The search step filters out:

- Closed issues
- Archived repositories
- Issues with linked PRs
- Assigned issues
- Repositories with fewer than 100 stars

## Tests

```powershell
python -m unittest discover
```

Tests use mocked GitHub responses and do not call the real GitHub API.

## Next

This project is still small. If it helps you, please consider giving it a ⭐. Discussions will be opened after the project reaches 16+ ⭐.

If you have suggestions or run into problems, please open an issue.

Future versions will continue to improve recommendation quality and usability.

## Contributors

<a href="https://github.com/Yong-yuan-X/oss-issue-scout/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=Yong-yuan-X/oss-issue-scout" alt="Contributors" />
</a>
