Learning the Basics

This is a learning guide for developers who are new to RepoSense.

Depending on what you know already and what you would like to work on (i.e., backend or frontend), you may find certain sections irrelevant to you and you can skip them accordingly.

Backend

This section is for developers who want to contribute to the backend of RepoSense. You may skip this section if you want to contribute as a pure frontend developer. Before you get started, you should have set up the project on your computer according to the Setting up page.

The backend implementation of RepoSense is located in src/main.

Step 1 Know Java

The RepoSense backend is mostly written in Java 11.

  1. You need to have a basic knowledge of Java before getting started, including its syntax, API, and certain frameworks such as JUnit.
  2. Once you are familiar with the basic syntax, you may wish to learn more advanced topics such as concurrency, synchronization, and streams. These topics can help you to understand certain part of the backend implementation (concurrent cloning and analysis of multiple repositories, etc.). They are optional but you may find them useful when working on certain issues.

Step 2 Learn the RepoSense backend architecture

You may want to refer to the backend architecture to understand the RepoSense backend implementation logic.

To gain a more concrete idea of how the backend works, you can use the IDE Debugger and run RepoSense under the debugging mode to trace through the steps of how arguments from command line and CSV files are parsed, how repositories are cloned and analyzed, and how the JSON files are generated.

The information below is for Intellij. If you are using a different IDE, you may need to check the documentation of how to use the debugger separately.

  • Check the debugging guide if you are not familiar with debugging in Intelij.
  • In RepoSense.java, the main class, set appropriate break points. Here are some relevant method calls in the main method at which you can set the breakpoints:
    • ArgsParser.parse(args): RepoSense parses the CLI arguments from the command given by the user.
    • getRepoConfigurations(cliArguments): RepoSense gets the configuration for each repository by parsing the CSV files.
    • getReportConfigurations(cliArguments): RepoSense gets the report configuration (report title) by parsing the JSON files.
    • ReportGenerator.generateReposReport(...) This is where the bulk of the work is conducted, including cloning repositories, analyzing repositories, and generating the JSON files to be used by the report.
  • To supply debugging arguments, right-click on the run button of RepoSense.main, click Modify Run Configuration, and add CLI flags in Program arguments. Examples: --since 16/12/2021 --until 18/12/2022; -s 16/12/2021 -u 18/12/2022.

When tracing through the program execution, you can cross reference the architecture diagram and Javadoc of the class and method to check your understanding of the procedure.

Step 3 Gain some hands-on experience

Here are some small tasks for you to gain some basic knowledge of the code related to the RepoSense backend. You can do each in a separate branch in your local copy of the code.

Task 1: Add a flag to pretty-print the JSON file

Task 2: Add exception message during repository cloning to the summary view

This is only for your practice. There is no need for you to commit this change and submit it in a pull request.

Step 4 Next Step

You can now proceed to learn the contributing workflow.

Frontend

This section is for developers who want to contribute to the frontend of RepoSense. You may skip this section if you want to contribute as a pure backend developer.

The frontend implementation of RepoSense is located in frontend/src.

Step 1 Learn the necessary tools

It is necessary for you to learn the basics of Vue.js, Pug, and SCSS before working on the project.

Vue.js

Vue.js uses JavaScript as its programming language. Before learning Vue.js, you may need to first get yourself familiar with JavaScript syntax first. You can refer to the Javascript documentation to learn the basic syntax. There are plenty of other resources available and please feel free to find the resource most suitable for you.

RepoSense uses Vue.js (Vue3) in its front-end implementation. In particular, major user interface components, such as summary view, authorship view, and zoom view, are implemented as Vue components. The corresponding source files are in frontend/src.

  • If you are new to Vue.js, you may want to start learning by looking at the beginner tutorial.
  • You can dive deeper later by checking the Vue.js documentation to learn about essential concepts such as component life cycle hooks, and component properties.
  • It is recommended if you can work on some small projects first to gain more solid understanding of Vue.js.

The guide above uses HTML as the component template, which is not the case with RepoSense. You may wish to learn more about Pug and its connection with HTML.

Vuex

RepoSense uses Vuex for the state management of the Vue components.

  • You can check the Vuex guide to find out how Vuex can be used in a Vue project.
  • There is also a course available that will walk you through an example of creating Vue application with Vuex.

Pug

RepoSense uses Pug files as the template of each Vue component. The corresponding HTML templates will later be generated from the Pug files by spuild when generating the report.

Since Pug is used to generate the HTML template, it is recommended that you have a basic knowledge of HTML before starting to learn Pug. Once you understand how HTML works, you can proceed to focus on how Pug is translated into HTML.

Scss

SCSS is used for styling the Pug template. The corresponding CSS will later be generated from the SCSS files by spuild when generating the report. The corresponding source files are in frontend/src/styles.

It is recommended that you have a basic knowledge of CSS before starting to learn SCSS. Once you understand how CSS works, you can proceed to focus on how SCSS is translated into CSS.

  • You can refer to the style rules to learn about the similarities and differences between SCSS and CSS.

Step 2 Learn the RepoSense frontend architecture

  • You may want to refer to the frontend architecture to understand the implementation.
  • Another way for you to understand the frontend is to use Vue.js devtools to learn how the various Vue Components interact with each other. You can refer to the frontend debugging guide for more information.

Step 3 Gain some hands-on experience

Here are some small tasks for you to gain some basic knowledge of the code related to the RepoSense frontend. You can do each in a separate branch in your local copy of the code.

Task 1: Highlight the selected author name in the summary view

Task 2: Add tooltip for file path in authorship panel

Task 3: Add tooltip for commit message title in zoom panel

This is only for your practice. There is no need for you to commit this change and submit it in a pull request.

Step 4 Next Step

You can now proceed to learn the contributing workflow.

DevOps

If you want to understand and contribute to the DevOps aspect of RepoSense, you can refer to the DevOps guide for more information.