Metadata-Version: 2.1
Name: truckfactor
Version: 0.2.8
Summary:  Tool to compute the truck factor of a Git repository 
Home-page: https://github.com/HelgeCPH/truckfactor
Author: HelgeCPH
Author-email: ropf@itu.dk
Requires-Python: >=3.9,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Dist: docopt (>=0.6.2,<0.7.0)
Requires-Dist: numpy (>=1.19.4,<2.0.0)
Requires-Dist: pandas (>=1.1.5,<2.0.0)
Requires-Dist: toml (>=0.10.2,<0.11.0)
Project-URL: Documentation, https://github.com/HelgeCPH/truckfactor/blob/main/README.md
Project-URL: Repository, https://github.com/HelgeCPH/truckfactor
Description-Content-Type: text/markdown

# What is this?

This tool, `truckfactor` computes the 
[truck (bus/lorry/lottery) factor](https://en.wikipedia.org/wiki/Bus_factor) for a 
given Git repository.

The truck factor is

  > the number of people on your team that have to be hit by a truck (or quit) 
  > before the project is in serious trouble
  >
  > L. Williams and R. Kessler, Pair Programming Illuminated. Addison Wesley, 2003.

<!-- One of the earliest occurrences of the term in a real project was in the Python
mailing list: 
["If Guido was hit by a bus?"](https://legacy.python.org/search/hypermail/python-1994q2/1040.html) -->


## Installation

```
pip install truckfactor
```

### Requirements

The tool requires that `git` is installed and accessible on `PATH`.


## How to use it?

You have to either point the tool to a directory containing a Git repository or
to a URL with a remote repository. In case a URL is given, the tool will clone
the repository into a temporary directory.

From the terminal, the tool can be run as in the following:

```
Usage:
  truckfactor <repository> [<commit_sha>] [--output=<kind>]
  truckfactor -h | --help
  truckfactor --version

Options:
  -h --help     Show this screen.
  --version     Show version.
  --output=<kind>  Kind of output, either csv or verbose.
```

For example, in its most basic form it can be called like this:

```bash
$ truckfactor <path_or_url_to_repository>
The truck factor of <path_to_repository> (<commit_sha>) is: <number>
```

If no `output` switch is given, the tool produces a single line output above. Otherwise, it will output a line in CSV format or in key: value form.


Calling it from code:

```python
from truckfactor.compute import main


truckfactor = main("<path_to_repo>")
```


# How does the tool compute the truck factor?

In essence the tool does the following:

  * Reads a git log from the repository
  * Computes for each file who has the _knowledge ownership_ of it.
    - A contributor has knowledge ownership of a file when she edited the most 
    lines in it.
    - That computation is inspired by 
    [A. Thornhill _Your Code as a Crime Scene_](https://pragprog.com/titles/atcrime/your-code-as-a-crime-scene/).
    - Note, only for text files knowledge ownership is computed. The tool may 
    not return a good answer for repositories containing only binary files.
  * Then similar to [G. Avelino et al. *A novel approach for estimating Truck Factors*](https://peerj.com/preprints/1233.pdf) 
  low-contributing authors are removed from the analysis as long as still more 
  than half of all files have a knowledge owner. The amount of remaining 
  knowledge owners is the truck factor of the given repository.


# Why does it exist?

This tool was developed since in Dec. 2020, we could not find an open-source and readily installable tool to compute truck factors of projects on PyPI or Rubygems.

