Skip to content

Commit

Permalink
[#329] UserGuide: clean up and rearrange sections (#334)
Browse files Browse the repository at this point in the history 
The instructions on many sections are incomplete and contains duplicate
information. Also, there is an inconsistency in phrasing of the
titles.

Let's clean up them up and also add a ToC to avoid confusing the users.
  • Loading branch information
@eugenepeh
eugenepeh authored Sep 9, 2018
1 parent 7af8404 commit e0d1290
Show file tree
Hide file tree
Showing 2 changed files with 92 additions and 57 deletions.
149 changes: 92 additions & 57 deletions docs/UserGuide.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,36 @@
# RepoSense - User Guide

## Quick Start
1. Ensure that you have the necessary [dependencies](#dependencies).
* [Prerequisites](#prerequisites)
* [Getting Started](#getting-started)
* [Generating the Report](#generating-the-report)
* [How to Generate Report](#how-to-generate-report)
* [Using repo-config.csv file](#using-repo-configcsv-file)
* [Using repository location(s)](#using-repository-locations)
* [How to View Report](#how-to-view-report)
* [With jar](#with-jar)
* [Manually](#manually)
* [Other option](#other-option)
* [Configuring Report Options](#configuring-report-options)
* [Repository configuration file](#repository-configuration-file)
* [[Optional] Author configuration file](#optional-author-configuration-file)
* [Git Author Name](#git-author-name)
* [[Optional] Preparation of Repositories](#optional-preparation-of-repositories)
* [Contribution Tags](#contribution-tags)
* [Standalone Configuration](#standalone-configuration)
* [Interpreting the Report](#interpreting-the-report)
* [Tool Bar](#tool-bar)
* [Chart Panel](#chart-panel)
* [Ramp Chart](#ramp-chart)
* [Total Contribution Bars](#total-contribution-bars)
* [Code Panel](#code-panel)

## Prerequisites
1. **JDK `1.8.0_60`** or later.
1. **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**.
## Getting Started
1. Ensure that you have the necessary [prerequisites](#prerequisites).
1. Download the latest executable Jar from our [release](https://github.com/reposense/RepoSense/releases/latest).
* Alternatively, you can compile the executable Jar yourself by following our [build from source guide](Build.md).
1. Generate the report by executing the jar with the terminal using your repository url as input. <br/>
Expand All @@ -11,63 +40,60 @@
```

For more information or to customize your own report, do read up on the following:
1. [How to Generate Report](#how-to-generate-report).
1. [How to View Report](#how-to-view-report).
1. Using the [CSV Config Files](#csv-config-files).
1. How to use the [Dashboard](#dashboard).
1. The full guide on [Generating the Report](#generating-the-report).
1. [Configuring Report Options](#configuring-report-options) using CSV file(s).
1. [Interpreting the Report](#interpreting-the-report).

## Dependencies
1. **JDK `1.8.0_60`** or later.
1. **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**.
## How to Generate Report
## Generating the Report
1. Download the latest executable Jar from our [release](https://github.com/reposense/RepoSense/releases/latest).
* Alternatively, you can compile the executable Jar yourself by following our [build from source guide](Build.md).
1. Execute it on the OS terminal. <br/>
1. To generate the report, please refer to [How to Generate Report](#how-to-generate-report).
1. To view the generated report, please refer to [How to View Report](#how-to-view-report).
1. Otherwise, you can also refer to [Other option](#other-option) on how to execute the program using source code.

### How to Generate Report
* [Using repo-config.csv file](#using-repo-configcsv-file).
* [Using repository location(s)](#using-repository-locations).

### Using repo-config.csv file
#### Using repo-config.csv file
Usage: `java -jar RepoSense.jar [-config CONFIG_DIRECTORY] [-output OUTPUT_DIRECTORY] [-since DD/MM/YYYY] [-until DD/MM/YYYY] [-formats FORMAT...]`
1. The report will be generated in the designated OUTPUT_DIRECTORY, or current working directory otherwise.

Sample usage to generate the report (with -config):
```
java -jar RepoSense.jar -config ./configs/ -output output_path/ -since 01/10/2017 -until 01/11/2017 -formats java adoc js
```
Argument List:
- config : Optional. The path to the directory that contains the configuration file(s). If not provided, it will be obtained from the current directory.
- output : Optional. The path to the dashboard generated. If not provided, it will be generated in the current directory.
- since : Optional. The start date of analysis. Format: `DD/MM/YYYY`
- until : Optional. The end date of analysis. Format: `DD/MM/YYYY`
- formats<sup>*</sup> : Optional. The file formats to analyze. Formats: `alphanumerical file formats`. <br/>
If not provided, the following file formats will be used: <br/>
`adoc cs css fxml gradle html java js json jsp md py tag xml`

<sup>* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `.</sup>

### Using repository location(s)
#### Using repository location(s)
Usage: `java -jar RepoSense.jar -repos REPO_PATH... [-output OUTPUT_DIRECTORY] [-since DD/MM/YYYY] [-until DD/MM/YYYY] [-formats FORMAT...]`
1. The report will be generated in the designated OUTPUT_DIRECTORY, or current working directory otherwise.

Sample usage to generate the report:
```
java -jar RepoSense.jar -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
```

> Note: The report will be generated in the designated OUTPUT_DIRECTORY, or current working directory otherwise.
Argument List:
- repo/repos<sup>*</sup> : Mandatory. The GitHub URL or disk location of the git repositories to clone. <br/>
- config<sup>^</sup> : Optional. The path to the directory that contains the configuration file(s). <br/>
If not provided, it will be obtained from the current directory.
- repo/repos<sup>*^</sup> : Mandatory. The GitHub URL or disk location of the git repositories to clone. <br/>
For example, `C:\Users\user\Desktop\GitHub\RepoSense`
- output : Optional. The path to the dashboard generated. <br/>
- output : Optional. The path to the report generated. <br/>
If not provided, it will be generated in the current directory.
- since : Optional. The start date of analysis. Format: `DD/MM/YYYY`
- until : Optional. The end date of analysis. Format: `DD/MM/YYYY`
- formats<sup>*</sup> : Optional. The file formats to analyze. Formats: `alphanumerical file formats`. <br/>
If not provided, the following file formats will be used: <br/>
`adoc cs css fxml gradle html java js json jsp md py tag xml`

<sup>* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `.</sup>
<sup>* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `.</sup><br/>
<sup>^ **Mutual exclusive**: only one of the arguments, in the mutually exclusive group, can be present at one time.</sup>

## How to View Report
### With jar
### How to View Report
* [With jar](#with-jar).
* [Manually](#manually).

#### With jar
1. Ensure that you have generated the report.
1. Execute it on the OS terminal. <br/>
Usage `java -jar RepoSense.jar -view REPORT_DIRECTORY`
Expand All @@ -76,14 +102,14 @@ Usage `java -jar RepoSense.jar -view REPORT_DIRECTORY`
java -jar RepoSense.jar -view output_path/reposense-report
```
Argument List:
- view : Mandatory.The server will be started to display the dashboard in the specified directory.
- view<sup>^</sup> : Mandatory. The server will be started to display the report in the specified directory.

`config` and `view` are mutually exclusive arguments which means that they cannot be provided together.
<sup>^ **Mutual exclusive**: only one of the arguments, in the mutually exclusive group, can be present at one time.</sup>

### Manually
1. Ensure that you have generated the report.
1. To visualize the report, open `index.html`.
1. If the dashboard was not loaded automatically, upload the `archive.zip` (generated in the OUTPUT_DIRECTORY) manually to load the data.
#### Manually
1. Ensure that you have [generated the report](#how-to-generate-report).
1. To visualize the report, open `index.html` (generated in the OUTPUT_DIRECTORY).
1. If the report was not loaded automatically, upload the `archive.zip` (in the same directory) manually to load the data.
```
Note:
The contribution calculation is based on the daily commits made within 00:00 to 23:59 in GMT+8.
Expand All @@ -98,28 +124,33 @@ Usage: `gradlew run -Dargs="([-config CONFIG_FOLDER] | -repos REPO_PATH_OR_URL..
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 dashboard:
Sample usage to view the report:
```
gradlew run -Dargs="-view output_path/reposense-report"
```
`-Dargs="..."` uses the same argument format as mentioned above.

## CSV Config Files
#### Repository configuration file
## Configuring Report Options
There are 2 CSV file(s) that can be used to customize your report:
1. [Repository configuration file](#repository-configuration-file)
1. [[Optional] Author configuration file](#optional-author-configuration-file)

Do also read up on [Preparation of Repositories](#optional-preparation-of-repositories) on how to further enhance the
accuracy of RepoSense analysis.

### Repository configuration file
to configure the list of repositories to analyze and the respective repository level options. <br/>
[repo-config.csv](repo-config.csv) is an example of a configuration file setup. It should contain the following columns:

Expand All @@ -134,28 +165,28 @@ Branch | The branch to analyze in the target repository

<sup>* **Multi-value column**: multiple values can be entered in this column using a semicolon, `;`, separator.</sup>

#### Author configuration file [Optional]
### [Optional] Author configuration file
to configure the list of authors to analyze and the options. <br/>
[author-config.csv](author-config.csv) is an example of a configuration file setup. It should contain the following columns:

<h5>
Note:
If author-config.csv is not used or the repositories being analyzed are not specified by any authors
in author-config.csv, add <a href="#standalone-configuration">Standalone Configuration</a> to those repostories.
Otherwise, all the authors of the repositories will be added into the report by default.
</h5>

Column Name | Explanation
----------- | -----------
Repository's Location | The `GitHub URL` or `Disk Path` to the git repository
Branch | The branch to analyze in the target repository
Author's GitHub ID | GitHub ID of the target contributor in the repository
Author's Display Name | Optional Field. The value of this field, if not empty, will be displayed in the dashboard instead of author's GitHub ID.
Author's Display Name | Optional Field. The value of this field, if not empty, will be displayed in the report instead of author's GitHub ID.
[Optional] Author's Git Author Name<sup>*</sup> | Detailed explanation below
[Optional] Ignore Global List<sup>*</sup> | The list of file path globs to ignore during analysis for this author on top of what is already specified in `author-config.csv`. More details on the Java glob standard [here](https://javapapers.com/java/glob-with-java-nio/)

<sup>* **Multi-value column**: multiple values can be entered in this column using a semicolon, `;`, separator.</sup>

<h5>
Note:
If author-config.csv is not used or the repositories being analyzed are not specified by any authors
in author-config.csv, add <a href="#standalone-configuration">Standalone Configuration</a> to those repostories.
Otherwise, all the authors of the repositories will be added into the report by default.
</h5>

#### Git Author Name
`Git Author Name` refers to the customizable author's display name set in the local `.gitconfig` file.
It is displayed as author name as opposed to the `GitHub ID` in the entries.
Expand Down Expand Up @@ -213,14 +244,18 @@ You can use `Start Tags` to mark the start of your contribution. The author spec
Instead of self-configuring all the repository details, you can have the repository owners include a *Standalone Configuration* to maintain their own repository configuration. For more information, check out the
[Setup Standalone Configuration](StandaloneConfiguration.md#reposense---guide-to-setup-standalone-configuration).

## Dashboard
The `Dashboard` is written in HTML and Javascript as static pages - readable by majority of web browsers, and easily deploy-able in most hosting platforms (such as [GitHub Pages](https://pages.github.com/)).
## Interpreting the Report
The report is written in HTML and Javascript as static pages - readable by majority of web browsers,
and easily deploy-able in most hosting platforms (such as [GitHub Pages](https://pages.github.com/)).

Below is an example of how the Dashboard looks like:
Below is an example of how the report looks like:

![dashboard](images/dashboard.png)
![report](images/report.png)

It consists of three main parts: [Tool Bar](#tool-bar), [Chart Panel](#chart-panel) and [Code Panel](#code-panel).
It consists of three main parts:
* [Tool Bar](#tool-bar)
* [Chart Panel](#chart-panel)
* [Code Panel](#code-panel)

### Tool Bar
The `Tool Bar` at the top provides a set of filters that control the chart panel. From right to left, the filters are:
Expand Down
0 docs/images/dashboard.png → docs/images/report.png
View file
File renamed without changes

0 comments on commit e0d1290

Please sign in to comment.