Skip to content

Latest commit

 

History

History
163 lines (104 loc) · 9.46 KB

CONTRIBUTING.md

File metadata and controls

163 lines (104 loc) · 9.46 KB

Contributing

In this document you will find a lot of information on how you can contribute to Komunumo.

How to contribute

Good first issues

To find possible tasks for your first contribution to Komunumo, 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 Komunumo together, we recommend to visit a Hackergarten event. Komunumo 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 Komunumo.

Sign-off your commits

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.

Add an emoji to your commit

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 code

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.

Communication

Matrix Chat

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: @komunumo:ijug.eu

GitHub Discussions

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/komunumo/discussions
Questions and Answers: https://github.com/McPringle/komunumo/discussions/categories/q-a

Architecture

The server of Komunumo 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.

Structure

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/org/komunumo/ Server-side source directory
    Application.java Server entrypoint
    AppShell.java application-shell configuration

Useful Vaadin Links

Build

Maven

Komunumo 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...

Running and debugging

There are two ways to run the application: From the command line or directly from your IDE.

Running the server from the command line.

To run from the command line, use ./mvnw and open http://localhost:8080 in your browser.

Running and debugging the server in Intellij IDEA

Using Maven

  • 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 mode blue 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.

Using the main method

  • Locate the Application.java class in the Project view. It is in the src folder, 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.

Running and debugging the server in Eclipse

Using Maven

  • 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 tests checkbox
  • 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.

Using the main method

  • Locate the Application.java class in the Package Explorer. It is in src/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.

Running using Docker

Tip

There is an official Docker image you can use to run Komunumo.

To build the dockerized version of Komunumo yourself, run:

docker build . -t komunumo:latest

Once the Docker image is correctly built, you can test it locally using:

docker run -p 8080:8080 komunumo:latest