Skip to content

Latest commit

 

History

History
160 lines (115 loc) · 5.81 KB

CONTRIBUTING.md

File metadata and controls

160 lines (115 loc) · 5.81 KB

Contributing guide

Thanks for taking a moment and reading this guide. Is very important to have everyone on the same page. This guide describes how to:

  • Set up your environment
  • Run this application
  • Run tests
  • Submit pull requests
  • Follow our code practices

(If you are new to GitHub, you might start with a basic tutorial and check out a more detailed guide to pull requests.)

All contributors retain the original copyright to their stuff, but by contributing to this project, you grant a world-wide, royalty-free, perpetual, irrevocable, non-exclusive, transferable license to all users under the terms of the license under which this project is distributed.

Set up your environment

Git

Make sure you have Git installed on your machine. You can follow this link for instructions.

Docker

We containerize our application with Docker images.

Note: things are way easier if you don't need to run docker commands with root (sudo). Take a look here to learn how to install. Note that Docker Desktop shouldn't be used for this project, due to license matters.

Java and Maven

An easy way of getting both Java and Maven on your machine is using SDK Man. Take a look here to learn how to install. For this project we're using Java 17 (OpenSDK).

IDE

We recommend IntelliJ IDEA Community, because all of its plugins and configurations possibilities, here's the website. But feel free to use Eclipse or other IDE of your choice.

Code style

Our Java code is formatted following the Google Java Style Guide. A formatter and plugins based on it for Eclipse and IntelliJ are available and make writing style-conformant code quite easy. Check the installation notes on the formatter's project page.

We configured a tool to validate changes submitted to us in accordance to our style guide. Passing such validation, however, doesn't mean that the code conforms to the style guide, as some rules cannot be checked by this tool. We ask you to check if your code adheres to the following rules before submitting it.

You can check your code before submitting with ./mvnw --no-transfer-progress checkstyle:checkstyle -Dcheckstyle.skip=false --file pom.xml

Run this application

After setting up your environment you might want to see this service running. You can get it up and running by typing (in the project root directory):

./mvnw spring-boot:run

In case you want to debug with remote JVM, you can do it with this command:

./mvnw spring-boot:run -Dspring-boot.run.jvmArguments="-Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005"

Note: You need a running Postgres service to have a fully working environment. You can do that with Docker or Docker and the Compose plugin. Follow these steps:

cd database
docker-compose up --build

Building Cloud Native Image

You can build the image with:

./mvnw -Pnative clean spring-boot:build-image -Dspring-boot.build-image.imageName="nr-spar-backend"

And then, run it with:

docker run -d \
  --name backend-native \
  --env-file ./backend/.env \
  nr-spar-backend

Run tests

For unit tests, please use this command:

./mvnw test --file pom.xml

And for integration tests:

./mvnw verify -P integration-test --file pom.xml

Tests coverage and reports can be seen on your commits and pull requests. But in case you want to check it locally, use this command to run all tests:

./mvnw --no-transfer-progress clean verify -P all-tests --file pom.xml

And check out the html file generated:

x-www-browser target/coverage-reports/merged-test-report/index.html # For Linux
open target/coverage-reports/merged-test-report/index.html # For MacOS

Submit pull requests

We use git flow, so all code changes happen through Pull Requests. There's a Pull Request template that you can fill. The more complete the better. If you have images, screen capture or diagrams, that helps a lot. Don't forget to add reviewers, assign to yourself and add a label.

Database versioning

Any permanent alteration to the database schema (creation or alteration of tables, columns, etc.) should be done through Flyway. Here's a brief explanation on how versioning with Flyway works.

Each migration should have its own file, which must follow this naming pattern.

Follow our best practices

  • Java source code must be formatted according to Google Java Style Guide, as mentioned. There's a pipeline to unsure all of our code is good to go.
  • We try to use conventional commits because it makes the process of generating changelogs way easier. So we encourage you to read at least the summary that summarize and give some examples.