Skip to content

Latest commit

 

History

History
152 lines (117 loc) · 11.4 KB

DeveloperGuide.md

File metadata and controls

152 lines (117 loc) · 11.4 KB

RepoSense - Developer Guide

Thank you for your interest in contributing to RepoSense!

Setting up

Prerequisites

  1. JDK 1.8.0_60 or later.
  2. git 2.14 or later on the command line.

Type git --version on your OS terminal and ensure that you have the correct version of git.

Setting up the project in your computer using IntelliJ

  1. Fork this repo, and clone the fork to your computer.
  2. Open IntelliJ (if you are not in the welcome screen, click File > Close Project to close the existing project dialog first).
  3. Set up the correct JDK version for Gradle.
    1. Click Configure > Project Defaults > Project Structure.
    2. Click New…​ and find the directory of the JDK.
  4. Click Import Project.
  5. Locate the build.gradle file and select it. Click OK.
  6. Ensure that the selected version of Gradle JVM matches our prerequisite.
  7. Click OK to accept the all the other default settings.

Verifying the setup

  1. Ensure that Gradle builds without error by running the command gradlew clean build, and ensure that it finishs with a BUILD SUCCESSFUL message.
  2. Run the tests to ensure that they all pass by running the command gradlew test functional, and ensure that it finishs with a BUILD SUCCESSFUL message.

Ensure that you are on the project root directory when using the gradlew commands.

Configuring the coding style

This project follows oss-generic coding standards. IntelliJ’s default style is mostly compliant with our Java coding convention but it uses a different import order from ours. To rectify,

  1. Go to File > Settings…​ (Windows/Linux), or IntelliJ IDEA > Preferences…​ (macOS).
  2. Select Editor > Code Style > Java.
  3. Click on the Imports tab to set the order
    • For Class count to use import with '*' and Names count to use static import with '*': Set to 999 to prevent IntelliJ from contracting the import statements
    • For Import Layout, follow this image below: import-order

Optionally, you can follow the Using Checkstyle document to configure Intellij to check style-compliance as you write code.

Before writing code

  1. Do check out our process guide before submitting any PR with your changes.

Building and running RepoSense from code

  1. Execute the following command on the OS terminal inside the project directory.
    Usage: gradlew run -Dargs="([-config CONFIG_FOLDER] | -repos REPO_PATH_OR_URL... | -view REPORT_FOLDER) [-output OUTPUT_DIRECTORY] [-since DD/MM/YYYY] [-until DD/MM/YYYY] [-formats FORMAT...]"

Sample usage to generate the report with no specify arguments: (find and use config files in current working directory)

gradlew run

Sample usage to generate the report with config files:

gradlew run -Dargs="-config ./configs/ -output output_path/ -since 01/10/2017 -until 01/11/2017 -formats java adoc js"

Sample usage to generate the report with repository locations:

gradlew run -Dargs="-repos https://github.com/reposense/RepoSense.git https://github.com/se-edu/collate.git -output output_path/ -since 01/10/2017 -until 01/11/2017 -formats java adoc js"

Sample usage to view the report:

gradlew run -Dargs="-view output_path/reposense-report"

-Dargs="..." uses the same argument format as mentioned above.

Architecture

architecture Figure 1. Overall architecture of RepoSense

Parser(ConfigParser)

Parser contains two classes:

  • ArgsParser: Parses the user-supplied command line arguments into a CliArguments object.
  • CsvParser: Parses the the user-supplied CSV config file into a list of RepoConfiguration for each repository to analyze.

Git(GitDownloader)

Git contains the wrapper classes for respective git commands.

  • GitDownloader: Wrapper class for git clone functionality. Clones the repository from GitHub into a temporary folder in order to run the analysis.
  • GitChecker: Wrapper class for git checkout functionality. Checks out the repository by branch name or commit hash.

CommitsReporter

CommitsReporter is responsible for analyzing the commit history and generating a CommitContributionSummary for each repository. CommitContributionSummary contains information such as each author's daily and weekly contribution and the variance of their contribution. CommitsReporter,

  1. uses CommitInfoExtractor to run the git log command, which generates the statistics of each commit made within date range.
  2. generates a CommitInfo for each commit, which contains the infoLine and statLine.
  3. uses CommitInfoAnalyzer to extract the relevant data from CommitInfo into a CommitResult, such as the number of line insertions and deletions in the commit and the author of the commit.
  4. uses CommitResultAggregator to aggregate all CommitResult into a CommitContributionSummary.

AuthorshipReporter

AuthorshipReporter is responsible for analyzing the white listed files, traces the original author for each line of text/code, and generating an AuthorshipSummary for each repository. AuthorshipSummary contains the analysis results of the white listed files and the amount of line contributions each author made. AuthorshipReporter,

  1. uses FileInfoExtractor to traverse the repository to find all relevant files.
  2. generates a FileInfo for each relevant file, which contains the path to the file and a list of LineInfo representing each line of the file.
  3. uses FileInfoAnalyzer to analyze each file, using git blame or annotations, and finds the Author for each LineInfo.
  4. generates a FileResult for each file, which consolidates the authorship results into a Map of each author's line contribution to the file.
  5. uses FileResultAggregator to aggregate all FileResult into an AuthorshipSummary.

ReportGenerator(Main)

ReportGenerator,

  1. uses GitDownloader API to download the repository from GitHub.
  2. copies the template files into the designated output directory.
  3. uses CommitReporter and AuthorshipReporter to produce the commit and authorship summary respectively.
  4. generates the JSON files needed to generate the HTML dashboard.

System

System contains the classes that interact with the Operating System and external processes.

  • CommandRunner creates processes that executes commands on the terminal. It consists of many git commands.
  • LogsManager uses the java.util.logging package for logging. The LogsManager class is used to manage the logging levels and logging destinations. Log messages are output through: Console and to a .log file.
  • DashboardServer starts a server to display the dashboard on the browser. It depends on the net.freeutils.httpserver package.

Model

Model holds the data structures that are commonly used by the different aspects of RepoSense.

  • Author stores the GitHub ID of an author. Any contributions or commits made by the author, using his/her GitHub ID or aliases, will be attributed to the same Author object. It is used by AuthorshipReporter and CommitsReporter to attribute the commit and file contributions to the respective authors.
  • CliArguments stores the parsed command line arguments supplied by the user. It contains the configuration settings such as the CSV config file to read from, the directory to output the report to, and date range of commits to analyze. These configuration settings are passed into RepoConfiguration.
  • RepoConfiguration stores the configuration information from the CSV config file for a single repository, which are the repository's orgarization, name, branch, list of authors to analyse, date range to analyze commits and files from CliArguments. These configuration information are used by:
    • GitDownloader to determine which repository to download from and which branch to check out to.
    • AuthorshipReporter and CommitsReporter to determine the range of commits and files to analyze.
    • ReportGenerator to determine the directory to output the report.

HTML Dashboard

Dashboard

The dashboard contains two main parts: data JSONs(generated by ReportGenerator), and the static Dashboard template. Refer to here for instructions on how to build the project and dashboard.

  • As shown in the graph above, there will be one summary JSON(summary.json) containing the summary information of all repositories, and one set of repo detail JSON(commits.json and authorship.json) for each repository, containing the contribution information of each specified author to that repository.

  • The dashboard template is a set of HTML + CSS + Javascript, which is located in template/. It is used to interpret the JSON information and display the dashboard on a web browser.
    Whenever RepoSense is built using Gradle, the current dashboard template's content will be zipped into templateZip.zip file for easier retrieval, and packaging into the generated .jar file.
    The dashboard template will then be unzipped to the target location along with the generated JSON data files in order to produce the dashboard whenever RepoSense generates a new report.