diff --git a/about.html b/about.html index 05b084669c..176cf6ba9d 100644 --- a/about.html +++ b/about.html @@ -3,7 +3,7 @@ - + RepoSense - About us @@ -31,7 +31,7 @@ Committer [2018 Aug - 2018 Dec]
Contributor [2018 May - 2018 Aug]

Peh Xian Bin, Eugene


Role: Maintainer [2020 May - 2021 Jan]
Project Lead [2018 May - 2020 May]

Aditya Agarwal

Contributor [2018 May - 2018 Aug]

Apoorva Ullas

Contributor [2018 Aug - 2019 May]

Chelsey Ong Hee

Contributor [2018 Dec - 2019 May]

Gilbert Emerson

Contributor [2018 Dec - 2019 May]

Teo Ming Yi

Contributor [2018 Dec - 2019 May]

Jin Minjia

Role: Contributor [2019 May - 2019 Aug]

James Pang Mun Wai


Role: Committer [2020 May - 2021 Jan]
-Contributor [2019 May - 2020 May]

Lee Jin Yao


Role: Contributor [2019 May - 2020 May]

Chong Chee Yuan

Role: Contributor [2020 January - 2020 May]

Ni Tianzhen

Role: Contributor [2020 January - 2020 May]

Yash Chowdhary


Role: Contributor [2020 January - 2020 May]

Liu Yiwen

Role: Contributor [2019 August - 2021 May]

Tejas Bhuwania


Role: Contributor [2019 August - 2021 August]

Anubhav

Role: Contributor [2019 September - 2020 August]

Ang Ze Yu

Role: Contributor [2020 January - 2021 May]

Roland Yu Wenyang

Role: Contributor [2021 January - 2021 March]

+Contributor [2019 May - 2020 May]

Lee Jin Yao


Role: Contributor [2019 May - 2020 May]

Chong Chee Yuan

Role: Contributor [2020 January - 2020 May]

Ni Tianzhen

Role: Contributor [2020 January - 2020 May]

Yash Chowdhary


Role: Contributor [2020 January - 2020 May]

Liu Yiwen

Role: Contributor [2019 August - 2021 May]

Tejas Bhuwania


Role: Contributor [2019 August - 2021 August]

Anubhav

Role: Contributor [2019 September - 2020 August]

Ang Ze Yu

Role: Contributor [2020 January - 2021 May]

Roland Yu Wenyang

Role: Contributor [2021 January - 2021 March]

@@ -17,7 +17,7 @@

Contact us

You can post your questions, suggestions, and bug reports in our issue tracker.

Alternatively, you can email us at seer@comp.nus.edu.sg

+

Contact us

You can post your questions, suggestions, and bug reports in our issue tracker.

Alternatively, you can email us at seer@comp.nus.edu.sg

@@ -23,7 +23,7 @@
  • analyzes the repositories using the CommitReporter and AuthorshipReporter in a multi-threaded fashion.
  • generates the JSON files needed to generate the HTML report.

    • System

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

    Model

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

    + @@ -22,7 +22,7 @@

    --fresh-cloning

    --fresh-cloning: Clones the repo again if it has been cloned before.

    • Used in ConfigSystemTest.
    • Some test cases performs shallow cloning while some does not. Fresh cloning ensures that the test cases that does not perform shallow cloning will clone the repo again if the previous test case uses shallow cloning, ensuring -correctness of the analysis.
    • Requires --test-mode flag to be enabled.
    +correctness of the analysis.
  • Requires --test-mode flag to be enabled.
    • @@ -17,7 +17,7 @@

    DevOps Guide

    This page documents the various components that form part of the DevOps infrastructure that RepoSense uses.

    GitHub Actions

    GitHub Actions is a platform that is used by RepoSense for running the test suite and is primarily used for continuous integration and testing. The test suite is stored in .github/workflows/ and comprises of:

    • Unit tests (in src/tests/)
    • System tests (in src/systemtest/)
    • Frontend tests (in frontend/cypress/tests/)

    Continuous integration

    All three types of tests in the test suite are run in a single GitHub Actions workflow called "Continuous Integration". The steps are defined in integration.yml and are split into two types of jobs:

    1. Ubuntu/macOS/Windows JDK 8 (mainbuild): Runs both unit tests and system tests on JDK 1.8 running on supported Ubuntu, macOS and Windows versions. For Ubuntu, this job also produces a RepoSense report and the MarkBind documentation website for previewing.
    2. Cypress frontend tests (cypress): Runs only the frontend tests on JDK 1.8 running on Ubuntu.

    The list of supported OS versions are available on the GitHub Docs website. These jobs should be updated regularly whenever RepoSense supports newer versions of the Java Development Kit (JDK) as well as when new OS versions are made available (via the job OS matrix). Frontend tests are run separately to take advantage of parallel job execution.

    Some of the jobs execute some commands that are too complicated to be included in the workflow configuration files. Such commands are written in the form of a bash script and are located in the config/gh-actions folder.

    This workflow is run for both incoming pull requests to any branch as well as direct commits to any branch in the repository.

    Cypress frontend tests are run against reports generated from config files in frontend/cypress/config. It uses the cypress branch of the RepoSense repository which is kept independent of master and should be updated only when there are new frontend tests that need to be accommodated.

    Report and documentation previews

    For each pull request to any branch in the repository, a RepoSense report and the MarkBind documentation website is generated based on the code submitted in the pull request. This is to facilitate pull request reviewers in being able to quickly preview how the RepoSense report and/or the documentation website will change after the pull request is merged.

    Due to security considerations in preventing pwn requests, the deployment of the report and documentation previews were split across two workflows in pull request #1411:

    1. Surge.sh pending build (defined in pending.yml): Used for gathering information about the pull request and update the pull request checklist to indicate that the previews are pending.
    2. Surge.sh build preview (defined in surge.yml): Used for actually deploying the RepoSense report and documentation website to Surge.sh and updating the pull request checklist to link to the preview websites.

    The previews are recognised as GitHub deployments and are named dashboard-$PRNUMBER and docs-$PRNUMBER, where $PRNUMBER is the pull request number. Once a preview is ready, the reviewer would be able to click on "View deployment" or "Show environments" in the pull request to open the preview websites.

    Both the "Surge.sh pending build" and "Continuous Integration" workflows produce an artifact respectively, which is then downloaded by the "Surge.sh build preview" workflow to be deployed to Surge.sh. Due to limitations in GitHub Actions in determining the workflow execution order, the "Surge.sh pending build" workflow is assumed to have been completed before the "Continuous Integration" workflow is completed.

    This task is not performed on commits to the repository, as there is no need to do so.

    After the pull request is closed or merged, the Surge.sh deployments are retained, while the GitHub environments for them are cleared by another workflow "Clear deployments for closed pull requests" (defined in delete-deploy.yml). The workflow uses delete-deploy.sh (found in the config/gh-actions/ folder) to remove the environments on GitHub, and to leave a comment on the pull request with links to the Surge.sh previews for later reference.

    GitHub Pages

    This task builds the MarkBind documentation website on every push to the master branch. The steps are defined in gh-pages.yml.

    Stale pull requests

    This task automates the cleaning up of the pull requests by automatically marking inactive pull requests as stale and subsequently closing them. The steps and configurations are defined in stale.yml and the job is triggered automatically once per day.

    Codecov

    Codecov is a platform for checking the code coverage status of the project and the pull request patch. It runs automatically on each pull request and the settings are located in codecov.yml.

    Surge.sh

    Surge.sh is a platform for hosting the RepoSense report and documentation preview builds. The deployment is automatically performed by the "Surge.sh build preview" job using the deploy.sh script in the config/gh-actions/ folder.

    For authentication, two secrets are stored and used in GitHub Actions:

    1. SURGE_LOGIN - Holds the email address to use for the Surge.sh account
    2. SURGE_TOKEN - Holds the secret account token generated for the above account (generated using surge token)

    The surge command automatically detects the existence of these two environment variables and use them for authentication when deploying the RepoSense report and documentation build previews.

    Currently, deployments are kept forever, even after the pull request is merged or closed. There is currently no existing functionality to automatically clean up deployments after they are no longer useful.

    +

    DevOps Guide

    This page documents the various components that form part of the DevOps infrastructure that RepoSense uses.

    GitHub Actions

    GitHub Actions is a platform that is used by RepoSense for running the test suite and is primarily used for continuous integration and testing. The test suite is stored in .github/workflows/ and comprises of:

    Continuous integration

    All three types of tests in the test suite are run in a single GitHub Actions workflow called "Continuous Integration". The steps are defined in integration.yml and are split into two types of jobs:

    1. Ubuntu/macOS/Windows JDK 8 (mainbuild): Runs both unit tests and system tests on JDK 1.8 running on supported Ubuntu, macOS and Windows versions. For Ubuntu, this job also produces a RepoSense report and the MarkBind documentation website for previewing.
    2. Cypress frontend tests (cypress): Runs only the frontend tests on JDK 1.8 running on Ubuntu.

    The list of supported OS versions are available on the GitHub Docs website. These jobs should be updated regularly whenever RepoSense supports newer versions of the Java Development Kit (JDK) as well as when new OS versions are made available (via the job OS matrix). Frontend tests are run separately to take advantage of parallel job execution.

    Some of the jobs execute some commands that are too complicated to be included in the workflow configuration files. Such commands are written in the form of a bash script and are located in the config/gh-actions folder.

    This workflow is run for both incoming pull requests to any branch as well as direct commits to any branch in the repository.

    Cypress frontend tests are run against reports generated from config files in frontend/cypress/config. It uses the cypress branch of the RepoSense repository which is kept independent of master and should be updated only when there are new frontend tests that need to be accommodated.

    Report and documentation previews

    For each pull request to any branch in the repository, a RepoSense report and the MarkBind documentation website is generated based on the code submitted in the pull request. This is to facilitate pull request reviewers in being able to quickly preview how the RepoSense report and/or the documentation website will change after the pull request is merged.

    Due to security considerations in preventing pwn requests, the deployment of the report and documentation previews were split across two workflows in pull request #1411:

    1. Surge.sh pending build (defined in pending.yml): Used for gathering information about the pull request and update the pull request checklist to indicate that the previews are pending.
    2. Surge.sh build preview (defined in surge.yml): Used for actually deploying the RepoSense report and documentation website to Surge.sh and updating the pull request checklist to link to the preview websites.

    The previews are recognised as GitHub deployments and are named dashboard-$PRNUMBER and docs-$PRNUMBER, where $PRNUMBER is the pull request number. Once a preview is ready, the reviewer would be able to click on "View deployment" or "Show environments" in the pull request to open the preview websites.

    Both the "Surge.sh pending build" and "Continuous Integration" workflows produce an artifact respectively, which is then downloaded by the "Surge.sh build preview" workflow to be deployed to Surge.sh. Due to limitations in GitHub Actions in determining the workflow execution order, the "Surge.sh pending build" workflow is assumed to have been completed before the "Continuous Integration" workflow is completed.

    This task is not performed on commits to the repository, as there is no need to do so.

    After the pull request is closed or merged, the Surge.sh deployments are retained, while the GitHub environments for them are cleared by another workflow "Clear deployments for closed pull requests" (defined in delete-deploy.yml). The workflow uses delete-deploy.sh (found in the config/gh-actions/ folder) to remove the environments on GitHub, and to leave a comment on the pull request with links to the Surge.sh previews for later reference.

    GitHub Pages

    This task builds the MarkBind documentation website on every push to the master branch. The steps are defined in gh-pages.yml.

    Stale pull requests

    This task automates the cleaning up of the pull requests by automatically marking inactive pull requests as stale and subsequently closing them. The steps and configurations are defined in stale.yml and the job is triggered automatically once per day.

    Codecov

    Codecov is a platform for checking the code coverage status of the project and the pull request patch. It runs automatically on each pull request and the settings are located in codecov.yml.

    Surge.sh

    Surge.sh is a platform for hosting the RepoSense report and documentation preview builds. The deployment is automatically performed by the "Surge.sh build preview" job using the deploy.sh script in the config/gh-actions/ folder.

    For authentication, two secrets are stored and used in GitHub Actions:

    1. SURGE_LOGIN - Holds the email address to use for the Surge.sh account
    2. SURGE_TOKEN - Holds the secret account token generated for the above account (generated using surge token)

    The surge command automatically detects the existence of these two environment variables and use them for authentication when deploying the RepoSense report and documentation build previews.

    Currently, deployments are kept forever, even after the pull request is merged or closed. There is currently no existing functionality to automatically clean up deployments after they are no longer useful.

    @@ -17,7 +17,7 @@

    Developer guide

    Contributing

    Thank you for your interest in contributing to RepoSense! We welcome PRs, especially from students.

    Here is a quick overview of how to get started.

    1. Set up the project on your computer (see the Setting up page)
    2. Learn the basics of the required background knowledge (see the Learning Basics page)
    3. Learn our workflow (see the Workflow page)
    4. Submit PRs as per the workflow. If you encounter any problems, post in our issue tracker.

    To gain a more solid understanding of the project implementation and workflow, you may want to start by working on issues that are suitable for first timers.

    We look forward to your PR. Happy coding!

    +

    Developer guide

    Contributing

    Thank you for your interest in contributing to RepoSense! We welcome PRs, especially from students.

    Here is a quick overview of how to get started.

    1. Set up the project on your computer (see the Setting up page)
    2. Learn the basics of the required background knowledge (see the Learning Basics page)
    3. Learn our workflow (see the Workflow page)
    4. Submit PRs as per the workflow. If you encounter any problems, post in our issue tracker.

    To gain a more solid understanding of the project implementation and workflow, you may want to start by working on issues that are suitable for first timers.

    We look forward to your PR. Happy coding!

    @@ -18,8 +18,8 @@

    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 8.

    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.

    +
  • 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.

    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.

    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.

    Step 2 Learn the RepoSense frontend architecture

    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.

    @@ -20,7 +20,7 @@

    Project management

    This page contains information about project management tasks. The target audience is senior developers (and above).

    Merging PRs

    Making a release on GitHub

    Before making a release, please check the following prerequisites:

    To make a release for RepoSense on GitHub, please follow the Creating a release section in the GitHub Docs.

    Take note of the following when making the release according to the above guide:

    After making the release, please also remember to deploy the production website using the deploy guide.

    Deploying the production website

    We have two versions of the website:

    1. Production website at https://reposense.org
      • matches the latest released version
      • deployed manually after each new release
    2. Dev website at https://reposense.org/RepoSense
      • matches the latest master branch
      • deployed automatically by Travis whenever the master branch is updated

    The production website differs from the dev website in some ways, e.g.,

    MarkBind mainly manages these variations via the site.config file. That is why the site.config file in the release branch is slightly different from the one in the master branch.

    After each release, do the following steps to deploy the production website:

    1. Switch to the release branch
    2. cd docs
    3. markbind build
    4. markbind deploy (make sure you have the push access to https://github.com/reposense/reposense.github.io)
    5. After a few minutes, check https://reposense.org to ensure it has been updated as intended.

    Hot patching after the release

    If critical bugs are found in the release, take the following steps to hot patch it:

    1. Switch to the release branch.
    2. Implement the fixes, commit them, and create a pull request from your forked release branch to the upstream release branch.
    3. After merging, release a new version of RepoSense with the release branch according to the above guide.
    4. Merge the release branch back into the master branch by creating a separate pull request.
    +
    1. Switch to the release branch.
    2. In the terminal, change the directory to the project root directory.
    3. Run gradlew --version to check that the JDK version is 1.8.0.
    4. Run gradlew shadowJar, and the Jar file will be generated at {buildDir}/jar/.
    5. Check that the Jar file is working. You may need to check that the report can be generated from the Jar file both locally and remotely by following the Generating Reports Guide.

    After making the release, please also remember to deploy the production website using the deploy guide.

    Deploying the production website

    We have two versions of the website:

    1. Production website at https://reposense.org
    2. Dev website at https://reposense.org/RepoSense

    The production website differs from the dev website in some ways, e.g.,

    MarkBind mainly manages these variations via the site.config file. That is why the site.config file in the release branch is slightly different from the one in the master branch.

    After each release, do the following steps to deploy the production website:

    1. Switch to the release branch
    2. cd docs
    3. markbind build
    4. markbind deploy (make sure you have the push access to https://github.com/reposense/reposense.github.io)
    5. After a few minutes, check https://reposense.org to ensure it has been updated as intended.

    Hot patching after the release

    If critical bugs are found in the release, take the following steps to hot patch it:

    1. Switch to the release branch.
    2. Implement the fixes, commit them, and create a pull request from your forked release branch to the upstream release branch.
    3. After merging, release a new version of RepoSense with the release branch according to the above guide.
    4. Merge the release branch back into the master branch by creating a separate pull request.
    @@ -20,7 +20,7 @@

    HTML report

    The report's source files are located in frontend/src and are built by vue-cli before being packaged into the JAR file to be extracted as part of the report.

    Vue (pronounced /vjuː/, like view) is a progressive framework for building user interfaces. It is heavily utilized in the report to update the information in the various views dynamically. (Style guide available here, Developer tool available here). Vue lifecycle hooks are the defined methods that get executed in a particular stage of the Vue object lifespan. The following is the Vue lifecycle diagram taken from here indicating the hook sequence: vue lifecycle diagram

    The following is a snapshot of the report: report screenshot

    Report architecture

    The main Vue object (app.vue) is responsible for loading the report via an async call to api.ts, which parses summary.json. Its repos attribute is tied to the global window.REPOS, and is passed into the various other modules when the information is needed.

    The report interface is broken down into two main parts

    The summary view acts as the main report, which shows the various calculations.
    -The tabbed interface is responsible for loading various modules such as authorship and zoom to display additional information.

    Typescript and Vue files

    JSON report files

    App (app.vue)

    This contains the logic for the main VueJS object, app.vue, which is the entry point for the web application.

    Vuex in store.ts is used to pass the necessary data into the relevant modules.

    c-home, c-widget, c-summary, c-authorship, c-zoom, c-segment, and c-ramp are components embedded into the report and will render the corresponding content based on the data passed into it from Vuex.

    Loading of report information

    The main Vue object depends on the summary.json data to determine the right commits.json files to load into memory. This is handled by api.ts, which loads the relevant file information from the network files if available; otherwise, a report archive, archive.zip, has to be used.

    Once the relevant commit.json files are loaded, all the repo information will be passed into c-summary to be loaded in the summary view as the relevant ramp charts.

    Activating additional view modules

    Most activity or actions should happen within the module itself, but in the case where there is a need to spawn or alter the view of another module, an event is emitted from the first module to the Vuex store, which then handles the data received and passes it along to the relevant modules.

    Other than the global main Vue object, another global variable we have is the window.hashParams. This object is responsible for generating the relevant permalink for a specific view of the report's summary module.

    Data loader (api.ts)

    This is the module that is in charge of loading and parsing the data files generated as part of the report.

    Loading from ZIP file

    Due to security design, most modern browsers (e.g., Chrome) do not allow web pages to obtain local files using the directory alone. As such, a ZIP archive of the report information will be produced alongside the report generation.

    This archive will be used in place of the network files to load information into the report when the network files are unavailable.

    The API module will be handling all requests for all the JSON data files. If the network file is not available, the files will be obtained from the zip archive provided.

    Retrieving and parsing information

    After the JSON files are loaded from their respective sources, the data will be parsed as objects and included inside the global storage object, window.REPOS, in the right format.

    For the basic skeleton of window.REPOS, refer to the generated summary.json file in the report for more details.

    Home view (c-home.vue)

    The c-home module is in charge of rendering the main report, and renders c-resizer, c-summary, c-authorship and c-zoom.

    Widget view (c-widget.vue)

    The c-widget module is in charge of rendering the widget from the iframe and only renders c-summary. An additional prop, isWidgetMode, is passed to c-summary so it knows to render as a widget and omit unnecessary elements.

    Summary view (c-summary.vue)

    The c-summary module is in charge of loading the ramp charts from the corresponding commits.json.

    Initializing the data for the ramp charts

    The summary module is activated after the information is loaded from the main Vue.JS object. At creation, the repo attribute is populated with the window.REPOS object, which contains information loaded from summary.json.

    Filtering users and repositories

    The commits information is retrieved from the corresponding project folders for each repository. This information will be filtered and sorted before being passed into the template to be displayed as ramp charts.

    Authorship view (c-authorship.vue)

    The authorship module retrieves the relevant information from the corresponding authorship.json file if it is not yet loaded. If it has been loaded, the data will be written into window.REPOS and be read from there instead.

    Showing relevant information by authors

    The files will be filtered, picking only files the selected author has written in. The lines are then split into chunks of "touched" and "untouched" code segments displayed in the tab view which will be popped up on the right side of the screen.

    Zoom view (c-zoom.vue)

    The c-zoom module is in charge of filtering and displaying the commits from the ramp chart's selected sub-range.

    Ramp view (c-ramp.vue)

    The c-ramp module is responsible for receiving the relevant information from c-summary and generating ramp charts that contain ramp slices.

    Padding for dates

    For ramps between the date ranges, the slices will be selected and it will be pre and post padded with empty slices to align the ramp slice between the sinceDate and untilDate. The ramps will then be rendered with the slices in the right position.

    Segment view (c-segment.vue)

    The c-segment module is used as a component in c-authorship. It separates the code in terms of "touched" and "untouched" segments and only loads each "untouched" segment when it is toggled.

    +The tabbed interface is responsible for loading various modules such as authorship and zoom to display additional information.

    Typescript and Vue files

    JSON report files

    App (app.vue)

    This contains the logic for the main VueJS object, app.vue, which is the entry point for the web application.

    Vuex in store.ts is used to pass the necessary data into the relevant modules.

    c-home, c-widget, c-summary, c-authorship, c-zoom, c-segment, and c-ramp are components embedded into the report and will render the corresponding content based on the data passed into it from Vuex.

    Loading of report information

    The main Vue object depends on the summary.json data to determine the right commits.json files to load into memory. This is handled by api.ts, which loads the relevant file information from the network files if available; otherwise, a report archive, archive.zip, has to be used.

    Once the relevant commit.json files are loaded, all the repo information will be passed into c-summary to be loaded in the summary view as the relevant ramp charts.

    Activating additional view modules

    Most activity or actions should happen within the module itself, but in the case where there is a need to spawn or alter the view of another module, an event is emitted from the first module to the Vuex store, which then handles the data received and passes it along to the relevant modules.

    Other than the global main Vue object, another global variable we have is the window.hashParams. This object is responsible for generating the relevant permalink for a specific view of the report's summary module.

    Data loader (api.ts)

    This is the module that is in charge of loading and parsing the data files generated as part of the report.

    Loading from ZIP file

    Due to security design, most modern browsers (e.g., Chrome) do not allow web pages to obtain local files using the directory alone. As such, a ZIP archive of the report information will be produced alongside the report generation.

    This archive will be used in place of the network files to load information into the report when the network files are unavailable.

    The API module will be handling all requests for all the JSON data files. If the network file is not available, the files will be obtained from the zip archive provided.

    Retrieving and parsing information

    After the JSON files are loaded from their respective sources, the data will be parsed as objects and included inside the global storage object, window.REPOS, in the right format.

    For the basic skeleton of window.REPOS, refer to the generated summary.json file in the report for more details.

    Home view (c-home.vue)

    The c-home module is in charge of rendering the main report, and renders c-resizer, c-summary, c-authorship and c-zoom.

    Widget view (c-widget.vue)

    The c-widget module is in charge of rendering the widget from the iframe and only renders c-summary. An additional prop, isWidgetMode, is passed to c-summary so it knows to render as a widget and omit unnecessary elements.

    Summary view (c-summary.vue)

    The c-summary module is in charge of loading the ramp charts from the corresponding commits.json.

    Initializing the data for the ramp charts

    The summary module is activated after the information is loaded from the main Vue.JS object. At creation, the repo attribute is populated with the window.REPOS object, which contains information loaded from summary.json.

    Filtering users and repositories

    The commits information is retrieved from the corresponding project folders for each repository. This information will be filtered and sorted before being passed into the template to be displayed as ramp charts.

    Authorship view (c-authorship.vue)

    The authorship module retrieves the relevant information from the corresponding authorship.json file if it is not yet loaded. If it has been loaded, the data will be written into window.REPOS and be read from there instead.

    Showing relevant information by authors

    The files will be filtered, picking only files the selected author has written in. The lines are then split into chunks of "touched" and "untouched" code segments displayed in the tab view which will be popped up on the right side of the screen.

    Zoom view (c-zoom.vue)

    The c-zoom module is in charge of filtering and displaying the commits from the ramp chart's selected sub-range.

    Ramp view (c-ramp.vue)

    The c-ramp module is responsible for receiving the relevant information from c-summary and generating ramp charts that contain ramp slices.

    Padding for dates

    For ramps between the date ranges, the slices will be selected and it will be pre and post padded with empty slices to align the ramp slice between the sinceDate and untilDate. The ramps will then be rendered with the slices in the right position.

    Segment view (c-segment.vue)

    The c-segment module is used as a component in c-authorship. It separates the code in terms of "touched" and "untouched" segments and only loads each "untouched" segment when it is toggled.

    @@ -17,7 +17,7 @@

    Setting up

    Prerequisites:

    • JDK 1.8.0_60 up to 17 (download ).

    • Node.js 16.19.1 to the latest minor version for 18 (download ).

    • git 2.23 or later (download ).

      Type java -version, node -v and git --version respectively on your OS terminal and ensure that you have the correct version of each prerequisite installed.

    Getting the code

    1. Fork the reposense/reposense repo.
    2. Clone the fork to your computer.

    Setting up the IDE

    The recommended IDE is Intellij IDEA. While it is not compulsory to use it, note that we will not be able to help you troubleshoot IDE problems if you use any other IDE.

    1. Ensure you have configured IDEA for the correct JDK, as explained in this tutorial.
    2. Import the project as a Gradle project, as explained in this tutorial.

    Verifying the setup

    This project is already configured to use Gradle for build automation. If you are new to Gradle, see this tutorial to learn how to use it.

    1. Open a command prompt and navigate to the project root.
    2. Run gradlew clean build (./gradlew clean build if you on a Unix-like OS), and ensure that it finishes with a BUILD SUCCESSFUL message.
    3. Run the tests using the gradlew test systemtest command and ensure it succeeds too.
    4. You can also try running the app using code, as given in the panel below.

    Before you start coding

    ... read the Workflow section.

    +

    Setting up

    Prerequisites:

    Getting the code

    1. Fork the reposense/reposense repo.
    2. Clone the fork to your computer.

    Setting up the IDE

    The recommended IDE is Intellij IDEA. While it is not compulsory to use it, note that we will not be able to help you troubleshoot IDE problems if you use any other IDE.

    1. Ensure you have configured IDEA for the correct JDK, as explained in this tutorial.
    2. Import the project as a Gradle project, as explained in this tutorial.

    Verifying the setup

    This project is already configured to use Gradle for build automation. If you are new to Gradle, see this tutorial to learn how to use it.

    1. Open a command prompt and navigate to the project root.
    2. Run gradlew clean build (./gradlew clean build if you on a Unix-like OS), and ensure that it finishes with a BUILD SUCCESSFUL message.
    3. Run the tests using the gradlew test systemtest command and ensure it succeeds too.
    4. You can also try running the app using code, as given in the panel below.

    Before you start coding

    ... read the Workflow section.

    @@ -131,7 +131,7 @@ class Foo { name: string; } - + @@ -18,14 +18,14 @@

    Workflow

    Our workflow is mostly based on the guidelines given at se-education.org/guides.

    To submit a PR, follow this guide, but note the following:

    • As we squash the commits when merging a PR, there is no need to follow a strict commit organization or write elaborate commit messages for each commit.
      -However, when pushing new commits to your PR branch, do clean up new commits (i.e., commits not yet pushed) e.g., delete temporary print statements added for debugging purposes.
    • In the PR description, please propose a commit message to be used when the PR is merged eventually. The commit message should follow the guidelines given here. You may refer to this PR for an example.
    • For simple documentation fixes or tasks with clear instructions, it is unnecessary to create an issue before creating a PR.
    • You can refer to the Architecture and the HTML Report sections to learn about the design and implementation of RepoSense.
    • The section below has more information about the various stages of submitting a PR.

    Find the suitable pull requests

    The issues for first timers usually have guidance provided in the comment or have linked pull requests from previous contributors. You can refer to them for implementation details.

    • If you are more experienced in contributing, aside from searching for issues in the issue tracker, you can find the list of issues organized in a more systematic way under the Projects Tab of the RepoSense repository. This can help you to find issues with suitable workload and direction.

    Following the coding standards

    • Make sure you know our coding standards.

    • Follow the tutorial to configure Intellij to follow our coding style.
    • This project uses Checkstyle to check the compliance of Java code. You can use this document to find how to use it. +However, when pushing new commits to your PR branch, do clean up new commits (i.e., commits not yet pushed) e.g., delete temporary print statements added for debugging purposes.
    • In the PR description, please propose a commit message to be used when the PR is merged eventually. The commit message should follow the guidelines given here. You may refer to this PR for an example.
    • For simple documentation fixes or tasks with clear instructions, it is unnecessary to create an issue before creating a PR.
    • You can refer to the Architecture and the HTML Report sections to learn about the design and implementation of RepoSense.
    • The section below has more information about the various stages of submitting a PR.

    Find the suitable pull requests

    The issues for first timers usually have guidance provided in the comment or have linked pull requests from previous contributors. You can refer to them for implementation details.

    • If you are more experienced in contributing, aside from searching for issues in the issue tracker, you can find the list of issues organized in a more systematic way under the Projects Tab of the RepoSense repository. This can help you to find issues with suitable workload and direction.

    Following the coding standards

    • Make sure you know our coding standards.

    • Follow the tutorial to configure Intellij to follow our coding style.
    • This project uses Checkstyle to check the compliance of Java code. You can use this document to find how to use it.
      • In particular, run gradlew checkstyleAll to check the style of all the relevant Java code. This will check the Java code in the following order: main code -> test code -> systemtest code.
      • If you only want to check the main code, run gradlew checkstyleMain. Likewise, for test code, run gradlew checkstyleTest and for systemtest code, run gradlew checkstyleSystemtest.
      • You can also run any of the combination of the above, such as gradlew checkstyleMain checkstyleTest or gradlew checkstyleTest checkstyleSystemtest.
    • To check Vue files for style errors, run gradlew lintFrontend from the project root directory. You can also run npm run lintfix in the frontend folder to automatically fix some of the JavaScript and CSS lint errors.
    • To perform environmental checks for style errors, run gradlew environmentalChecks from the project root directory. This checks if all files end with a newline, if prohibited line endings (\r\n) are present and if trailing whitespaces are present.

    Running the app from code

    • To run the app from code, run gradlew run from the project root. By default, it will run based on the config files in the [project root]/config folder, and generate the report in the [project root]/reposense-report folder.
    • To supply flags to customize the report, you can use the -Dargs="[FLAGS]" format.
      -e.g., gradlew run -Dargs="--since 31/12/2019 --formats java adoc xml"
    • Run gradlew run -Dargs="--view" to generate the report and view it in the default browser.
    • You can refer to the panel below for the format of the flags that can be supplied in -Dargs="[FLAGS]".

    Debugging (front-end)

    You can use the hot reloading feature to see how your code changes the functionality of the website in real time.

    1. Navigate to the project root in your terminal.
    2. Generate the desired data for the report using gradlew run with the appropriate flags.
    3. Run gradlew hotReloadFrontend.
    4. The website will be automatically opened in your browser shortly.

    You can use Vue.js devtools for frontend debugging on Chrome. Here are the steps:

    1. On your Chrome, visit the website of Vue.js devtools and add the extension.
    2. Go to the detail page of this extension in Chrome's extension management panel and select Allow access to file URLs. If you are unable to locate it, copy the link: chrome://extensions/?id=nhdogjmejiglipccpnnnanhbledajbpd and visit it on your Chrome.
    3. Open any report generated by RepoSense.
    4. Press F12 or right click and choose inspect at the report page.
    5. Choose Vue at the navigation bar.
      Choose Vue
    6. Debug using the tool.
      Use Vue

    See vue-devtools project home page for more details.

    Testing (front-end)

    We use Cypress for automated end-to-end front-end testing.

    Writing tests

    1. Create a new test file in frontend/cypress/tests.
    2. At project root start Cypress Test Runner by running gradlew cypress.
    3. Select E2E Testing and choose Chrome as the preferred browser. +e.g., gradlew run -Dargs="--since 31/12/2019 --formats java adoc xml"
    4. Run gradlew run -Dargs="--view" to generate the report and view it in the default browser.
    5. You can refer to the panel below for the format of the flags that can be supplied in -Dargs="[FLAGS]".

    Debugging (front-end)

    You can use the hot reloading feature to see how your code changes the functionality of the website in real time.

    1. Navigate to the project root in your terminal.
    2. Generate the desired data for the report using gradlew run with the appropriate flags.
    3. Run gradlew hotReloadFrontend.
    4. The website will be automatically opened in your browser shortly.

    You can use Vue.js devtools for frontend debugging on Chrome. Here are the steps:

    1. On your Chrome, visit the website of Vue.js devtools and add the extension.
    2. Go to the detail page of this extension in Chrome's extension management panel and select Allow access to file URLs. If you are unable to locate it, copy the link: chrome://extensions/?id=nhdogjmejiglipccpnnnanhbledajbpd and visit it on your Chrome.
    3. Open any report generated by RepoSense.
    4. Press F12 or right click and choose inspect at the report page.
    5. Choose Vue at the navigation bar.
      Choose Vue
    6. Debug using the tool.
      Use Vue

    See vue-devtools project home page for more details.

    Testing (front-end)

    We use Cypress for automated end-to-end front-end testing.

    Writing tests

    1. Create a new test file in frontend/cypress/tests.
    2. At project root start Cypress Test Runner by running gradlew cypress.
    3. Select E2E Testing and choose Chrome as the preferred browser. Cypress Test E2E Cypress Test Chrome
    4. Under E2E specs, click on the newly created test file to run it. Cypress Test Runner

    Read Cypress's Documentation to familiarize yourself with its syntax and Cypress's debugging guide to tackle problems with your tests.

    Note that it is compulsory to add tests for the new front-end changes that you made to prevent regression bugs, except for trivial changes that are unlikely to cause any regression or other situations where testing does not apply to the change.

    Running tests

    To run all tests locally, run gradlew frontendTest.

    If you encountered an invalid browser error, ensure that you have Chrome installed in the default installation directory. Otherwise, follow the instructions here to create symbolic links so Cypress can locate Chrome in your system.

    Testing (back-end)

    The back-end tests can be found at [project root]/systemtest and [project root]/test.

    Running tests

    To run all the system tests, run gradlew systemtest.

    To run all the unit and integration tests, run gradlew test.

    Writing documentation

    This project uses MarkBind for documentation. Follow this tutorial to learn how to use MarkBind for updating project documentation.

    To show some content only in the , add the tags="production" attribute to the HTML element enclosing the content. Similarly, tags="dev" will make the content appear only in the .

    <span tags="production">This will appear in the production website only.</span>
 <span tags="dev">This will appear in the dev website only.</span>
 This will appear in both sites.
-
    + @@ -18,7 +18,7 @@

    RepoSense

    Visualize programmer activities across git repositories... -

    RepoSense overview

    RepoSense can generate interactive visualizations of programmer activities, even across multiple repositories. It's ideal for educators and managers to get insights into the programming activities of their mentees. The visualizations can be easily shared with others (e.g., as an online dashboard), and updating the visualizations periodically can be automated.

    Some example insights RepoSense can provide:

    Insights about the code

    • Which part of the code was written by Tom? How many lines? How many files?
    • Which test cases were written by Kim?
    • Which commit messages were written by Serene?

    Insights about the type of work

    • Which portion of Jacob's code is documentation?
    • Who hasn't written any test code yet?
    • Which project did Jolene contribute to in the last month?

    Insights about the timing of work

    • Who is putting in the consistent effort?
    • Who waits till the deadline to do the work?
    • Who hasn't started any work yet?

    Insights based on comparisons

    • Which programmers/teams are falling behind?
    • How does everyone compare in their front-end coding work over the past two weeks?
    • Who are the top 10 code contributors?

    SHOWCASE of use cases

    ABOUT us

    CONTACT us

    GitHub

    This website was built using MarkBind.

    Deploy previews are powered by Netlify and Surge.

    USER GUIDE

    DEVELOPER GUIDE

    +

    RepoSense overview

    RepoSense can generate interactive visualizations of programmer activities, even across multiple repositories. It's ideal for educators and managers to get insights into the programming activities of their mentees. The visualizations can be easily shared with others (e.g., as an online dashboard), and updating the visualizations periodically can be automated.

    Some example insights RepoSense can provide:

    Insights about the code

    Insights about the type of work

    Insights about the timing of work

    Insights based on comparisons

    SHOWCASE of use cases

    ABOUT us

    CONTACT us

    GitHub

    This website was built using MarkBind.

    Deploy previews are powered by Netlify and Surge.

    USER GUIDE

    DEVELOPER GUIDE

    @@ -17,7 +17,7 @@

    Showcase

    Case 1: Monitoring student programmers (individual projects)

    • Scenario: RepoSense is used to monitor a Software Engineering course in which students build a project over 8 weeks.

    • Links: report | repo containing the settings

    • Example usages:

      • To compare students based on the amount of code written, we can sort by contribution, as done in this view.
      • This view shows us code written by a specific student.

    Case 2: Monitoring student programmers (team projects)

    • Scenario: Similar to case 1 above, but this time students are doing team projects.

    • Links: report | settings

    • Example usages:

      • To find the breakdown of the work done, we can tick the breakdown by file type checkbox, as shown in this view. After that, we can filter out certain file types by un-ticking the file type.
      • To find how teams compare in terms of total work done, we can tick the merge all groups check-box and sort groups by Contribution, as seen in this view. Also, note how to reduce clutter.
      • This view shows the activities near the submission deadline of 8 November 2021 (note how some have overshot the deadline and some others show a frenzy of activities very near to the deadline).

    Case 3: Monitoring student programmers (multiple external projects)

    • Scenario: Similar to cases 1 and 2 above, but this time, each student works on multiple projects. Furthermore, most projects are external OSS projects, not within the control of the teacher.

    • Links: report | settings

    • Example usages:

      • This view shows the commit messages written by a specific student.
      • Note how we can use the group by drop-down to organize activities around projects or individual authors.
      • Similarly, we can use the merge all groups check-box to see the sum of activities in a specific project or by a specific student.
    +

    Showcase

    Case 1: Monitoring student programmers (individual projects)

    Case 2: Monitoring student programmers (team projects)

    Case 3: Monitoring student programmers (multiple external projects)

    @@ -17,7 +17,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: author-config.csv advanced syntax

    Given below are the advanced syntax available for author-config.csv.

    Multiple Repository's Location per author

    Specifying multiple Repository's Location

    To specify multiple Repository's Location in a single row, we can use a semicolon ; as a separator.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense.git;https://github.com/MarkBind/markbind.git master sikai00 --

    We have now furnished author details for both repositories in a single row, instead of having two individual rows per Repository's Location.


    Specifying Repository's Location with one or more specific branches

    To list out one or more branches for a particular Repository's Location, we can use a pipe | separator to demarcate the different branches.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense.git~master|release|cypress master sikai00 --

    We have now provided author details for three different branches in a single repo, using a single row.

    The branch specified through the delimiter syntax will take precedence over the Branch column.

    Using GitHub branch URL as Repository's Location

    We can also use GitHub branch URL as copied from the address bar directly, to be able to quickly use the URL to specify the Repository's Location and a specific Branch at the same time.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense/tree/release sikai00 --

    There is no need to specify the Branch column now, as we have specified it through the GitHub branch URL.

    GitLab and BitBucket branch URL are not supported at the moment.

    Combining the advanced syntax

    It is possible to combine the above-mentioned advanced syntax. By doing so, we can go from:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/MarkBind/markbind/tree/vue3-migration sikai00 --
    https://github.com/reposense/RepoSense.git master sikai00 --
    https://github.com/reposense/RepoSense.git cypress sikai00 --

    to:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/MarkBind/markbind/tree/vue3-migration;https://github.com/reposense/RepoSense.git~master|cypress sikai00 --

    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: author-config.csv advanced syntax

    Given below are the advanced syntax available for author-config.csv.

    Multiple Repository's Location per author

    Specifying multiple Repository's Location

    To specify multiple Repository's Location in a single row, we can use a semicolon ; as a separator.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense.git;https://github.com/MarkBind/markbind.git master sikai00 --

    We have now furnished author details for both repositories in a single row, instead of having two individual rows per Repository's Location.


    Specifying Repository's Location with one or more specific branches

    To list out one or more branches for a particular Repository's Location, we can use a pipe | separator to demarcate the different branches.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense.git~master|release|cypress master sikai00 --

    We have now provided author details for three different branches in a single repo, using a single row.

    The branch specified through the delimiter syntax will take precedence over the Branch column.

    Using GitHub branch URL as Repository's Location

    We can also use GitHub branch URL as copied from the address bar directly, to be able to quickly use the URL to specify the Repository's Location and a specific Branch at the same time.

    Below is an example:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/reposense/RepoSense/tree/release sikai00 --

    There is no need to specify the Branch column now, as we have specified it through the GitHub branch URL.

    GitLab and BitBucket branch URL are not supported at the moment.

    Combining the advanced syntax

    It is possible to combine the above-mentioned advanced syntax. By doing so, we can go from:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/MarkBind/markbind/tree/vue3-migration sikai00 --
    https://github.com/reposense/RepoSense.git master sikai00 --
    https://github.com/reposense/RepoSense.git cypress sikai00 --

    to:

    Repository's Location Branch Author's Git Host ID ... Hidden columns
    https://github.com/MarkBind/markbind/tree/vue3-migration;https://github.com/reposense/RepoSense.git~master|cypress sikai00 --

    @@ -27,7 +27,7 @@ Default: one month before the current date
  • Alias: -s
  • Example:--since 21/10/2017 or -s 21/10/2017
    • If the start date is not specified, only commits made one month before the end date (if specified) or the date of generating the report, will be captured and analyzed.
    • If d1 is specified as the start date (--since d1 or -s d1), then the program will search for the earliest commit date of all repositories and use that as the start date.
    • If d1 is specified together with --period, then the program will warn that the date range being analyzed may be incorrect.

    --timezone, -t

    --timezone ZONE_ID: Indicates the timezone to be used for the analysis.

    --until, -u

    --until END_DATE: Specifies the end date of the analysis period.

    Note: If the end date is not specified, the date of generating the report will be taken as the end date.

    --version, -V

    --version: Shows the version of RepoSense.

    Cannot be used with any other flags. This flag takes precedence over all other flags other than --help.

    --view, -v

    --view [REPORT_FOLDER]: Specifies that the report should be opened in the default browser.

    +Default: ./reposense-report
  • Alias: -v
  • Example:--view or -v
    • @@ -21,7 +21,7 @@ The Shallow Cloning option is incompatible with the "--last-modified-date" CLI flag.
    If Ignore File Size Limit is yes, the File Size Limit and Skip Ignored File Analysis columns are ignored. -

    * Multi-value column: multiple values can be entered in this column using a semicolon ; as the separator.
    + Overrideable column: prepend with override: to use entered value(s) instead of value(s) from standalone config.

    When using standalone config (if it is not ignored), it is possible to override specific values from the standalone config by prepending the entered value with override:.

    author-config.csv

    Optionally, you can use an author-config.csv (which should be in the same directory as the repo-config.csv file) to provide more details about the authors to analyze (example). It should contain the following columns:

    Column Name Explanation
    Repository's Location* Same as repo-config.csv. Default: all the repos in repo-config.csv.
    Branch The branch to analyze for this author, e.g., master. Default: the author will be bound to all the repos in repo-config.csv that has the same repo's location, regardless of branch.
    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.
    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.
    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.
    # For backward compatibility, Author's GitHub ID is still accepted as the header in place of Author's Git Host ID.

    If author-config.csv is not given and the repo has not provided author details in a standalone config file, all the authors of the repositories within the date range specified (if any) will be analyzed.

    author-config.csv has some advanced syntax that can help to reduce duplication of the author's information. The syntax guide is given below:

    group-config.csv

    Optionally, you can provide a group-config.csv(which should be in the same directory as repo-config.csv file) to provide details on any custom groupings for files in specified repositories (example). It should contain the following columns:

    Column Name Explanation
    Repository's Location Same as repo-config.csv. Default: all the repos in repo-config.csv
    Group Name mandatory Name of the group, e.g.,test.
    Globs * mandatory The list of file path globs to include for specified group, e.g.,**/test/*;**.java.

    * Multi-value column: multiple values can be entered in this column using a semicolon ; as the separator.

    Note that a file in a given repository should only be tagged to one group.
    +

    * Multi-value column: multiple values can be entered in this column using a semicolon ; as the separator.
    + Overrideable column: prepend with override: to use entered value(s) instead of value(s) from standalone config.

    When using standalone config (if it is not ignored), it is possible to override specific values from the standalone config by prepending the entered value with override:.

    author-config.csv

    Optionally, you can use an author-config.csv (which should be in the same directory as the repo-config.csv file) to provide more details about the authors to analyze (example). It should contain the following columns:

    Column Name Explanation
    Repository's Location* Same as repo-config.csv. Default: all the repos in repo-config.csv.
    Branch The branch to analyze for this author, e.g., master. Default: the author will be bound to all the repos in repo-config.csv that has the same repo's location, regardless of branch.
    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.
    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.
    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.
    # For backward compatibility, Author's GitHub ID is still accepted as the header in place of Author's Git Host ID.

    If author-config.csv is not given and the repo has not provided author details in a standalone config file, all the authors of the repositories within the date range specified (if any) will be analyzed.

    author-config.csv has some advanced syntax that can help to reduce duplication of the author's information. The syntax guide is given below:

    group-config.csv

    Optionally, you can provide a group-config.csv(which should be in the same directory as repo-config.csv file) to provide details on any custom groupings for files in specified repositories (example). It should contain the following columns:

    Column Name Explanation
    Repository's Location Same as repo-config.csv. Default: all the repos in repo-config.csv
    Group Name mandatory Name of the group, e.g.,test.
    Globs * mandatory The list of file path globs to include for specified group, e.g.,**/test/*;**.java.

    * Multi-value column: multiple values can be entered in this column using a semicolon ; as the separator.

    Note that a file in a given repository should only be tagged to one group.
    e.g.: example.java in example-repo can either be in the test group or the code group, but not in both test and code group. If multiple groups are specified for a given file, the latter group (i.e., code group) is set for the file.

    report-config.json

    You can optionally use report-config.json to customize report generation by providing the following information. (example)

    Fields to provide:

    config.json (standalone config file)

    Repo owners can provide the following additional information to RepoSense using a config file that we call the standalone config file:

    To use this feature, add a _reposense/config.json to the root of your repo using the format in the example below (another example) and commit it (reason: RepoSense can see committed code only):

    {
   "ignoreGlobList": ["about-us/**", "**index.html"],
   "formats": ["html", "css"],
@@ -60,7 +60,7 @@
 To find the author name that you are currently using for your current git repository, run the following command within your git repository:
     
    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):
     
    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:
     
    git config --global user.name "YOUR_AUTHOR_NAME”
-
    RepoSense expects the Git Author Name to be the same as author's username on the Git hosting platform (GitHub, GitLab, BitBucket). If an author's Git Author Name is different from their username on the Git hosting platform, the Git Author Name needs to be specified in the standalone config file. If the author has more than one Git Author Name, multiple values can be entered too.
     
     
     
      
    Note: Symbols such as ", !, / etc. in your author name will be omitted, which may reduce the accuracy of the analysis if 2 names in the repository are approximately similar.
    +

    RepoSense expects the Git Author Name to be the same as author's username on the Git hosting platform (GitHub, GitLab, BitBucket). If an author's Git Author Name is different from their username on the Git hosting platform, the Git Author Name needs to be specified in the standalone config file. If the author has more than one Git Author Name, multiple values can be entered too.

    Note: Symbols such as ", !, / etc. in your author name will be omitted, which may reduce the accuracy of the analysis if 2 names in the repository are approximately similar.

    @@ -17,7 +17,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Customizing reports

    The report can be customized using several ways, as explained below.

    Customize using CLI flags

    The simplest approach is to provide additional flags when running RepoSense. The various flags are given in the panel below.

    Customize using CSV config files

    Another, more powerful, way to customize the report is by using dedicated config files. In this case you need to use the --config flag instead of the --repo flag when running RepoSense, as follows:

    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 ( ).

    To ensure that their PRs are correct, you can use Netlify deploy previews to preview how the report would look like after the PR has been merged. More details are in the panels below.

    Get target repos to provide more info

    If feasible, you can also customize the target repos to play well with RepoSense in the following two ways:

    1. Add a standalone config file to the repo to provide more config details to RepoSense. The format of the file is given below.

    2. To have more precise control over which code segment is attributed to which author, authors can annotate their code using @@author tags, as explained below.

    In both instances, it is necessary to commit any changes for them to be detected by 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. 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.

    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Customizing reports

    The report can be customized using several ways, as explained below.

    Customize using CLI flags

    The simplest approach is to provide additional flags when running RepoSense. The various flags are given in the panel below.

    Customize using CSV config files

    Another, more powerful, way to customize the report is by using dedicated config files. In this case you need to use the --config flag instead of the --repo flag when running RepoSense, as follows:

    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 ( ).

    To ensure that their PRs are correct, you can use Netlify deploy previews to preview how the report would look like after the PR has been merged. More details are in the panels below.

    Get target repos to provide more info

    If feasible, you can also customize the target repos to play well with RepoSense in the following two ways:

    1. Add a standalone config file to the repo to provide more config details to RepoSense. The format of the file is given below.

    2. To have more precise control over which code segment is attributed to which author, authors can annotate their code using @@author tags, as explained below.

    In both instances, it is necessary to commit any changes for them to be detected by 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. 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.

    @@ -20,7 +20,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: FAQ

    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.

    Q: How do formats work?

    A: Formats are the file extensions, which is the suffix at the end of a filename that indicates what type of file it is.
    The formats/file extensions to be analyzed by RepoSense can be specified through the standalone config file, repo-config file, and command line.

    Q: How does ignore glob list work?

    A: Glob is the pattern to specify a set of filenames with wildcard characters. Ignore glob list is the list of patterns to specify all the files in the repository which should be ignored from analysis.
    -The ignore glob list can be specified through the standalone config file, repo-config file, and author-config file.

    +The ignore glob list can be specified through the standalone config file, repo-config file, and author-config file.

    @@ -20,7 +20,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Generating a report

    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. For other types of repositories, external links are disabled.

    Generating reports locally

    1. Ensure you have the prerequisites:

      • Java 8 (JRE 1.8.0_60) or later (download ).
      • git 2.23 or later on the command line. (download ).
        run git --version in your OS terminal to confirm the version.

    2. Download the latest JAR file from our releases.

    3. Generate a report: The simplest use case for RepoSense is to generate a report for the recent history of a repo.
      command: java -jar RepoSense.jar --repos LIST_OF_REPO_URLS --view
      -Examples:

      • java -jar RepoSense.jar --repos https://github.com/reposense/RepoSense.git --view (note the .git at the end of the repo URL)
      • java -jar RepoSense.jar --repos https://github.com/reposense/RepoSense.git c:/myRepose/foo/bar --view analyzes the two specified repos (one remote, one local).

      The above commands will analyze the given repo(s) for commits done within the last month and open the report in your default Browser.

    To learn how to generate a report using , head over to the Customizing reports section.

    Generating reports remotely

    You can generate a RepoSense report remotely without installing/running anything on your computer. This is particularly useful when you are deciding whether to adopt RepoSense.

    The easiest option is to use Netlify. The instructions are given below.

    You can also use the following options. While they are more work to set up, they are more suitable as a permanent solution due to their generous free tier.

    +Examples:

    The above commands will analyze the given repo(s) for commits done within the last month and open the report in your default Browser.

    To learn how to generate a report using , head over to the Customizing reports section.

    Generating reports remotely

    You can generate a RepoSense report remotely without installing/running anything on your computer. This is particularly useful when you are deciding whether to adopt RepoSense.

    The easiest option is to use Netlify. The instructions are given below.

    You can also use the following options. While they are more work to set up, they are more suitable as a permanent solution due to their generous free tier.

    @@ -20,7 +20,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Granting write-access to a repository

    We recommend using a personal access token if aiming for the ease of setup and deploy key if aiming for enhanced security.

    If you wish to use personal access token:

    1. Create a personal access token by following this guide and give only public_repo permission.
    2. Copy the token for later use.

    If you wish to use deploy key:

    [Windows users] ssh-keygen and base64 are accessible using Git Bash.

    1. Create a public-private key pair (without a passphrase) using the ssh-keygen.
      i.e., ssh-keygen -t ecdsa -b 521 -f id_reposense -q -N ""
    2. Create a deploy key as follows:
      1. Go to the settings page of your publish-RepoSense fork
      2. Click on the Deploy keys item in the navigation menu in that page
      3. Click on the Add deploy key button and create a new deploy key with the contents of id_reposense.pub.
    3. Copy the private key in base64 encoded format for later use.
      -i.e., cat id_reposense | base64 -w 0
    +i.e., cat id_reposense | base64 -w 0 @@ -17,7 +17,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    User guide

    Welcome to the RepoSense user guide. This user guide takes you through a three-step approach to adopting RepoSense for your own use.

    In case you missed it, the overview of RepoSense is given below.

    Report: We use the term report to refer to the web-based visualization generated by RepoSense. You can also think of it as a dashboard.

    1 Explore real-life examples

    If still not entirely sure if RepoSense matches your needs, you can use the examples of real-life RepoSense reports given below to get some sense of what visualizations it produces.

    As you explore the above examples, you can refer to the following section to learn how to read and interact with those reports.

    2 Generate your own reports

    The next step is to generate your own RepoSense reports, either in your computer, or on one of the remote platforms we support.

    As you generate reports, you may need to learn how to customize those reports further.

    3 Share your reports

    Finally, you can learn how to share those reports with others, and how to automate the whole process.

    If you encounter problems at any step, you can refer to our FAQ, the troubleshooting guide, or post in our issue tracker.



    Happy RepoSensing!

    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    User guide

    Welcome to the RepoSense user guide. This user guide takes you through a three-step approach to adopting RepoSense for your own use.

    In case you missed it, the overview of RepoSense is given below.

    Report: We use the term report to refer to the web-based visualization generated by RepoSense. You can also think of it as a dashboard.

    1 Explore real-life examples

    If still not entirely sure if RepoSense matches your needs, you can use the examples of real-life RepoSense reports given below to get some sense of what visualizations it produces.

    As you explore the above examples, you can refer to the following section to learn how to read and interact with those reports.

    2 Generate your own reports

    The next step is to generate your own RepoSense reports, either in your computer, or on one of the remote platforms we support.

    As you generate reports, you may need to learn how to customize those reports further.

    3 Share your reports

    Finally, you can learn how to share those reports with others, and how to automate the whole process.

    If you encounter problems at any step, you can refer to our FAQ, the troubleshooting guide, or post in our issue tracker.



    Happy RepoSensing!

    @@ -17,7 +17,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: run.sh format

    run.sh is a script used for automating RepoSense report generation.

    Customizing the RepoSense command

    You can update the RepoSense command (i.e., the last line) in the run.sh to match your needs.

    Specifying which version of RepoSense to use

    Depending on which version you wish to use for report generation, add one of the following flags to the line ./get-reposense.py in run.sh (e.g., ./get-reposense.py --release):

    • --release: Use the latest release (Stable)
    • --master: Use the latest version of the master branch
    • --tag TAG (e.g. --tag v1.6.1): Use the version identified by the Git tag given
    • --commit COMMIT (e.g. --commit abc123): Use the version identified by the Git commit SHA given
    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: run.sh format

    run.sh is a script used for automating RepoSense report generation.

    Customizing the RepoSense command

    You can update the RepoSense command (i.e., the last line) in the run.sh to match your needs.

    Specifying which version of RepoSense to use

    Depending on which version you wish to use for report generation, add one of the following flags to the line ./get-reposense.py in run.sh (e.g., ./get-reposense.py --release):

    @@ -17,8 +17,8 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Sharing reports

    Often, you would want to share the RepoSense report with others. For example, a teacher using RepoSense for a programming class might want to share the report privately with tutors or publish it so that everyone can see it.

    The sections below explain various ways of sharing a RepoSense report.

    Share privately

    To share a RepoSense report privately, simply find a way to share the folder containing the report (by default, it will be in a folder named reposense-report). For example, you can zip that folder and share it with the intended recipients.

    You can point the recipients to the Using reports section for guidance on how to view reports.

    Publish on the web

    As RepoSense reports are in a web page format, you can publish a report by simply uploading it onto any web hosting service. Given below are several options that not only allow to publish reports, but also enable various levels of automating the entire process (e.g., automatically update the report daily).

    Embeddable Widgets

    Published reports can additionally be embedded in other websites through iframes. Simply click the clipboard icon to generate and copy the iframe for your desired section of the report for either a single ramp chart or a group of ramp charts. Paste the iframe in any HTML supported document to render it.

    A sample iframe would look like:

    <iframe src="XXX" frameborder="0" width="800px" height="XXXpx"></iframe>
-

    Adjust the width and height to the desired dimensions as required.

    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Sharing reports

    Often, you would want to share the RepoSense report with others. For example, a teacher using RepoSense for a programming class might want to share the report privately with tutors or publish it so that everyone can see it.

    The sections below explain various ways of sharing a RepoSense report.

    Share privately

    To share a RepoSense report privately, simply find a way to share the folder containing the report (by default, it will be in a folder named reposense-report). For example, you can zip that folder and share it with the intended recipients.

    You can point the recipients to the Using reports section for guidance on how to view reports.

    Publish on the web

    As RepoSense reports are in a web page format, you can publish a report by simply uploading it onto any web hosting service. Given below are several options that not only allow to publish reports, but also enable various levels of automating the entire process (e.g., automatically update the report daily).

    Embeddable Widgets

    Published reports can additionally be embedded in other websites through iframes. Simply click the clipboard icon to generate and copy the iframe for your desired section of the report for either a single ramp chart or a group of ramp charts. Paste the iframe in any HTML supported document to render it.

    A sample iframe would look like:

    <iframe src="XXX" frameborder="0" width="800px" height="XXXpx"></iframe>
+

    Adjust the width and height to the desired dimensions as required.

    @@ -21,7 +21,7 @@ Please refer to A Note About Git Author Name above on how to find out the correct author name you are using and how to change it.
    Also, ensure that you have added all author name aliases you may be using (if you are using multiple computers or have previously changed your author name).
    Alternatively, you may choose to configure RepoSense to track the email associated with your local Git config or remote Git host email in a standalone config file or author-config file, which is more accurate compared to author name aliases. For GitHub, the associated email you are using can be found in your GitHub settings.

    Contribution bar and code panel is empty (despite a non-empty ramp chart)

    The contribution bar and code panel records the lines you have authored to the latest commit of the repository and branch you are analyzing. As such, it is possible that while you have lots of committed contributions, your final authorship contribution is low. This happens if you have only deleted lines or someone else has overwritten your code and taken authorship for it (currently, RepoSense does not have the functionality to track overwritten lines).
    -It is also possible that another user has overridden the authorship of your lines using the @@author tags.

    RepoSense is not using the standalone config file in my local repository

    Ensure that you have committed the changes to your standalone config file first before running the analysis, as RepoSense is unable to detect uncommitted changes to your local repository.

    RepoSense fails on Windows (but works on Linux/Mac OS)

    Possibly, you may have some file names with special characters in them, which is disallowed in Windows OS. As such, RepoSense is unable to clone your repository fully, thus failing the analysis.

    Some file types are not shown in the file type filter even if I have included them in the file formats when generating the report

    The files of these types may be binary files. RepoSense will group binary files under one single file type binary. Common binary files include images (.jpg, .png), applications (.exe), zip files (.zip, .rar) and certain document types (.docx, .pptx).

    +It is also possible that another user has overridden the authorship of your lines using the @@author tags.

    RepoSense is not using the standalone config file in my local repository

    Ensure that you have committed the changes to your standalone config file first before running the analysis, as RepoSense is unable to detect uncommitted changes to your local repository.

    RepoSense fails on Windows (but works on Linux/Mac OS)

    Possibly, you may have some file names with special characters in them, which is disallowed in Windows OS. As such, RepoSense is unable to clone your repository fully, thus failing the analysis.

    Some file types are not shown in the file type filter even if I have included them in the file formats when generating the report

    The files of these types may be binary files. RepoSense will group binary files under one single file type binary. Common binary files include images (.jpg, .png), applications (.exe), zip files (.zip, .rar) and certain document types (.docx, .pptx).

    @@ -18,7 +18,7 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: Using @@author tags

    @@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.

    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.
    • End Tags (format: @@author): Optional. An end tag indicates the end of a code segment written by the author identified by the AUTHOR_GIT_AUTHOR_NAME of the start tag.

    If an end tag is not provided, the code till the next start tag (or the end of the file) will be attributed to the author specified in the start tag above. Use only when necessary to minimize polluting your code with these extra tags.

    If an end tag is provided without a corresponding start tag, the code until the next start tag, the next end tag, or the end of the file, will not be attributed to any author. This should only be used if the code should not be attributed to any author.

    The @@author tags should be enclosed within a single-line comment, using the comment syntax of the file in concern. Below are some examples:

    author tags

    Currently, the following comment formats are supported:

    • // @@author authorName
    • /* @@author authorName */
    • /* @@author authorName
    • # @@author authorName
    • % @@author authorName
    • <!-- @@author authorName -->
    • <!--- @@author authorName --->
    • [//]: # (@@author authorName)

    RepoSense checks whether the line matches the supported comment formats. If the line does not match the formats, -RepoSense treats it as a normal line.

    The code until the next start tag, the end tag, or the end of file will be attributed to that author.

    Note: Remember to commit the files after the changes. (reason: RepoSense can see committed code only)

    Special thanks to Collate project for providing the inspiration for this functionality.

    +RepoSense treats it as a normal line.

    The code until the next start tag, the end tag, or the end of file will be attributed to that author.

    Note: Remember to commit the files after the changes. (reason: RepoSense can see committed code only)

    Special thanks to Collate project for providing the inspiration for this functionality.

    @@ -35,7 +35,7 @@
  • Clicking the file title toggles the file content.
  • Clicking the first icon beside the file title opens the history view of the file on the remote repository.
  • Clicking the second icon beside the file title opens the blame view of the file on the remote repository.
  • When using the code panel for a specific author, code attributed to the author is highlighted in green.
  • Non-trivial code segments that the selected author has not written are hidden by default, but you can toggle them by clicking on the icon.

    • Changing binary files, such as images (.jpg, .png), applications (.exe), zip files (.zip, .rar) and certain document types (.docx, .pptx), is not counted towards the total number of lines of code contributed by an author.

    Commits panel

    commits panel

    The Commits panel allows users to see the commits attributed to a specific author.

    Opening commits panel

    + @@ -17,8 +17,8 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: RepoSense with GitHub Actions

    You can use GitHub Actions (together with other GitHub tools) to automate the generating and publishing of RepoSense reports.

    Setting up

    The instructions below assume you are using GitHub pages to host your report.

    Step 1 Fork the publish-RepoSense repository using this link. Optionally, you can rename the fork to match your RepoSense report e.g., project-code-dashboard.

    Step 2 Activate GitHub Actions on the forked repository:

    1. Go to the Actions page of your fork of the publish-RepoSense repo.
    2. Click on the green button that says I understand my workflows, go ahead and enable them to enable GitHub Actions on your new repository.

    Step 3 Update report configuration:

    In your fork, edit run.sh (and if applicable, repo-config.csv, author-config.csv, group-config.csv) to customize the command line parameters or repositories to be analyzed.

    Step 4 View the generated report:

    To access your regenerated RepoSense report, go to the settings of your fork in GitHub, under GitHub Pages section, look for Your site is published at [LINK]. It should look something like https://[YOUR_GITHUB_ID].github.io/publish-RepoSense. -GitHub Setting

    There is also a published GitHub Action (reposense-action) that can be used to generate and publish RepoSense reports. It is especially convenient for users who wish to skip the forking and setting up of a separate repository. For more information, refer to the usage description.

    Updating the report

    Manual:

    • You can trigger GitHub to re-generate and re-deploy the report by pushing an empty commit to your fork.
    • Currently, the GitHub Actions UI does not support the manual execution of workflows.

    Automated: GitHub actions can be set to run periodically.

    1. Edit the .github/workflows/main.yml and uncomment the schedule: section.
    2. You may change the expression after cron: to a schedule of your choice. Read more about cron syntax here.
    3. Commit your changes.
    +

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: RepoSense with GitHub Actions

    You can use GitHub Actions (together with other GitHub tools) to automate the generating and publishing of RepoSense reports.

    Setting up

    The instructions below assume you are using GitHub pages to host your report.

    Step 1 Fork the publish-RepoSense repository using this link. Optionally, you can rename the fork to match your RepoSense report e.g., project-code-dashboard.

    Step 2 Activate GitHub Actions on the forked repository:

    1. Go to the Actions page of your fork of the publish-RepoSense repo.
    2. Click on the green button that says I understand my workflows, go ahead and enable them to enable GitHub Actions on your new repository.

    Step 3 Update report configuration:

    In your fork, edit run.sh (and if applicable, repo-config.csv, author-config.csv, group-config.csv) to customize the command line parameters or repositories to be analyzed.

    Step 4 View the generated report:

    To access your regenerated RepoSense report, go to the settings of your fork in GitHub, under GitHub Pages section, look for Your site is published at [LINK]. It should look something like https://[YOUR_GITHUB_ID].github.io/publish-RepoSense. +GitHub Setting

    There is also a published GitHub Action (reposense-action) that can be used to generate and publish RepoSense reports. It is especially convenient for users who wish to skip the forking and setting up of a separate repository. For more information, refer to the usage description.

    Updating the report

    Manual:

    • You can trigger GitHub to re-generate and re-deploy the report by pushing an empty commit to your fork.
    • Currently, the GitHub Actions UI does not support the manual execution of workflows.

    Automated: GitHub actions can be set to run periodically.

    1. Edit the .github/workflows/main.yml and uncomment the schedule: section.
    2. You may change the expression after cron: to a schedule of your choice. Read more about cron syntax here.
    3. Commit your changes.
    @@ -22,7 +22,7 @@ Netlify Preview

    Updating the report

    Manual: Netlify UI has a way for you to trigger a build, using which you can cause the report to be updated.

    Automated: Netlify's can be set up to update the report whenever a target repo of your report is updated, provided you are able to update the target repos in a certain way.

    1. Click on Settings in the top, choose Build & deploy from the left panel and scroll to Build hooks. Build hooks

    2. Click Add build hook, give your webhook a name, and choose the master branch to build. A Netlify URL will be generated.

    3. Go to your target repository (the repository you want to analyze) and click on Settings.

    4. Select Webhooks on left panel and click on Add webhook. Add webhook

    5. Copy the Netlify URL and paste it in the URL form field. -Webhook url

      Note: Although the build url is not that secretive, it should be kept safe to prevent any misuse.

    6. Select application.json as content type.

    7. Select Let me select individual events and based on your requirements check the checkboxes.

    8. Leave the Active checkbox checked.

    9. Click on Add webhook to save the webhook and add it.

    +Webhook url

    Note: Although the build url is not that secretive, it should be kept safe to prevent any misuse.

  • Select application.json as content type.

  • Select Let me select individual events and based on your requirements check the checkboxes.

  • Leave the Active checkbox checked.

  • Click on Add webhook to save the webhook and add it.

    • @@ -17,9 +17,9 @@

    You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

    Appendix: RepoSense with Travis

    You can use the CI tool Travis to automate generating and publishing of RepoSense reports.

    Setting up

    The instructions below assume you are using GitHub pages to host your report.

    Step 1 Fork the publish-RepoSense repository using this link. Optionally, you can rename the fork to match your RepoSense report e.g., project-code-dashboard.

    Step 2 Generate a personal access token or deploy key on GitHub as explained in the panel below.

    Step 3 Login to Travis-CI. You may have to sign up first.

    Step 4 Sync your Travis account with GitHub:

    1. Go to your account.
    2. Click on Sync account to fetch all your repositories into Travis-CI.

    Step 5 Activate the repository:

    1. Go to your publish-RepoSense fork in Travis-CI
    2. Under Current tab, click on Activate repository.

    Step 6 Set the token/key:

    1. In the same page, click on More options on the right.
    2. Then, click on the Settings option:
      Travis-CI Dashboard
    3. Under Environment Variables, name a variable as GITHUB_TOKEN or GITHUB_DEPLOY_KEY depending on your earlier choice and paste the token/key into its value field; then click Add.
    4. Ensure that the Display value in build log is switched off for security reasons:
      Travis-CI Environment Variable

    Step 7 Update the report configuration:

    In your fork, edit run.sh (and if applicable, repo-config.csv, author-config.csv, group-config.csv) to customize the command line parameters or repositories to be analyzed.

    Step 8 View the generated report:

    1. Go to the Settings page of your fork in GitHub.
    2. Under the GitHub Pages section, look for Your site is published at [LINK]. It should look something like https://[YOUR_GITHUB_ID].github.io/publish-RepoSense. +

      You are looking at the user documentation for the most recent master branch of RepoSense (not released to the public yet). The documentation for the latest public release is here.

      Appendix: RepoSense with Travis

      You can use the CI tool Travis to automate generating and publishing of RepoSense reports.

      Setting up

      The instructions below assume you are using GitHub pages to host your report.

      Step 1 Fork the publish-RepoSense repository using this link. Optionally, you can rename the fork to match your RepoSense report e.g., project-code-dashboard.

      Step 2 Generate a personal access token or deploy key on GitHub as explained in the panel below.

      Step 3 Login to Travis-CI. You may have to sign up first.

      Step 4 Sync your Travis account with GitHub:

      1. Go to your account.
      2. Click on Sync account to fetch all your repositories into Travis-CI.

      Step 5 Activate the repository:

      1. Go to your publish-RepoSense fork in Travis-CI
      2. Under Current tab, click on Activate repository.

      Step 6 Set the token/key:

      1. In the same page, click on More options on the right.
      2. Then, click on the Settings option:
        Travis-CI Dashboard
      3. Under Environment Variables, name a variable as GITHUB_TOKEN or GITHUB_DEPLOY_KEY depending on your earlier choice and paste the token/key into its value field; then click Add.
      4. Ensure that the Display value in build log is switched off for security reasons:
        Travis-CI Environment Variable

      Step 7 Update the report configuration:

      In your fork, edit run.sh (and if applicable, repo-config.csv, author-config.csv, group-config.csv) to customize the command line parameters or repositories to be analyzed.

      Step 8 View the generated report:

      1. Go to the Settings page of your fork in GitHub.
      2. Under the GitHub Pages section, look for Your site is published at [LINK]. It should look something like https://[YOUR_GITHUB_ID].github.io/publish-RepoSense. GitHub Setting

      It takes a few minutes for report generation. Meanwhile, you can monitor the progress live at Travis-CI's Builds.

      Updating the report

      Manual: Travis UI has a way for you to trigger a build, using which you can cause the report to be updated.

      1. Go to your fork in Travis-CI, click on More options on the right then Trigger build.
      2. In the pop up, click Trigger custom build.

      Automated: Travis-CI offers Cron Jobs in intervals of daily, weekly or monthly.

      1. Login to Travis-CI.
      2. Go to your fork in Travis-CI, click on More options on the right then access Settings.
      3. Under Cron Jobs, choose master for Branch, Always run for Options and pick an Interval of your choice; then click Add. -Travis-CI Cron
      +Travis-CI Cron