From e0d1290cbbb923dedc08b2159deb417b2204533b Mon Sep 17 00:00:00 2001 From: Eugene Peh Date: Mon, 10 Sep 2018 01:06:28 +0800 Subject: [PATCH] [#329] UserGuide: clean up and rearrange sections (#334) 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. --- docs/UserGuide.md | 149 +++++++++++++--------- docs/images/{dashboard.png => report.png} | Bin 2 files changed, 92 insertions(+), 57 deletions(-) rename docs/images/{dashboard.png => report.png} (100%) diff --git a/docs/UserGuide.md b/docs/UserGuide.md index 5e3836b8bd..afa35ee3cd 100644 --- a/docs/UserGuide.md +++ b/docs/UserGuide.md @@ -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.
@@ -11,52 +40,45 @@ ``` 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.
+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* : Optional. The file formats to analyze. Formats: `alphanumerical file formats`.
- If not provided, the following file formats will be used:
- `adoc cs css fxml gradle html java js json jsp md py tag xml` - -* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `. -### 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* : Mandatory. The GitHub URL or disk location of the git repositories to clone.
+- config^ : Optional. The path to the directory that contains the configuration file(s).
+ If not provided, it will be obtained from the current directory. +- repo/repos*^ : Mandatory. The GitHub URL or disk location of the git repositories to clone.
For example, `C:\Users\user\Desktop\GitHub\RepoSense` -- output : Optional. The path to the dashboard generated.
+- output : Optional. The path to the report 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` @@ -64,10 +86,14 @@ Argument List: If not provided, the following file formats will be used:
`adoc cs css fxml gradle html java js json jsp md py tag xml` -* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `. +* **Multi-value field**: multiple values can be entered in this field by separating them with a space, ` `.
+^ **Mutual exclusive**: only one of the arguments, in the mutually exclusive group, can be present at one time. -## 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.
Usage `java -jar RepoSense.jar -view REPORT_DIRECTORY` @@ -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^ : 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. +^ **Mutual exclusive**: only one of the arguments, in the mutually exclusive group, can be present at one time. -### 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. @@ -98,13 +124,11 @@ 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: @@ -112,14 +136,21 @@ 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.
[repo-config.csv](repo-config.csv) is an example of a configuration file setup. It should contain the following columns: @@ -134,28 +165,28 @@ Branch | The branch to analyze in the target repository * **Multi-value column**: multiple values can be entered in this column using a semicolon, `;`, separator. -#### Author configuration file [Optional] +### [Optional] Author configuration file to configure the list of authors to analyze and the options.
[author-config.csv](author-config.csv) is an example of a configuration file setup. It should contain the following columns: -
-Note: -If author-config.csv is not used or the repositories being analyzed are not specified by any authors -in author-config.csv, add Standalone Configuration to those repostories. -Otherwise, all the authors of the repositories will be added into the report by default. -
- 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* | Detailed explanation below [Optional] Ignore Global List* | 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/) * **Multi-value column**: multiple values can be entered in this column using a semicolon, `;`, separator. +
+Note: +If author-config.csv is not used or the repositories being analyzed are not specified by any authors +in author-config.csv, add Standalone Configuration to those repostories. +Otherwise, all the authors of the repositories will be added into the report by default. +
+ #### 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. @@ -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: diff --git a/docs/images/dashboard.png b/docs/images/report.png similarity index 100% rename from docs/images/dashboard.png rename to docs/images/report.png