QIFTool or Query Issue Finder-Tool is a project created as a bachelor’s thesis.It aims to help in the quality research field of technical debt by provoding relevant discussions regarding these debts. The discussion are presented in form of issues from github. The tool uses keywords and additional metrics to find potentially interesting issues. Although it is meant for the field of techincal debt the tool can be also be used to return all different kind of issues’ topics.

The documentation can also be found here: Documentation

• Workflow
• How to run the program
• Configuration file
• Interactive mode
  • Functions
• SQLite - Database
  • Repositories
  • Issues
• Expanding the tool
  • Metrics
  • SQLite commands

QIFTool is written in Python(3.8) and uses Google’s Custom Search JSON API in conjunction with Google’s Custom Search Engine to filter issues directly on Github. Keywords will be read out of a configuration file to determine which issues should be prefiltered. All prefiltered issues found by the engine will be inserted for research and caching purposes into a SQLite database. Afterwards it uses the official Github API (PyGithub) to look through the available pieces of metainformation inside each found issue and compares them to the other metrics set in the configuration file to only show the issues that match the requirements.

1. Download the qiftool.py and requirements.txt files from the repository
2. Place both files in the desired location
3. Open the terminal and navigate to the files’ location
4. Install all dependencies by running pip3 install -r /path/to/requirements.txt or just pip install -r /path/to/requirements.txt depending on your python version
5. Run the program by using python3 qiftool.py
6. By running it for the very first time the tool should have created a config.ini file inside the tool’s folder. Fill out the necessary parameters following the instructions in Configuration file
7. With the config.file filled out run the programm again just like in step 5
8. The tool should now operate properly and an interactive mode will be seen. Follow Interactive mode for further instructions

This file is created by running the program for the very first time. It is used to give the user a space to use their own parameters used by the tool. The file contains three sections for the user to fill out.

[DEFAULT]
  path_of_database = current
  path_of_download = current
[credentials]
  github_api_key = randomnumberandlettersinlowercase
  google_api_key = randomlettersinuppderandlowercaseandsymbols
  google_cse_id = randomleterandnumbersinlowercase
[metrics]
  keywords = technical debt refactor rewrite
  issue_comments = 5
  repo_contributors = 50

1. [DEFAULT] this section contains the path for the database and downloaded repositories to be stored in. The user is able to create their own path with the location of the ’qiftool.py”s as a pivot. These can be changed by providiung a valid path on your machine.

2. [credentials] this section contains the corresponding credentials necessary to run the used APIs

   1. [github_api_key]
      1. register on github
      2. use this link and click on ’generate new token’ to create a new key
      3. paste the key as a parameter
   2. [google_api_key]
      1. register on google
      2. use this link and click on ’Get a Key’ to create a new key
      3. either choose a project or create a new one
      4. follow the instructions and paste the key as a parameter
   3. [google_cse_id]
      1. login to the google account created in the prior step
      2. use this link and click on the project you used to create the google key with
      3. look for the ’Search engine ID’ and paste the ID as a parameter

3. [metrics] These contain the metrics used for the google search. For further details for understanding each metric please refer to the tables in SQLite Database.

   1. [keywords] - string of characters with each element separated by a tabulator. Note that the keywords will be used to find patterns that exactly match. So ’refactor’ will find ’refactoring’ but not vice versa. In addition the keywords are connected with a logical and.
   2. [issue_comments] - an integer over 0. It will show issues that have at least the amount of comments set in this metric. So 5 will yield issues with 5 or more comments.
   3. [repo_contributors] - an integer over 0. It will show issues that have at least the amount of contributors working on the corresponding repository. So 5 will yield issues with more 5 or more contributors working on its repository.

Once you successfully configered the configuration file in 3 an interactive mode will be seen on the console after running it. In this mode the program will wait for the user to simply type a desired function into the console and confirming it by pressing enter. After being done with a function the program goes back to displaying the interactive mode as it loops itself around it.

This tool uses the SQLite version 3.33.0 (2020-8-14) library. The database created with this tool consists of two tables with one table refering to the other in a 1:n relation.

This tool can offer various fields of expansion. Most likely it will be an addition of other metrics. This section will explain how to proceed in order to expand the tool. Depending on the type of expansion the tool needs less steps to accomplish it

1. Inside create_config(): Add the desired metric as an attribute inside the [metrics] section and give it a default value.
2. Inside the Config class: Add the new metric to the __init__ function.
3. Inside read_config(): let the new metric be read out and stored inside the created instance of the Config class.
4. Inside create_database(path): Add the new metric to the respective table and add the desired constraints as well as edit the UNIQUE modifier.
5. Inside insert(conn, table, values): Add the new metric inside the respective insert statement as well as the required ?.
6. Depending on what kind of metric and how accessible it is, it is necessary to create a function and preferably a class for the metric to be extracted and stored in. In case it needs to be created and takes API requests, do not forget to add the reset_sleep(auth) condition. See function stats_code_frequency(repo, auth) for an example.
7. Inside either RepoObj or IssueObj: add the new metric to the __init__ function.
8. Inside metric_check(conn, config_issue_comments, config_repo_contributors, issue_id, repo_id): Add the new metric as a new condition. The amount of conditions have a 2ⁿ complexity for with n being the amount of metrics. This semantic should be rewritten in order to allow the addition of more metrics.
9. If desired to also print out the new metric, the class IssuePrint and function issue_print need to be modified by adding the new metric.
10. Inside page_iterator(auth, keywords, issue_comments, repo_contributors, google_api_key, google_cse_id, path_db): the new metric needs to be called and then be stored inside the repo or issue object.
11. Inside input_handler(init): To access or make proper use of the new metric, add a new function that is callable via the interactive mode.

These commands will be callable via the interactive mode and access the database and its entries directly

1. Inside input_handler(init): Add a condition to to access the new function. Note that the function will be determined via the use of tabulators as seperators.
2. Create a new function similar to get_issues_where_metrics(conn, keywords, issue_comments, repo_contributors) and modify the SQL statement to perform the desired action