Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewritten Read Me #269

Merged
merged 2 commits into from
Feb 25, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,11 @@ First of all: Thanks for your interest in joining us on our journey through the

The following is a set of guidelines for contributing to sonarQuest which is hosted by the viadee IT-Unternehmensberatung at GitHub. Guidelines are not meant to be rules. And as this is a community project - feel free to share your thoughts and experiences with the community and propose changes to this document in a pull request.

This project and everyone participating in it is governed by the sonarQuest [Code of Conduct](https://github.com/viadee/sonarQuest/...). By participating, you are expected to uphold this code.

## How Can I Contribute?

* Reporting Bugs
* Suggesting Enhancements
* Design Improvements
* Your First Code Contribution
* Pull Requests

Expand Down
147 changes: 51 additions & 96 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
# SonarQuest
![SonarQuest-Banner](docs/images/sonarquest-banner.png)


[![Build Status](https://travis-ci.org/viadee/sonarQuest.svg?branch=master)](https://travis-ci.org/viadee/sonarQuest)
[![](https://img.shields.io/github/release-pre/viadee/sonarquest.svg)](https://github.com/viadee/sonarQuest/releases)
Expand All @@ -7,64 +8,64 @@
[![](https://img.shields.io/github/forks/viadee/sonarQuest.svg)](https://github.com/viadee/sonarQuest/network/members)
[![](https://img.shields.io/github/contributors/viadee/SonarQuest.svg)](https://github.com/viadee/sonarQuest/graphs/contributors)
[![](https://img.shields.io/github/last-commit/viadee/SonarQuest.svg)](https://github.com/viadee/sonarQuest/commits/master)
[![](https://img.shields.io/github/commits-since/viadee/SonarQuest/0.7.1.svg)](https://github.com/viadee/sonarQuest/compare/0.7.1...master)


A tool for extending [SonarQube](https://www.sonarqube.org/) by a gamification system. Handle your code quality issues in a playful way by solving quests and adventures, earning rewards for refactoring code smells and optimization.

* more about SonarQuest's game concepts and application scenarios: https://www.viadee.de/sonarquest_en
* Sonar Quest info package: https://github.com/viadee/sonarQuest/blob/master/docs/SonarQuest_info_package.pdf
**SonarQuest** is a gamification tool extending [SonarQube](https://www.sonarqube.org/),
that allows developers to get rid of their code quality issues in a playful way
by solving quests and adventures, earning rewards for refactoring code smells
and optimization.

## Quick Start

### Install
Start your adventure with your team in 3 steps via Docker:
1. Clone this repo in a destination of your choice.
2. Run SonarQuest using Docker in the root project folder *sonarquest*: `docker-compose up --build` .
3. We added some initial users to play around with.
Open SonarQuest at http://localhost:4200 and login with the following credentials:

| Role | Username | Password |
|--------------------|----------|----------|
| Admin | admin | test |
| Game Master | gm | test |
| Developer (Player) | dev | test |

Don't want to use Docker? Check out the [Installation Guide](https://github.com/viadee/sonarQuest/wiki/Installation)
in our wiki!

### Start the game

1. Log in as admin.
2. Connect to any reachable SonarQube server and check the connection.
3. Get all the projects on SonarQube into SonarQuest and make a single project playable as a "world".
4. Assign a game master and players to this world.
5. Log in as predefined game master or add a new game master.
6. Get all issues aka tasks for the current world.
7. Create quests by writing a short story and add tasks to make them solvable.
8. *(Optionally)* create an adventure and add quests to it to support a whole story.
9. Get your players to log in (all pre-made avatars have the password test and their username as login)
and take on your quests by selecting to _fight_ in a quest and to _fight_ issues in the quests.
10. Login in as a game master from time to time to synchronize SonarQuest with the SonarQube project to have
SonarQuest pay out rewards to your players!

## Goal
Have fun!

Reduce technical debts in your code project by changing the refactoring process into a game. Create quests from SonarQube issues and write your own story.
Interested in getting to know SonarQuest more intense?
Check out our [GitHub wiki](https://github.com/viadee/sonarQuest/wiki)!

An example: a team defines the solvation of issues with priority levels "blocker" and "critical" as goals on a fictious adventure map in a game they call "travel through the wild Codeistan". They can reach the respective targets in the adventure by decreasing the number of code smells, bugs and security vulnerabilities detected by SonarQube.
## Contributing
Interested in joining our adventure of making code refactorings much more fun? We are glad that you are here!
We are looking for enthusiasts and pioneers who want to be part of a motivated community,
regardless of whether you are designer, an idea generator or - of course - a developer: We welcome you!
Check out the [Contributing Guide](CONTRIBUTING.md) to get started.

![Example](docs/images/screenshot.jpg)

## Jump-start for users

The quickest way to get a running SonarQuest and to start playing is to use Docker, see [INSTALLATION.md](installation.md) or if you do not have Docker, just do the following:

### Backend
* download the runnable backend jar from the latest release, e.g. https://github.com/viadee/sonarQuest/releases/tag/0.7.1/
* start it with "java -jar [name of the jar]"

### Frontend
* check out the *sonarquest-frontend* folder from github
* Install *Node.js*. Please follow the instructions on the [Node.js](https://nodejs.org) website.
* Install *Angular-Cli* globally with `npm install -g @angular/cli`

After that you can start the SonarQuest client:
1. switch to the directory: `cd sonarQuest-frontend`
2. install the node modules: `npm install`
3. start the test server with the SonarQuest client: `ng serve`
You can access the SonarQuest client in a browser at `http://localhost:4200`
## Support
You have still open questions? Feel free to open an issue in GitHub. We will answer as fast as possible.

### 10 steps into your SonarQuest game

1. Log in as admin with password test
2. Check the connection to the SonarQube server
3. Get all the projects on SonarQube into SonarQuest and make a single project playable as a "world"
4. Assign a gm and players to this world
5. Log in as gm with password test
6. Get all issues aka tasks for the current world
7. Create quests by writing a short story and add tasks to make them solvable
8. (Optionally) create an adventure and add quests to it to support a story arc
9. Get your players to log in (all pre-made avatars have the password test and their username as login) and take on your quests by selecting to "fight" in a quest and to "fight" issues in the quests
10. Login in as a gm from time to time to synchronize SonarQuest with the SonarQube project to have SonarQuest pay out rewards to your players!

Have fun!

## Getting Started

See [INSTALLATION.md](installation.md) for instruction to get started with SonarQuest. These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.


### Used technologies and projects
The SonarQuest client is an *Angular* application on the basis of *TypeScript*. *Angular Material*, *Teradata Covalent* and *RPG-Awesome* (Icons) are used for the UI. You need *Node.js* for your development environment.

## Used frameworks
SonarQuest is a web-based app with an Angular UI application and Spring Boot as backend server.

* [Angular](https://angular.io) (licensed under MIT)
* [Angular Material](https://material.angular.io) (licensed under MIT)
Expand All @@ -75,54 +76,8 @@ The SonarQuest client is an *Angular* application on the basis of *TypeScript*.
* [Spring Boot](https://spring.io/) (licensed under Apache License 2.0)


## Contributing

Interested in helping out? Welcome! Check out the guide [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

## License

This project is licensed under the BSD 3-Clause "New" or "Revised" License - see the [LICENSE](LICENSE) file for details.
The licenses of the reused components of the SonarQuest server can be found in [Licenses SonarQuestServer](sonarQuest-backend/src/main/resources/licenses/licenses.json).

## User Guidelines



### Player and Avatars

A user can choose an individual avatar with a name, a class (e.g. warrior or magician) and a race (e.g. dwarf or elf). A set of predefined avatars is available [here in PDF format](AvatarCards.pdf).
Please note the username (login) is the character's name by default (first letter is always uppercase!) and the standard password is `test` for all accounts.

During an adventure the party (which may be represented by a project team) takes on quests and every avatar has several possibilities to gain experience points (XP) and get to the next level. Besides, some quests and tasks contain a reward in form of gold -- which can be used to purchase items and improvements in the marketplace.

The levels are determined based on experience points (XP) as follows:

#### Levels

| Level | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
|-------|---|----|----|----|----|----|----|----|
| XP | 0 | 10 | 30 | 60 | 100| 150| 210| 280|

Levels 1 to 100 are included in the standard game data. In case you want to add some extra levels, consider reading the [level calculation documentation](docs/SonarQuest_Level_Calculation.ods).

#### Rating system
Every issue is assessed in experience points and gold. The higher the severity of a issue the more experience points that a user gets.
* Blocker = 10 XP
* Critical = 7 XP
* Major = 5 XP
* Minor = 2 XP
* Info = 1 XP

The number of gold is calculated depending on the effort (minutes/10), e.g. approximately 30 minutes = 3 gold, 2 hours = 12 gold.
Thus issues with a low severity and a high effort are also attractive for a user.

### Quests and Administration

A "Game-Master" is responsible for the administration of quests and adventures and assigning issues from SonarQube to them. This process is supported by automatic generation: The results from the previous SonarQube-Build are being loaded and evaluated using the severity the effort to solve them. Subsequently, the issues are randomly grouped to predefined quests. These can be assigned to team adventures.
When a quest is solved, i.e. the related SonarQube issues don't exist anymore, the avatar receives the reward.

Additionally, a Game Master is able to manually create "special tasks" which are rewarded by bonus experience points or bonus gold, such as:

- Increase the coverage of a changed class for 10%
- Increase the documentation quality of a changed class
- Apply the DRY principle in one class
Binary file added docs/images/sonarquest-banner.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
6 changes: 6 additions & 0 deletions installation.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
**!!This file needs to be updated and integrated in the [wiki](https://github.com/viadee/sonarQuest/wiki/Installation)!!**


***


# Technical documentation of SonarQuest
Following, the components of SonarQuest are described.
Firstly, the general architecture is explained, followed by the installation guide.
Expand Down
6 changes: 3 additions & 3 deletions sonarQuest-frontend/angular.json
Original file line number Diff line number Diff line change
Expand Up @@ -124,11 +124,11 @@
"defaultProject": "sonarquest-frontend",
"schematics": {
"@schematics/angular:component": {
"prefix": "app",
"styleext": "css"
"prefix": "sq",
"styleext": "scss"
},
"@schematics/angular:directive": {
"prefix": "app"
"prefix": "sq"
}
}
}
2 changes: 1 addition & 1 deletion sonarQuest-frontend/nginx/sonarquest.conf
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ server {
}

location /api/ {
proxy_pass http://backend:80/;
proxy_pass http://backend:8080/;
}


Expand Down
6 changes: 3 additions & 3 deletions sonarQuest-frontend/src/app/app-routing/app-routing.module.ts
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ import {GamemasterPageComponent} from '../pages/gamemaster-page/gamemaster-page.
import {AuthenticationGuard} from '../authentication/authentication.guard';
import {EmptyPageComponent} from '../pages/empty-page/empty-page.component';
import {RoutingUrls} from './routing-urls';
import {LoginPageComponent} from "../pages/login-page/login-page.component";
import {MainLayoutComponent} from "../layouts/main-layout/main-layout.component";
import {LoginPageComponent} from '../pages/login-page/login-page.component';
import {MainLayoutComponent} from '../layouts/main-layout/main-layout.component';


const appRoutes: Routes = [
Expand All @@ -32,7 +32,7 @@ const appRoutes: Routes = [
{path: RoutingUrls.empty, component: EmptyPageComponent}
];

@NgModule({
@NgModule({
imports: [
RouterModule.forRoot(appRoutes, { onSameUrlNavigation: 'reload' })
],
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@ import {Injectable} from '@angular/core';
import {ActivatedRouteSnapshot, CanActivateChild, Router, RouterStateSnapshot} from '@angular/router';
import {AuthenticationService} from './authentication.service';
import {PermissionService} from '../services/permission.service';
import {RoutingUrls} from "../app-routing/routing-urls";
import {RoutingUrls} from '../app-routing/routing-urls';

@Injectable()
export class AuthenticationGuard implements CanActivateChild {
Expand Down
4 changes: 2 additions & 2 deletions sonarQuest-frontend/src/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@
<link rel="mask-icon" href="/assets/favicon/safari-pinned-tab.svg" color="#c62828">
<meta name="msapplication-TileColor" content="#c62828">
<meta name="theme-color" content="#c62828">

<script type="application/javascript">
var global = window;
</script>
Expand All @@ -30,7 +30,7 @@
<app-root>
<div class="loading">
<img src="assets/images/splash_screen.svg" style="height:30%" alt="This is the start screen of the app.">
<h1>prepare for...SonarQuest</h1>
<h1>prepare for...<strong>SonarQuest</strong></h1>
<div class="spinner">
<div class="double-bounce1"></div>
<div class="double-bounce2"></div>
Expand Down