Skip to content

Commit

Permalink
docs/3276/improve-getting-started (#3289)
Browse files Browse the repository at this point in the history
* Expand developer documentation #3276

---------

Co-authored-by: Phanlezz <65733509+phanlezz@users.noreply.github.com>
  • Loading branch information
moritz-suckow-mw and phanlezz authored May 15, 2023
1 parent b19ac78 commit 35dd8a0
Show file tree
Hide file tree
Showing 5 changed files with 173 additions and 114 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/)

- Added support for parser suggestions to SVN-, MetricGardener-, RawText- and SourceCodeParser [#3287](https://github.com/MaibornWolff/codecharta/pull/3287) </br>
- Add semi automatic merging feature after executing multiple parsers [#3287](https://github.com/MaibornWolff/codecharta/pull/3287)
- Expanded developer documentation to include common problems and solutions for them [#3289](https://github.com/MaibornWolff/codecharta/pull/3289)

### Fixed 🐞

Expand Down
4 changes: 4 additions & 0 deletions gh-pages/_data/navigation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,10 @@ docs:
children:
- title: "New to this Code?"
url: /docs/new-to-code/
- title: "New to Analysis?"
url: /docs/new-to-code-analysis/
- title: "New to Visualization?"
url: /docs/new-to-code-visualization/

- title: Meta
children:
Expand Down
128 changes: 14 additions & 114 deletions gh-pages/_docs/07-01-new-to-code.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,12 @@ Finally, it would be great if you looked at how we give and receive [feedback]({
# Branching / Releasing

We create Pull Requests to the `main` branch after implementing a feature or fixing a bug. There is no release or development branch. We never push on `main` directly. Please take a look at our [contributing guidelines](https://github.com/MaibornWolff/codecharta/blob/main/CONTRIBUTING.md) before you start committing.
When updating your branch, we prefer using a rebase instead of merging to keep the commit history clean.

# Code Style Guide

Besides the rules enforced by our linter, we do not follow a set of defined style guidelines for our code.
Just try to make your code readable and follow common best practices.

# GitHub Actions

Expand Down Expand Up @@ -39,124 +45,18 @@ All workflow files can be found under `.github/workflows`

- Workflow: `release.yml`

# Analysis

The analysis is a CLI to import, export or filter from all kind of resources.

### Importing the Project

Don't import the whole codecharta project to IntelliJ when working on the analysis. Simply import the analysis folder for that. IntelliJ might not able to identify it as a Gradle project otherwise.

### Definitions

#### Importer

- Retrieves metrics from external sources, such as `SonarQube` and creates a `cc.json`.

#### Exporter

- Consumes a cc.json and creates another format, such as CSV

#### Filter

- Consumes a cc.json and creates another cc.json. A common use case is merging two cc.jsons

### Technologies

- [Kotlin]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_2_pick_analysis_language.md %})
- Gradle
- [PicoCli]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_5_pick_analysis_cli_library.md %})
- JUnit
- Assertj
- Mockito
- Gson
- Sonar-Plugins to create our own parsers

### Concepts

- [Pipes and filters architecture]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_4_decide_analysis_architecture.md %})
- Shared nothing importers.

### Building

- `gradlew.bat build` or `./gradlew build`
- Navigate to `build/distributions` and unzip the zip-folder
- Navigate to the `build/distributions/codecharta-analysis-VERSION/bin` and execute the ccsh

### Testing

- Run `gradlew.bat test` or `./gradlew test`
- Run `gradlew.bat integrationTest` or `./gradlew integrationTest`
# Common Issues

The integration tests might fail on windows, because of a missing or unknown `sh` command.
To make it work, add the path to the Git `sh.exe` (which is normally placed here `C:\<path-to-git>\Git\bin`) to your PATH variable.
There are a few issues regularly occurring when trying to start contributing. This aims to be like a FAQ section to help address the most common problems.

**If you want to run the JUnit tests with the IntelliJ-Runner, make sure to go to `File -> Settings ->Build,Execution, Deployment -> Build Tools -> Gradle` and select `Run test using: IntelliJ IDEA`**
### General

### Linting/Formatting
1. Error `lint-staged: command not found` when trying to commit: Try to reinstall the node packages in the project. To do that, visit the root directory of the project (and the subdirectories for analysis and visualization if that still fails) and execute `npm ci`.

- `gradlew.bat ktlintApplyToIdea` or `./gradlew ktlintApplyToIdea` (tested in IntelliJ)
### Analysis

# Visualization

The visualization opens a cc.json and displays a city-like landscape based on the folder structure.

### State Management

We use Redux to manage our state. This way we have a single state that allows us to have a single one-directional data flow at a time. Get familiar with the [core-concepts of redux](https://redux.js.org/introduction/core-concepts) and check out the chart below afterwards.

This chart shows the correct way to update the viewModel of a controller.

![redux]({{site.baseurl}}/assets/images/docs/reference/redux-flow.png)

This chart shows the data flow in our architecture when a new cc.json is opened.

![new-file-imported]({{site.baseurl}}/assets/images/docs/reference/loading-a-new-file-flow.png)

### PlopJS

In order to reduce the amount of time spent on repetitive work such as creating 5 files for an ui-component, we implemented some plop-templates that will help you with that. Just type `npm run plop` and let the magic take over.

Currently, we support the creation of:

- state service
- ui-component
- util static class
- redux property
- redux sub-reducer

### Other Technologies

- [Typescript]({{site.baseurl}}{% link _posts/adr/2017-09-03-ADR_7_pick_visualization_language.md %})
- npm
- AngularJs 1.x, specifically what are Components, Services
- Jest (Unit Tests)
- Puppeteer (E2E Tests)
- ESLint
- ThreeJs for 3d visualization
- d3 for tree map algorithm and tree hierarchy (parent-child relations)
- Webpack
- nwjs
- Redux

### Important Concepts

- Dependency Injection
- Observer Pattern (`.subscribe(...)`)
- 2D Squarified TreeMap

### Building

There are 3 possible ways to build and run the application. You can run it as a developer with hot-code, which allows you to make changes in the code and see the results in your browser a few seconds later. But you can also build the application yourself and run it in a standalone or in the browser.

- Development: `npm run dev`
- Standalone: `npm run build` -> `npm start`
- Web: `npm run build` -> Move the created content to a nginx server for example

### Testing
1. First build fails on new setup: One of our parsers depends on MetricGardener which is a multi-language parser to calculate metrics for a variety of languages. Therefore, make sure to install MetricGardener before trying to build the project. Also make sure that `metric-gardener` is available in your CLI. You can find more information on the documentation page about the [MetricGardenerImporter]({{site.baseurl}}{% link _docs/04-13-metricgardener.md %}).

- Unit-Tests: `npm test`
- E2E-Tests: `npm run build && npm run e2e`
- For IntelliJ: Run -> Edit Configurations -> Templates -> Jest -> Add configuration file -> Select `jest.config.json` -> Add CLI argument `--env=jsdom`
# Further documentation

For more test options check the `package.json`
For further information please check out the documentation pages for the [analysis]({{site.baseurl}}{% link _docs/07-02-new-to-code-analysis.md %}) and [visualization]({{site.baseurl}}{% link _docs/07-03-new-to-code-visualization.md %}) parts of the project.
80 changes: 80 additions & 0 deletions gh-pages/_docs/07-02-new-to-code-analysis.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
---
permalink: /docs/new-to-code-analysis/
title: "New to Analysis?"
---

# Analysis

The analysis is a CLI to import, export or filter from all kind of resources.

### Importing the Project

Don't import the whole codecharta project to IntelliJ when working on the analysis. Simply import the analysis folder for that. IntelliJ might not able to identify it as a Gradle project otherwise.
A simple way to only import the analysis is to clone the whole repository and then only open the analysis subdirectory as a project in IntelliJ.

## Architecture, Design and Technology

### Definitions

#### Importer

- Retrieves metrics from external sources, such as `SonarQube` and creates a `cc.json`.

#### Exporter

- Consumes a cc.json and creates another format, such as CSV

#### Filter

- Consumes a cc.json and creates another cc.json. A common use case is merging two cc.jsons

### Technologies

- [Kotlin]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_2_pick_analysis_language.md %})
- Gradle
- [PicoCli]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_5_pick_analysis_cli_library.md %})
- JUnit
- Assertj
- Mockito
- Gson
- Sonar-Plugins to create our own parsers

### Concepts

- [Pipes and filters architecture]({{site.baseurl}}{% link _posts/adr/2017-01-02-ADR_4_decide_analysis_architecture.md %})
- Shared nothing importers.

## Other

### Building

- `gradlew.bat build` or `./gradlew build`
- Navigate to `build/distributions` and unzip the zip-folder
- Navigate to the `build/distributions/codecharta-analysis-VERSION/bin` and execute the ccsh

### Testing

- Run `gradlew.bat test` or `./gradlew test`
- Run `gradlew.bat integrationTest` or `./gradlew integrationTest`

The integration tests might fail on windows, because of a missing or unknown `sh` command.
To make it work, add the path to the Git `sh.exe` (which is normally placed here `C:\<path-to-git>\Git\bin`) to your PATH variable.

**If you want to run the JUnit tests with the IntelliJ-Runner, make sure to go to `File -> Settings ->Build,Execution, Deployment -> Build Tools -> Gradle` and select `Run test using: IntelliJ IDEA`**

### Linting/Formatting

- `gradlew.bat ktlintApplyToIdea` or `./gradlew ktlintApplyToIdea` (tested in IntelliJ)

### Intellij Gradle Integration for Building and Testing

Multiple gradle tasks can be directly executed in the IntelliJ interface, this is especially useful when trying to build and test the project.
To do that open the gradle menu on the right side, and open the gradle tasks.
Under there you can find multiple useful tasks:

- `clean`: Deletes previous builds.
- `build`: Executes a formatting check, all unit tests and builds the project.
- `installDist`: Unpacks the zip file generated from the build, so that you get an executable file for manual testing. Inside the unpacked folder, you will find a bin director containing an executable `ccsh` file.
- `integrationTest`: Executes the integration tests specified in golden_test.sh

There are several more tasks defined, this is just an overview of the most commonly used tasks.
74 changes: 74 additions & 0 deletions gh-pages/_docs/07-03-new-to-code-visualization.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
---
permalink: /docs/new-to-code-visualization/
title: "New to Visualization?"
---

# Visualization

The visualization opens a cc.json and displays a city-like landscape based on the folder structure.

### State Management

We use Redux to manage our state. This way we have a single state that allows us to have a single one-directional data flow at a time. Get familiar with the [core-concepts of redux](https://redux.js.org/introduction/core-concepts) and check out the chart below afterwards.

This chart shows the correct way to update the viewModel of a controller.

![redux]({{site.baseurl}}/assets/images/docs/reference/redux-flow.png)

This chart shows the data flow in our architecture when a new cc.json is opened.

![new-file-imported]({{site.baseurl}}/assets/images/docs/reference/loading-a-new-file-flow.png)

### PlopJS

In order to reduce the amount of time spent on repetitive work such as creating 5 files for an ui-component, we implemented some plop-templates that will help you with that. Just type `npm run plop` and let the magic take over.

Currently, we support the creation of:

- state service
- ui-component
- util static class
- redux property
- redux sub-reducer

### Other Technologies

- [Typescript]({{site.baseurl}}{% link _posts/adr/2017-09-03-ADR_7_pick_visualization_language.md %})
- npm
- AngularJs 1.x, specifically what are Components, Services
- Jest (Unit Tests)
- Puppeteer (E2E Tests)
- ESLint
- ThreeJs for 3d visualization
- d3 for tree map algorithm and tree hierarchy (parent-child relations)
- Webpack
- nwjs
- Redux

### Important Concepts

- Dependency Injection
- Observer Pattern (`.subscribe(...)`)
- 2D Squarified TreeMap

### Building

There are 3 possible ways to build and run the application. You can run it as a developer with hot-code, which allows you to make changes in the code and see the results in your browser a few seconds later. But you can also build the application yourself and run it in a standalone or in the browser.

- Development: `npm run dev`
- Standalone: `npm run build` -> `npm start`
- Web: `npm run build` -> Move the created content to a nginx server for example

### Testing

- Unit-Tests: `npm test`
- E2E-Tests: `npm run build && npm run e2e`
- For IntelliJ: Run -> Edit Configurations -> Templates -> Jest -> Add configuration file -> Select `jest.config.json` -> Add CLI argument `--env=jsdom`

For more test options check the `package.json`

### Troubleshooting

#### ESLint & IntelliJ

If you run into a warning about the ESLint configuration you can try to change `Run for files` default glob pattern to this pattern `"**/*.(js|ts|jsx|tsx|html|vue)"`

0 comments on commit 35dd8a0

Please sign in to comment.