In this document you will find a lot of information on how you can contribute to RallyMan.
To find possible tasks for your first contribution to RallyMan, we tagged some of the hopefully easier to solve issues as good first issue.
If you prefer to meet people in real life to contribute to RallyMan together, we recommend to visit a Hackergarten event. RallyMan is often selected as a contribution target in Lucerne, Zurich, and at the JavaLand conference.
Please join our developer community using our Matrix chat to get support and help for contributing to RallyMan.
It is important to sign-off every commit. That is a de facto standard way to ensure that you have the right to submit your content and that you agree to the DCO (Developer Certificate of Origin).
You can find more information about why this is important and how to do it easily in a very good blog post by Josef Andersson.
We love to add an emoji to the beginning of every commit message which relates to the nature of the change. You can find a searchable list of possible emojis and their meaning in the overview on the gitmoji website. If you prefer, you can also install one of the plugins that are available for almost all common IDEs.
AI generated source code is based on real existing source code, which is copied in whole or in part into the generated code. The license of the original source code with which the AI was trained is not taken into account. It is not clear which license conditions apply and how these can be complied with. For legal reasons, we therefore do not allow AI-generated source code at all.
There is a channel at Matrix for quick and easy communication. This is publicly accessible for everyone. For developers as well as users. The communication in this chat is to be regarded as short-lived and has no documentary character.
You can find our Matrix channel here: @rallyman:ijug.eu
We use the corresponding GitHub function for discussions. The discussions held here are long-lived and divided into categories for the sake of clarity. One important category, for example, is that for questions and answers.
Discussions on GitHub: https://github.com/McPringle/rallyman/discussions
Questions and Answers: https://github.com/McPringle/rallyman/discussions/categories/q-a
It is highly recommended to use Docker to run a local database, which is needed to start RallyMan on your development machine.
RallyMan needs a database. It is recommended to use MariaDB. To make contributions easier, there is a docker-compose.yaml available which starts a MariaDB instance locally on port 3306, including a web based administration interface on port 4000. To start the database, just run the following command from the project root:
docker compose -f docker/developer-db/docker-compose.yaml up -d
The web based administration interface is available on http://localhost:4000/. The data in the database is persisted between restarts. You can find the files in the .mariadb/data directory inside the project root. To stop the database server, use the following command:
docker compose -f docker/developer-db/docker-compose.yaml down
The server of RallyMan is written using the Java programming language. The main framework is Spring. For the user interface, we use Vaadin Flow. To access the database, we rely on jOOQ. To coordinate the build process, Maven is used.
Vaadin web applications are full-stack and include both client-side and server-side code in the same project.
| Directory | Description |
|---|---|
src/main/frontend/ |
Client-side source directory |
index.html |
HTML template |
index.ts |
Frontend entrypoint |
main-layout.ts |
Main layout Web Component (optional) |
views/ |
UI views Web Components (TypeScript / HTML) |
styles/ |
Styles directory (CSS) |
src/main/java/swiss/fihlon/rallyman/ |
Server-side source directory |
Application.java |
Server entrypoint |
- Read the documentation at vaadin.com/docs.
- Follow the tutorials at vaadin.com/tutorials.
- Watch training videos and get certified at vaadin.com/learn/training.
- Create new projects at start.vaadin.com.
- Search UI components and their usage examples at vaadin.com/components.
- View use case applications that demonstrate Vaadin capabilities at vaadin.com/examples-and-demos.
- Discover Vaadin's set of CSS utility classes that enable building any UI without custom CSS in the docs.
- Find a collection of solutions to common use cases in Vaadin Cookbook.
- Find Add-ons at vaadin.com/directory.
- Ask questions on Stack Overflow or join our Discord channel.
- Report issues, create pull requests in GitHub.
RallyMan uses Maven to build the project. Please use standard Maven commands to build what you need:
| Command | What it does |
|---|---|
./mvnw |
compile and run the app |
./mvnw clean |
cleanup generated files and build artefacts |
./mvnw compile |
compile the code without running the tests |
./mvnw test |
compile and run all tests |
./mvnw package |
compile, test, and create a JAR file to run it with Java directly |
./mvnw verify |
compile, test, package, and run analysis tools |
There is no need to run the install or deploy tasks. They will just run longer, produce unnecessary output, burn energy, and occupy your disk space. Don't just blindly run mvn clean install...
There are two ways to run the application: From the command line or directly from your IDE.
To run from the command line, use ./mvnw and open http://localhost:8080 in your browser.
- On the right side of the window, select "Maven" --> "Plugins" -->
spring-boot-->spring-boot:run - Optionally, you can disable tests by clicking on a
Skip Tests modeblue button.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Locate the
Application.javaclass in the Project view. It is in thesrcfolder, under the main package's root. - Right-click on the Application class
- Select "Debug 'Application.main()'" from the list
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Right click on a project folder and select
Run As-->Maven build.... After that a configuration window is opened. - In the window set the value of the Goals field to
spring-boot:run - You can optionally select the
Skip testscheckbox - All the other settings can be left to default
Once configurations are set clicking Run will start the application.
Do not worry if the debugger breaks at a SilentExitException. This is a Spring Boot feature and happens on every startup.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
- Locate the
Application.javaclass in the Package Explorer. It is insrc/main/java, under the main package. - Right-click on the file and select
Debug As-->Java Application.
Do not worry if the debugger breaks at a SilentExitException. This is a Spring Boot feature and happens on every startup.
After the server has started, you can view it at http://localhost:8080/ in your browser. You can now also attach breakpoints in code for debugging purposes, by clicking next to a line number in any source file.
Tip
There is an official Docker image you can use to run RallyMan.
To build the dockerized version of RallyMan yourself, run:
docker build . -f docker/build/Dockerfile -t rallyman:latest
Once the Docker image is correctly built, you can test it locally using:
docker run -p 8080:8080 rallyman:latest