Skip to content
Snippets Groups Projects
Verified Commit c1434678 authored by Luc Everse's avatar Luc Everse :passport_control:
Browse files

Add contributing guide

parent 3c1e4e85
Branches
Tags
2 merge requests!175Release v2.4.0,!170Add CHANGELOG and CONTRIBUTING
Pipeline #608504 passed
# Contributing to AuTA #
This contributing guide has the following objectives:
1. [Getting Access](#getting-access)
2. [Project Setup](#project-setup)
3. [Project Architecture](#project-architecture)
1. [The Core](#the-core)
2. [The Workers](#the-workers)
3. [The Front-End](#the-front-end)
4. [Working on AuTA](#working-on-auta)
5. [Submitting Your Changes](#submitting-your-changes)
## Getting Access ##
To get started on developing AuTA (or Labrador), you will need to request access.
We do this to prevent the project from becoming unmanageable and to keep track of bug bounties effectively.
To request access, you will need to email eip-ewi@tudelft.nl. In this email, please explain why you want to help out with AuTA and what you want to contribute to specifically. Please also disclose your `gitlab.ewi.tudelft.nl` username.
## Project Setup ##
In order to get the project up and running, there is a few steps you need to take.
1. Install [IntelliJ IDEA Professional](https://www.jetbrains.com/idea/) which is free for students.
2. Install [Node.js](https://nodejs.org/en/download/) with NPM. Version 16 (LTS) is known to work.
3. Clone the project into your local directory (`git clone <LINK_TO_GIT_REPOSITORY>`).
4. Import the project into IntelliJ using the `build.gradle` file. Instructions can be found [here](https://www.jetbrains.com/help/idea/gradle.html#).
5. Make sure that you are running [JDK 11](https://jdk.java.net/archive/), otherwise, IntelliJ won't run the project. Instructions on how to set this up can be found [here](https://www.jetbrains.com/help/idea/sdk.html#).
6. Set up the application context.
1. Create a directory `/srv/auta` with read/write access for your user account;
2. Install MongoDB.
7. To run the application:
1. Start the core via the `:core:bootRun` Gradle task (via the IDE or `./gradlew :core:bootRun`);
2. Request a worker token:
1. Go to http://localhost:8080/workers;
2. Log in with admin/admin;
3. Click "**+** New token".
3. Start one or more workers using this token. The recommended command line is:
```shell
java -jar worker/build/libs/worker-<VERSION>.jar api-token=<API TOKEN> api-protocol=http api-port=8080
```
* If local Docker support is needed, but the worker complains about a missing libjunixsocket object, add the following _before_ `-jar`: `-Dorg.newsclub.net.unix.library.override=worker/lib/jni/libjunixsocket-native-2.2.0.so`
## Project Architecture ##
See the [AuTA architecture overview](/doc/architecture-design/auta-subsystems.png) for a diagram.
#### The Core ####
The AuTA core is a [Spring Boot Application](https://spring.io/) and handles external requests such as new submissions and administration. It divides incoming jobs over its connected workers and stores and transforms their results into human-readable reports. Each installation has exactly one instance of the core.
#### The Workers ####
AuTA workers take incoming jobs for analysis, calculating the configured set of metrics of the submission and, if needed, launching a Docker container for further user-configurable analysis. Multiple workers can be associated with a core, which allows for wide scaling, even across machines and networks. Orchestration via [Kubernetes](https://kubernetes.io/) is also available if desired.
#### The Front-End ####
The front-end is a [Vue.js](https://v3.vuejs.org/) application that interacts with the core's REST API for configuring assignments and manual submissions. It is an optional component, as the REST API is sufficient to configure AuTA.
## Working on AuTA ##
There are a few things we'd like to ask you to do, to keep the project as organized and maintainable as possible. They are as follows:
* **Sign your work.** If you are new to Labrador-dev, you will need to run a script which adds a `Signed-off-by` tag to each of your commits. Please read [these instructions](https://gitlab.ewi.tudelft.nl/eip/labrador/queue/-/blob/development/CONTRIBUTING.md#signing-your-work) to set this up.
* **Keep your git history clean.**
* Please keep to the standard of writing commit messages: start with a capital letter and use the correct tense. You can imagine your commit message is a continuation of "This commit will...". Make sure each commit message clearly explains what you changed. Use commit titles to summarize the changes and the commit body to explain them in detail.
* Use `git rebase -i <BRANCH>` when rebasing on a different branch, if possible. Please avoid merging branches (unless you are making an MR to `development` or `master`) as this creates a messy commit history. If you are not familiar with rebasing, you can read the [documentation](https://git-scm.com/docs/git-rebase).
* **Create your branch from the issue overview.** Open the issue you want to be working on and select the `Create branch` option. This way, the branch will be linked to the issue and once an MR from it is merged, it will automatically close it.
* **List all your significant changes in the [changelog](CHANGELOG.md).**
* Log changes under the `[UNRELEASED]` tag.
* Make sure to put it under the correct category (`added` / `changed` / `fixed`).
* **Make sure the code is properly formatted.** You can check you formatting by running `./gradlew checkstyleAll`. To keep reviews short, minimize the amount of changes; for example, do not align things by columns and do not auto-format files.
* **Test you code.** Make sure you test all the code you write. We try to keep the test coverage as high as possible. To run the tests with gradle, you can run `./gradlew test` and to generate the reports, you can run `./gradlew jacocoRootReport`.
* **Ensure your GitLab CI passes.** Your MR will not be able to merge if the pipelines on your MR don't pass. To check everything locally, run `./gradlew clean` followed by `./gradlew check`. Sometimes, one of the jobs in the CI doesn't pass due to a timeout - this might have been cause by a high load on the GitLab builders, so simply rerunning that job will often fix the issue.
* **Write detailed issue and MR descriptions.** There are templates created for both issues and merge requests which you can fill in to keep your description as clear and informative as possible.
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment