Merge branch 'contributing-draft' into 'development'

Contributing draft

See merge request !168

Contributing.md

+# Contributing to the queue (Queue) #
+This guide has the following goals
+
+1. Get the project [running](#Project-Setup) on your machine.
+2. Introduce the technologies used in Queue.
+3. Give you some directions to navigate the codebase.
+4. Cover the process of submitting your changes!
+
+## Project setup ##
+
+In order to have the project setup properly for development a few steps need to be taken.
+These steps assume you have already cloned the project (`git clone git@gitlab.ewi.tudelft.nl:eip/labrador/queue.git`)
+
+1.
+    First the config file should be moved from the template into the actual properties file
+    By executing ` cp src/main/resources/application.properties.template src/main/resources/application.properties `
+    from the root directory of the project.
+2. Install [IntelliJ IDEA Professional](https://www.jetbrains.com/idea/) ([free for students](https://www.jetbrains.com/student/))
+3. [Import project from Gradle model](https://www.jetbrains.com/idea/help/importing-project-from-gradle-model.html)
+4. For IntelliJ to run the project make sure you are running jdk 8.
+5. Start the project by right-clicking `QueueApplication` and clicking 'Run'
+6. Visit http://localhost:8081/courses, please note that the regular login button currently doesn't work in the development setup,
+   however visiting any other url (like /courses) in the queue will prompt you with a login screen.
+Various test users include: `U: assistant1@tudelft.nl P: assistant1` or `U: student1@tudelft.nl P: student1` and of course `U: admin@tudelft.nl P: admin`.
+A list of all users and other things set up in the development environment can be found in the `DataBaseLoader` class.
+
+## Queue in context ##
+In this section we give a joint context / development view of Queue.
+That is we place Queue in it's own environment the databases Queue owns and the browser it will interact with.
+Plus we identify the components with which Queue interacts with these and provide a very high level overview of how to work with them.
+More importantly this can serve as a reference, to check assumptions about these tools and how we use them for the new comer, more than an introduction to start using these tools.
+For that refer to section 3.
+
+![context-view](docs/Queuecontext.png)
+
+The diagram flows from frontend concerns on the left to back end on the right.
+The queue is then made out of the following components:
+
+1. Spring framework, with sub components:
+    - Spring security
+    - Thymeleaf
+    - Spring repositories
+2. Websockets
+3. Hibernate
+4. QueryDsl
+5. Redis
+6. Liquibase
+
+We cover these components in two groups, the first being the more "web facing" technologies: Spring (security), Thymeleaf, Redis and Websockets.
+Secondly we cover the application persistence technologies: Hibernate, QueryDsl, Spring repositories and Liquibase.
+
+### Web technologies ###
+The Queue is built using [Spring](https://spring.io/) which handles concerns such as routing, security and views.
+Routing is the act of finding the right piece of code to execute for a certain http request, depending on url or the http method (think: "GET" vs "POST").
+This is done by registering methods in a "controller" class and annotating them.
+Spring also implements our authentication and authorisation through [Spring Security](https://spring.io/projects/spring-security).
+Information about the authenticated user is stored in a session store, which in the production environment would be a [Redis](https://redis.io) it is not required for the development set up but it is an important part of the runtime environment of Queue, which is why it is listed here. 
+
+After the relevant processing is done to create the actual web page for the request the controller method hands of control to [Thymeleaf](https://www.thymeleaf.org/).
+Thymeleaf is a html templating engine that is: it has commands that go inside the html code that change the html depending on parameters given to Thymeleaf.
+These parameters are called the "model".
+ Think about it as the glue to only show an admin button to an admin etc.
+
+To summarize this workflow: A http request comes in it is then handled by a controller method registered through spring, check if the user is allowed to do this through Spring Security, it will do some processing with our data (see the next section) and finally create a web page for the request by handing an appropriate model to a Thymeleaf template.
+
+A few features in the queue also have communication going to the front end that is initiated by the backend.
+These include notifications and updates to the request table.
+These are sent through a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API) we don't explain anything regarding them here, but list them to note them as an important part of the runtime environment of Queue.
+
+### Persistence technologies ###
+For our persistence technology Query Dsl, Spring repositories and Hibernate have a clear relationship with one another, while Liquibase is mostly used in isolation.
+Hence we cover the first three first and together and cover Liquibase later.
+
+1. [Hibernate](http://hibernate.org/) is an ORM (object relational mapper), that is it knows how to connect to the database and can navigate the schema of the database by knowledge derived from classes in our code base.
+ Hence it maps objects to the relations (tables) in the database.
+  You can write queries directly with hibernate as well however the level of abstraction is not much higher than that of plain sql.
+  The best spot to find information about Hibernate is directly in their [user guide](https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html).
+
+2. [Spring Repository](https://spring.io/projects/spring-data) spring repositories are the first technology we use to raise the level of abstraction for writing queries.
+ A spring repository is an interface declaration with certain method signatures describing queries.
+ Spring then knows how to generate an implementation for these queries through Hibernate.
+ That is Spring uses Hibernate to execute the queries.
+ All these interfaces are found in the repository package of Queue.
+
+3. [Query Dsl](http://www.querydsl.com/)
+Query Dsl is a domain specific language for writing sql queries in java code rather than in strings.
+In order to do this it generates classes at compile time capturing information about the schema in the database, so that the types in the queries match the types of our schema.
+Query Dsl also doesn't talk to the database directly but does so through hibernate.
+
+![Persistence Stack](docs/PersistenceStack.png)
+
+Finally [Liquibase](https://www.liquibase.org/) is a tool for database migrations.
+So the queue once it is up and running actually has nothing to do with it.
+However it bridges changes you make to the schema in terms of the Hibernate model classes to the schema actually running in production.
+The database in production is actually populated, and can't be recreated from scratch every time the queue starts.
+Liquibase is a structured way you can write down changes to the schema (that reflect the changes made in the hibernate classes) that can be applied incrementally to the production database.
+
+
+## Navigating the code base ##
+Aside from understanding the components included in Queue, you as a developer also need to be able to find the relevant code for these things.
+Most features will affect most of the components, that is they will change the view (Thymeleaf) require some logic in a controller and perhaps store more information in the database.
+The proposed way to tackle a feature like this has the following high level steps.
+
+1. Find the relevant page in the running Queue (dev environment) application that you want to change.
+2. Find the controller method that corresponds to this page
+3. Change the frontend 
+4. See what it does in the controller method
+5. Find out what changes the database needs
+6. Update the hibernate model
+7. Write a liquibase migration for this change
+8. Hook up the controller logic
+
+To find the controller method you need the easiest way is to do a global search on the url of the page you are currently on.
+If you find a hit for that string in a `@RequestMapping` annotation for example:
+```java
+	@RequestMapping(value = "/courses", method = RequestMethod.GET)
+```
+That means you are probably in the right spot.
+If you want to be entirely sure put a breakpoint in the method and launch the Queue in debug and see if it hits the breakpoint.
+Also note that all controllers reside in the `Controller` package.
+
+
+To find the corresponding Thymeleaf template, look at the string that the controller method returns.
+For example:
+```java
+		return "course/view";
+```
+Means that the template in `src/main/resources/templates/course/view.html` will be rendered as a reply for this http request.
+
+The classes that make up the schema that are mapped by Hibernate reside in the model package.
+To figure out how to properly annotate the class to make a certain schema change the [domain-model](https://docs.jboss.org/hibernate/orm/5.4/userguide/html_single/Hibernate_User_Guide.html#domain-model) section of the user guide is your best bet.
+
+
+After making these changes (most likely depending on your config but not a certainty) Hibernate will crash if you restart the application.
+Because the schema that's in the development database does not match the schema it expects based on the classes in the project.
+To fix this mismatch we need to create a liquibase migration.
+These migrations reside in `src/main/resources/migrations.yaml`, either check the liquibase documentation or the previous changes in the file for inspiration on how to do this.
+
+With that in place you can update the logic in the controller to hopefully finish your new feature!
+
+#### A small side note on configuration ####
+A lot of changes to the queue also require changes to the way spring is configured in the project.
+The applications.properties file that we had you copy over in the setup section is the most important part of spring configuration.
+We don't cover the meaning of the properties here but note it as an important file in the repository.
+
+Besides the configuration in this file the rest of the configuration is done in code see `QueueApplication` for this.
+
+## Submitting your changes ## 
+After building your awesome new feature time has come to submit a merge request. The merge request template should already contain a check list for you to go through but we also list some of the steps here.
+
+1. Make sure your code is formatted properly.
+you can check this by using two different gradle tasks: `./gradlew spotlessCheck` and `./gradlew spotlessApply`
+2. Ensure your commit message has a title explaining what the change is and a body explaining why you made this change.
+3. Ensure your code is tested according to our non-existent testing guide.
+4. Ensure CI passes.
+5. probably more stuff
+
+## Production
+Queue runs on queue.tudelft.nl (alias for queue.ewi.tudelft.nl).
+This server is managed by the developers of the CSE Teaching Team (eip-ewi@tudelft.nl).
+
+### Error logging
+All exceptions in the production environment are logged to our [self-hosted Sentry instance](https://sentry.ewi.tudelft.nl).
+Access to Sentry can be requested via the server maintainers.
+In order to send the logs to the Sentry instance you need to create a properties file called `sentry.properties` next to the `application.properties` file.
+This file should contain the following (exact URL can be found in the Sentry project):
+
+```
+dsn=https://[identifier]@sentry.ewi.tudelft.nl
+```
+
+For local development your local logs should be sufficient to debug errors.
+When the above key is not set in the `sentry.properties` file then the Sentry Exception Handler will be ignored.