-
Notifications
You must be signed in to change notification settings - Fork 30
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs/3276/improve-getting-started (#3289)
* Expand developer documentation #3276 --------- Co-authored-by: Phanlezz <65733509+phanlezz@users.noreply.github.com>
- Loading branch information
1 parent
b19ac78
commit 35dd8a0
Showing
5 changed files
with
173 additions
and
114 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| 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. | ||
|
|
||
|  | ||
|
|
||
| This chart shows the data flow in our architecture when a new cc.json is opened. | ||
|
|
||
|  | ||
|
|
||
| ### 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)"` |