swen-746-project

Installation

To install the necessary dependencies for this project, it is recommended to use uv; however, you can also use pip.

Note: Make sure you have Python 3.12 or higher installed.

Using uv

1. Install uv if you haven't already:

   pip install uv

2. To create a virtual environment and install dependencies, run:

   uv sync

Using pip

1. Create a virtual environment (optional but recommended):

   python -m venv .venv
   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`

2. Install the dependencies:

   pip install -r requirements.txt

Usage

1. Set your GitHub token as an environment variable:

   export GITHUB_TOKEN=your_github_token

Note: Replace your_github_token with your actual GitHub token. If you do not set this variable, the script will use unauthenticated requests, which are subject to stricter rate limits. For instructions on how to create a GitHub token, see the GitHub documentation.

2. Run the script with the desired command and the target repository name as an argument. Use --help to see all options:

   Fetch Commits

   • With uv:

   uv run python src/repo_miner.py fetch-commits --repo owner/repo --out output.csv

   • Without uv:

   python src/repo_miner.py fetch-commits --repo owner/repo --out output.csv

   Note: There is an optional --max argument to limit the number of commits fetched. If not specified, all commits will be fetched.

   Output

   See data/commits.csv for an example output file.

   Fetch Issues

   • With uv:

   uv run python src/repo_miner.py fetch-issues --repo owner/repo --out output.csv

   • Without uv:

   python src/repo_miner.py fetch-issues --repo owner/repo --out output.csv

   Output

   See data/issues.csv for an example output file.

   Merge and Summarize

   • With uv:

       uv run python src/repo_miner.py summarize --commits commits.csv --issues issues.csv

   • Without uv:

       python src/repo_miner.py summarize --commits commits.csv --issues issues.csv

   Example Output

   Top 5 committers:
       Committer 1: 47 commits
       Committer 2: 23 commits
       Committer 3: 5 commits
       Committer 4: 3 commits
       Committer 5: 2 commits
   Issue close rate: 0.50
   Avg. issue open duration: 1.00 days
   

Note: Run the repo_miner.py script with --help to see all options. If you want more info about a specific command, then use the --help option after the command:

• With uv:

uv run python src/repo_miner.py --help

• Without uv:

python src/repo_miner.py --help