From e6dfa3dc559f3dece11b7616ba809a6ec67c28a3 Mon Sep 17 00:00:00 2001 From: damithc Date: Thu, 16 May 2024 23:53:10 +0800 Subject: [PATCH 1/4] variables.md: Use syntax Let's update varialbes.md to use the proper syntax instead of the legacy syntax for defining variables. --- docs/_markbind/variables.md | 80 ++++++++++++++++++------------------- 1 file changed, 40 insertions(+), 40 deletions(-) diff --git a/docs/_markbind/variables.md b/docs/_markbind/variables.md index a38b52f05a..344f531535 100644 --- a/docs/_markbind/variables.md +++ b/docs/_markbind/variables.md @@ -1,42 +1,42 @@ -:fas-bell: -:fas-book: -:fas-calendar-alt: -:fas-thumbs-down: -:fas-cube: -:glyphicon-log-in: -:fas-dumbbell: -:fas-plus: extra -:fas-info-circle: -:fas-thumbs-up: -:fab-linux: -:far-star: -:far-star::far-star: -:far-star::far-star::far-star: -:glyphicon-exclamation-sign: -:glyphicon-exclamation-sign: -:glyphicon-new-window: -:fas-trophy: -:fas-arrow-down: -:fas-arrow-right: -:glyphicon-print: -:glyphicon-education: -:glyphicon-eye-open: -:fas-lightbulb: PRO TIP -:glyphicon-question-sign: -{{ icon_Q | safe }}:glyphicon-ok-sign: -:fas-paperclip: ->_ -:far-file-alt: -:fas-check: -:fas-lightbulb: -{{ icon_tick | safe }} -:glyphicon-check: -:far-images: -:glyphicon-facetime-video: -:fab-windows: -:fas-times: -{{ icon_x | safe }} -**{{ icon_dislike | safe }} Bad** -**{{ icon_like | safe }} Good** +:fas-bell: +:fas-book: +:fas-calendar-alt: +:fas-thumbs-down: +:fas-cube: +:glyphicon-log-in: +:fas-dumbbell: +:fas-plus: extra +:fas-info-circle: +:fas-thumbs-up: +:fab-linux: +:far-star: +:far-star::far-star: +:far-star::far-star::far-star: +:glyphicon-exclamation-sign: +:glyphicon-exclamation-sign: +:glyphicon-new-window: +:fas-trophy: +:fas-arrow-down: +:fas-arrow-right: +:glyphicon-print: +:glyphicon-education: +:glyphicon-eye-open: +:fas-lightbulb: PRO TIP +:glyphicon-question-sign: +{{ icon_Q | safe }}:glyphicon-ok-sign: +:fas-paperclip: +>_ +:far-file-alt: +:fas-check: +:fas-lightbulb: +{{ icon_tick | safe }} +:glyphicon-check: +:far-images: +:glyphicon-facetime-video: +:fab-windows: +:fas-times: +{{ icon_x | safe }} +**{{ icon_dislike | safe }} Bad** +**{{ icon_like | safe }} Good** From 43e97c89095cb707ecdde454aaf0ba8f4d27cb7e Mon Sep 17 00:00:00 2001 From: damithc Date: Thu, 16 May 2024 23:56:44 +0800 Subject: [PATCH 2/4] docs: Remove variables.json Let's remove the variables.json file as it is not used. --- docs/_markbind/variables.json | 3 --- docs/_markbind/variables.md | 2 -- 2 files changed, 5 deletions(-) delete mode 100644 docs/_markbind/variables.json diff --git a/docs/_markbind/variables.json b/docs/_markbind/variables.json deleted file mode 100644 index 9d89eb0358..0000000000 --- a/docs/_markbind/variables.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "jsonVariableExample": "Your variables can be defined here as well" -} diff --git a/docs/_markbind/variables.md b/docs/_markbind/variables.md index 344f531535..8699832bb4 100644 --- a/docs/_markbind/variables.md +++ b/docs/_markbind/variables.md @@ -38,5 +38,3 @@ {{ icon_x | safe }} **{{ icon_dislike | safe }} Bad** **{{ icon_like | safe }} Good** - - From 2c39b145298853f47e5549a685d2cf32cb0763db Mon Sep 17 00:00:00 2001 From: damithc Date: Fri, 17 May 2024 00:16:06 +0800 Subject: [PATCH 3/4] Update outdated links to example reports Let's update links of example dashboards to point to a later version which uses a more recent version of RepoSense. --- docs/ug/usingReports.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ug/usingReports.md b/docs/ug/usingReports.md index d0ebbd13c6..eebaf835d2 100644 --- a/docs/ug/usingReports.md +++ b/docs/ug/usingReports.md @@ -18,7 +18,7 @@ Let's look at how to view, interpret, and interact with a RepoSense report. As a report consists of web pages, it can be viewed using a Web Browser. Here are the ways to view the report in different situations. * **Situation 1: The report has been hosted on a website** - * Simply go to the URL of the report ([example](https://nus-cs2113-ay1920s2.github.io/tp-dashboard)) in your browser. + * Simply go to the URL of the report ([example](https://nus-cs2113-ay2324s2.github.io/tp-dashboard)) in your browser. * **Situation 2: You generated the report in your computer earlier** * Run RepoSense with the `--view` option:
Format: `java -jar RepoSense.jar --view REPORT_FOLDER`
@@ -129,7 +129,7 @@ Notes:
-**RepoSense support _intelligent_ bookmarks**: Note how the browser URL changes as you modify settings in the report. If you send that URL to someone else, that person will be able to use that URL to view the report in the same _view configuration_ you had when you copied the URL. For example, [this URL](https://nus-cs2113-ay1920s2.github.io/tp-dashboard/) and [this URL](https://nus-cs2113-ay1920s2.github.io/tp-dashboard/#search=&sort=groupTitle&sortWithin=title&since=2020-03-01&timeframe=day&mergegroup=true&groupSelect=groupByRepos&breakdown=true) give two different views of the same report. +**RepoSense support _intelligent_ bookmarks**: Note how the browser URL changes as you modify settings in the report. If you send that URL to someone else, that person will be able to use that URL to view the report in the same _view configuration_ you had when you copied the URL. For example, [this URL](https://nus-cs2113-ay2324s2.github.io/tp-dashboard/) and [this URL](https://nus-cs2113-ay2324s2.github.io/tp-dashboard/?search=&sort=groupTitle%20dsc&sortWithin=title&since=2024-02-23&until=2024-04-26&timeframe=commit&mergegroup=&groupSelect=groupByRepos&breakdown=true&tabOpen=false&checkedFileTypes=docs~functional-code~test-code~other) give two different views of the same report. From 8d75802c0d2f49d873f20f1c945dcd299ca98cf2 Mon Sep 17 00:00:00 2001 From: damithc Date: Fri, 17 May 2024 00:31:27 +0800 Subject: [PATCH 4/4] Fix typo: git -> Git --- docs/dg/architecture.md | 2 +- docs/dg/report.md | 2 +- docs/dg/settingUp.md | 2 +- docs/index.md | 2 +- docs/ug/cli.md | 2 +- docs/ug/configFiles.md | 18 +++++++++--------- docs/ug/customizingReports.md | 4 ++-- docs/ug/faq.md | 4 ++-- docs/ug/generatingReports.md | 4 ++-- docs/ug/usingAuthorTags.md | 2 +- docs/ug/usingReports.md | 2 +- 11 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/dg/architecture.md b/docs/dg/architecture.md index f7d9d4f4ac..ed4b2481f8 100644 --- a/docs/dg/architecture.md +++ b/docs/dg/architecture.md @@ -39,7 +39,7 @@ * [`GitShortlog`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitShortlog.java): Wrapper class for `git shortlog` functionality. Obtains the list of authors who have contributed to the target repo. * [`GitShow`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitShow.java): Wrapper class for `git show` functionality. Gets the date of the commit with the commit hash. * [`GitUtil`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitUtil.java): Contains helper functions used by the other Git classes above. - * [`GitVersion`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitVersion.java): Wrapper class for `git --version` functionality. Obtains the current git version of the environment that RepoSense is being run on. + * [`GitVersion`](https://github.com/reposense/RepoSense/blob/master/src/main/java/reposense/git/GitVersion.java): Wrapper class for `git --version` functionality. Obtains the current Git version of the environment that RepoSense is being run on. diff --git a/docs/dg/report.md b/docs/dg/report.md index f40add4810..f4f449fab5 100644 --- a/docs/dg/report.md +++ b/docs/dg/report.md @@ -50,7 +50,7 @@ The tabbed interface is responsible for loading various modules such as authorsh - **summary.json** - a list of all the repositories and their respective details - **projName/commits.json** - contains information of the users' commits information (e.g., line deletion, insertion, etc.), grouped by date -- **projName/authorship.json** - contains information from git blame, detailing the author of each line for all the processed files +- **projName/authorship.json** - contains information from `git blame`, detailing the author of each line for all the processed files diff --git a/docs/dg/settingUp.md b/docs/dg/settingUp.md index cc26d56ee8..1d87f98017 100644 --- a/docs/dg/settingUp.md +++ b/docs/dg/settingUp.md @@ -11,7 +11,7 @@ **Prerequisites:** * **JDK `11.0.21+9`** up to **`17`** ([download :fas-download:](https://www.oracle.com/technetwork/java/javase/downloads/index.html)). * **Node.js** **`18`** up to the latest minor version of **`19`** ([download :fas-download:](https://www.npmjs.com/get-npm)). -* **git `2.23`** or later ([download :fas-download:](https://git-scm.com/downloads)). +* **Git `2.23`** or later ([download :fas-download:](https://git-scm.com/downloads)). diff --git a/docs/index.md b/docs/index.md index 1106198a9e..308061dded 100644 --- a/docs/index.md +++ b/docs/index.md @@ -11,7 +11,7 @@

RepoSense

-Visualize programmer activities across git repositories... +Visualize programmer activities across Git repositories...

RepoSense overview

diff --git a/docs/ug/cli.md b/docs/ug/cli.md index 02f5cab297..9a7f707e66 100644 --- a/docs/ug/cli.md +++ b/docs/ug/cli.md @@ -215,7 +215,7 @@ credit is given. ### `--repo`, `--repos`, `-r` **`--repo REPO_LOCATION`**: Specifies which repositories to analyze. -* Parameter: `REPO_LOCATION` A list of URLs or the disk location of the git repositories to analyze, separated by spaces. +* Parameter: `REPO_LOCATION` A list of URLs or the disk location of the Git repositories to analyze, separated by spaces. * Alias: `-r` * Examples: * `--repos https://github.com/reposense/RepoSense.git` diff --git a/docs/ug/configFiles.md b/docs/ug/configFiles.md index 5a9c1745c2..0d65158ac7 100644 --- a/docs/ug/configFiles.md +++ b/docs/ug/configFiles.md @@ -33,7 +33,7 @@ Given below are the details of the various config files used by RepoSense. | Column Name | Explanation | |-------------|-------------| -| Repository's Location {{ mandatory }} | The `Remote Repo URL` or `Disk Path` to the git repository e.g., `https://github.com/foo/bar.git` or `C:\Users\user\Desktop\GitHub\foo\bar` | +| Repository's Location {{ mandatory }} | The `Remote Repo URL` or `Disk Path` to the Git repository e.g., `https://github.com/foo/bar.git` or `C:\Users\user\Desktop\GitHub\foo\bar` | | Branch | The branch to analyze in the target repository e.g., `master`. Default: the default branch of the repo | | File formats*+ | The file extensions to analyze. Binary file formats, such as `png` and `jpg`, will be automatically labelled as the file type `binary` in the generated report. Default: all file formats | | Find Previous Authors | Enter **`yes`** to utilize Git blame's ignore revisions functionality, RepoSense will attempt to blame the line changes caused by commits in the ignore commit list to the previous authors who altered those lines (if available). | @@ -75,7 +75,7 @@ Optionally, you can use an `author-config.csv` (which should be in the same dire | Author's Git Host ID# {{ mandatory }} | Username of the target author's profile on GitHub, GitLab or Bitbucket, e.g.`JohnDoe`. | | Author's Emails* | Associated emails of the author. For GitHub users, this can be found in your [GitHub settings](https://github.com/settings/emails). | | Author's Display Name | The name to display for the author. Default: author's username. | -| Author's Git Author Name* | The meaning of _Git Author Name_ is explained in [_A note about git author name_](#a-note-about-git-author-name). | +| Author's Git Author Name* | The meaning of _Git Author Name_ is explained in [_A note about Git author name_](#a-note-about-git-author-name). | | Ignore Glob List* | Files to ignore for this author, in addition to files ignored by the patterns specified in `repo-config.csv`. The path glob syntax is the same as that of Ignore Glob List in `repo-config.csv`. | * **Multi-value column**: multiple values can be entered in this column using a semicolon `;` as the separator. @@ -122,7 +122,7 @@ You can optionally use `report-config.json` to customize report generation by pr Repo owners can provide the following additional information to RepoSense using a config file that we call the **_standalone config file_**: * which files/authors/commits to analyze/omit -* which git and git host usernames belong to which authors +* which Git and Git host usernames belong to which authors * the display of an author To use this feature, add a `_reposense/config.json` to the root of your repo using the format in the example below ([another example](https://github.com/reposense/RepoSense/blob/master/_reposense/config.json)) and **commit it** (reason: RepoSense can see committed code only): @@ -160,9 +160,9 @@ Note: all fields are optional unless specified otherwise. **Fields to provide _author-level_ info**:
Note: `authors` field should contain _all_ authors that should be captured in the analysis. * `gitId`: Username of the author. {{ mandatory }} field. -* `emails`: Associated git emails of the author. For GitHub, this can be found in your [GitHub settings](https://github.com/settings/emails). +* `emails`: Associated Git emails of the author. For GitHub, this can be found in your [GitHub settings](https://github.com/settings/emails). * `displayName`: Name to display on the report for this author. -* `authorNames`: Git Author Name(s) used in the author's commits. By default, RepoSense assumes an author would use their remote Git Host username as the Git username too. The meaning of _Git Author Name_ is explained in [_A note about git author name_](#a-note-about-git-author-name). +* `authorNames`: Git Author Name(s) used in the author's commits. By default, RepoSense assumes an author would use their remote Git Host username as the Git username too. The meaning of _Git Author Name_ is explained in [_A note about Git author name_](#a-note-about-git-author-name). * `ignoreGlobList`: _Additional_ (i.e. on top of the repo-level `ignoreGlobList`) folders/files to ignore for a specific author. The path glob syntax is specified by the [_glob format_](https://docs.oracle.com/javase/tutorial/essential/io/fileOps.html#glob). In the example above, the actual `ignoreGlobList` for `alice` would be `["about-us/**", "**index.html", "**.css"]`. To verify your standalone configuration is as intended, add the `_reposense/config.json` to your local copy of repo and run RepoSense against it as follows:
@@ -170,7 +170,7 @@ To verify your standalone configuration is as intended, add the `_reposense/conf * Example: `java -jar RepoSense.jar --repo c:/myRepose/foo/bar`
After that, view the report to see if the configuration you specified in the config file is being reflected correctly in the report. -## A note about git author name +## A note about Git author name `Git Author Name` refers to the customizable author's display name set in the local `.gitconfig` file. For example, in the Git Log's display: ``` {.no-line-numbers} @@ -189,15 +189,15 @@ Date: Fri Feb 9 19:13:13 2018 +0800 ... ``` `ActualGitHostId` and `ConfiguredAuthorName` are both `Git Author Name` of the same author.
-To find the author name that you are currently using for your current git repository, run the following command within your git repository: +To find the author name that you are currently using for your current Git repository, run the following command within your Git repository: ``` shell {.no-line-numbers} git config user.name ``` -To set the author name to the value you want (e.g., to set it to your GitHub username) for your current git repository, you can use the following command ([more info](https://www.git-tower.com/learn/git/faq/change-author-name-email)): +To set the author name to the value you want (e.g., to set it to your GitHub username) for your current Git repository, you can use the following command ([more info](https://www.git-tower.com/learn/git/faq/change-author-name-email)): ``` shell {.no-line-numbers} git config user.name "YOUR_AUTHOR_NAME” ``` -To set the author name to use a default value you want for future git repositories, you can use the following command: +To set the author name to use a default value you want for future Git repositories, you can use the following command: ``` shell {.no-line-numbers} git config --global user.name "YOUR_AUTHOR_NAME” ``` diff --git a/docs/ug/customizingReports.md b/docs/ug/customizingReports.md index 531ae94442..741e7995d7 100644 --- a/docs/ug/customizingReports.md +++ b/docs/ug/customizingReports.md @@ -31,7 +31,7 @@ The report can be customized using several ways, as explained below. -**Managing config files collaboratively**: If you use RepoSense to monitor a large number of programmers, it may be more practical to get the programmers to submit PRs to update the config files as necessary (example use case). +**Managing config files collaboratively**: If you use RepoSense to monitor a large number of programmers, it may be more practical to get the programmers to submit PRs to update the config files as necessary (example use case). To ensure that their PRs are correct, you can use [Netlify _deploy previews_](https://www.netlify.com/blog/2016/07/20/introducing-deploy-previews-in-netlify/) to preview how the report would look like after the PR has been merged. More details are in the panels below. @@ -58,7 +58,7 @@ In both instances, it is **necessary to commit any changes** for them to be dete -3\. Add a git `.mailmap` file at the top-level of the repository, specifying mapped authors/commiters and/or e-mail addresses as per [gitmailmap documentation](https://git-scm.com/docs/gitmailmap). Any mappings specified here will be applied by git before all other RepoSense configurations. Configuration via `.mailmap` is particularly useful if you want the mapping to apply for all git commands as well instead of just for RepoSense. +3\. Add a Git `.mailmap` file at the top-level of the repository, specifying mapped authors/commiters and/or e-mail addresses as per [gitmailmap documentation](https://git-scm.com/docs/gitmailmap). Any mappings specified here will be applied by Git before all other RepoSense configurations. Configuration via `.mailmap` is particularly useful if you want the mapping to apply for all Git commands as well instead of just for RepoSense. diff --git a/docs/ug/faq.md b/docs/ug/faq.md index 005852bcae..a356df2b2a 100644 --- a/docs/ug/faq.md +++ b/docs/ug/faq.md @@ -9,8 +9,8 @@ ### Q: Does RepoSense work on private repositories? -**A:** *RepoSense* will first clone the git repository to be analyzed; thus, if you do not have access to the repository, we cannot run the analysis.
-To enable *RepoSense* to work on private repositories, ensure that you have enabled access to your private repository in your git terminal first before running the analysis. +**A:** *RepoSense* will first clone the Git repository to be analyzed; thus, if you do not have access to the repository, we cannot run the analysis.
+To enable *RepoSense* to work on private repositories, ensure that you have enabled access to your private repository in your Git terminal first before running the analysis. diff --git a/docs/ug/generatingReports.md b/docs/ug/generatingReports.md index bbc574d4d8..2bd1fc2c28 100644 --- a/docs/ug/generatingReports.md +++ b/docs/ug/generatingReports.md @@ -20,7 +20,7 @@ Let's look at different ways to generate RepoSense reports. -RepoSense is built to analyze any type of git repo, remote or local. It works best when analyzing remote repositories hosted on GitHub, GitLab or BitBucket. +RepoSense is built to analyze any type of Git repo, remote or local. It works best when analyzing remote repositories hosted on GitHub, GitLab or BitBucket. For other types of repositories, external links are disabled. @@ -30,7 +30,7 @@ For other types of repositories, external links are disabled. 1. **Ensure you have the prerequisites**: * **Java 11** or later ([download :fas-download:](https://www.java.com/en/)). - * **git `2.23`** or later on the command line. ([download :fas-download:](https://git-scm.com/downloads)).
run `git --version` in your OS terminal to confirm the version. + * **Git `2.23`** or later on the command line. ([download :fas-download:](https://git-scm.com/downloads)).
run `git --version` in your OS terminal to confirm the version. 1. **Download the latest JAR file** from our [releases](https://github.com/reposense/RepoSense/releases/latest). diff --git a/docs/ug/usingAuthorTags.md b/docs/ug/usingAuthorTags.md index 14f46db86a..9202970b17 100644 --- a/docs/ug/usingAuthorTags.md +++ b/docs/ug/usingAuthorTags.md @@ -12,7 +12,7 @@ `@@author` tags is a rather invasive but sometimes necessary way to provide more information to RepoSense, by annotating the code being analyzed.
-If you want to override the code authorship deduced by RepoSense (which is based on Git blame/log data), you can use `@@author` tags to specify certain code segments that should be credited to a certain author irrespective of git history. An example scenario where this is useful is when a method was originally written by one author but a second author did some minor refactoring to it; in this case, RepoSense might attribute the code to the second author while you may want to attribute the code to the first author. +If you want to override the code authorship deduced by RepoSense (which is based on Git blame/log data), you can use `@@author` tags to specify certain code segments that should be credited to a certain author irrespective of Git history. An example scenario where this is useful is when a method was originally written by one author but a second author did some minor refactoring to it; in this case, RepoSense might attribute the code to the second author while you may want to attribute the code to the first author. There are 2 types of `@@author` tags: - Start Tags (format: `@@author AUTHOR_GIT_AUTHOR_NAME`): A start tag indicates the start of a code segment written by the author identified by the `AUTHOR_GIT_AUTHOR_NAME`. diff --git a/docs/ug/usingReports.md b/docs/ug/usingReports.md index eebaf835d2..6ab6e90dfd 100644 --- a/docs/ug/usingReports.md +++ b/docs/ug/usingReports.md @@ -94,7 +94,7 @@ The `Tool Bar` at the top of the Chart panel provides a set of configuration opt * Multiple keywords/terms can be used, separated by spaces. * Entries that contain _any_ (not necessarily _all_) of the search terms will be displayed. * The keywords used to filter the author and repository are case-insensitive. - * Starting a search with `tag:` will filter author and repository by git tags. Similar search rules as above (like separating multiple tag names by space) apply. + * Starting a search with `tag:` will filter author and repository by Git tags. Similar search rules as above (like separating multiple tag names by space) apply. * `Group by`: grouping criteria for the rows of results. * `None`: results will not be grouped in any particular way. * `Repo/Branch`: results will be grouped by repositories and its' associating branches.