Skip to content

Latest commit

 

History

History
238 lines (173 loc) · 8.71 KB

CONTRIBUTING.md

File metadata and controls

238 lines (173 loc) · 8.71 KB
Raw

Contributing guide

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

  • Setting up local development
  • Runing SPAR locally
  • Opening and Reviewing PRs
  • Deployment and CI/CD
  • General 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.

Setting up local development

If all you want is to run SPAR locally, you can do it with Docker, without intalling all required tools for local development. Please go to the next section.

Git

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

Docker

You can use Docker and the Compose plugin to speed up local development!

⚠️ Note: Docker may requires super user (root) to be fully functional, but things can be a lot easier if you configure your computer to allow your regular user to run it without superpowers.

Take a look here to learn how to get it installed.

NodeJS

⚠️ Note: Please skip this step if you're going to work only with back-end tasks.

NodeJS is required to build and start SPAR Client. You can look for install instructions here. Make sure you have at least the version 18.

Java and Maven

⚠️ Note: Please skip this step if you're going to work only with front-end tasks.

SPAR uses Java OpenJDK 17 for development and Apache Maven for project magament.

An easy way of getting both Java and Maven on your machine is using SDK Man. Take a look here to learn how to get it installed. For this project we're using OpenJDK Java 17.

IDE

Front-end: Microsoft VS Code can be a great option. Lots of extensions and integrations. You can learn how to get installed here.

Please consider adding these suggested extensions:

Back-end: IntelliJ IDEA Community is strongly recommend, 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

Front-end: To enforce a better solution and a stronger product the Airbnb ESLint check-style was chosen. SPAR CI/CD Workflows also have a dedicated pipeline to check for common errors and possible bugs.

You cab run npm run lint before opening a PR, so any style error not addressed can be checked and you can use npm run lint --fix to fix small issues.

Note that if you choose VS Code, the above mentioned extension ESLint, by Microsoft is strongly recommend. Here's the link to the Marketplace: https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint

Back-end: The back-end 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.

There's a tool to validate changes submitted in accordance to the 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 for possible checkstyle issues with:

./mvnw --no-transfer-progress checkstyle:checkstyle -Dcheckstyle.skip=false --file pom.xml

Running SPAR Locally

The easiest way of getting all SPAR services running locally is with Docker and the Compose plugin. If you already have these on your computer, just run:

docker compose up -d

Here are some other usefull Docker commands:

Look for all running containers:

docker ps

Stopping all components:

docker compose down

And if you need, you can start only one component with:

docker compose up database -d

You may need to run both back-end or front-end in your local computer, instead of containers. To do that you'll need above mentioned development tools. Java and Maven for the back-end, and NodeJS for the front-end.

Front-end: After setting you local nodejs setup, you can run:

cd frontend
npm install
npm run start

If you want to understand more about the front-end component, you can read the README or the CONTRIBUTING files.

Back-end: With your local Java setup done, you can get SPAR up and running by typing (in the project root directory):

cd backend
./mvnw spring-boot:run

And in case you want to debug with remote JVM, you can do it with:

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

If you want to understand more about the back-end component, you can read the README or the CONTRIBUTING files.

Opening and Reviewing PRs

All code changes happen through Pull Requests. There's a 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 labels.

Git flow suggests that the branch name starts with the keywork based on the task. Starting with feat for features, bufix or fix for fixes, and so on. If you started your work based on a jira task, it's a good idea to put the task number at the beginning of the branch name as well. Same thing for issues. Consider these examples:

Task from Jira about a new feature:

git checkout -b feat/655-create-orchard-api

Task from GitHub issues about a bug fix:

git checkout -b bugfix/16-user-component-issues

When openning PRs make sure all the pipelines pass. That's a critical condition to get your PR merged. The first reviewer of your code should be yourself. Take a look and make sure no warnings or issues are thrown when running you change.

When reviewing PRs remember to be clear, if you need, you can add links and explanations why you think another way should be considered for a particular case.

PRs also are the best place to discuss changes before they get approved.

Deployment and CI/CD

SPAR uses GitHub Actions for deployments, CI and CD. All working code gets deployed into OpenShift Cloud. You can look for the deployments under the namespace b9d53b.

These are the existing workflows:

CI - Runs for every commit sent - Link here

PR - Runs for every open pull request - Link here

PR Close - Runs for all closed PRs - Link here

Merge to Main - Runs for all merges to main - Link here

General code practices

  • All source code must be formatted according to its configured tool, Google CheckStyle for Java and AirBnb ESLint for TypeScript.
  • Try to stick to conventional commits because it makes the process of generating changelogs way easier. You may want to take a look as this link, to read at least the summary and understand what is this thing about.