Skip to content

Latest commit

 

History

History
181 lines (121 loc) · 5.36 KB

CONTRIBUTING.adoc

File metadata and controls

181 lines (121 loc) · 5.36 KB
Raw

Contributing to Plugin Health Scoring

This page provides information about contributing to the Plugin Health Scoring code base.

Getting started

The project is using Maven with Java 21 and Yarn to be built. The entire build process can be handled by Maven. When building, Yarn will bundle the front-end files only.

  1. Clone the repository.

  2. Install tools

    1. Java 21

    2. Maven 3.9.6

    3. Node 20.10.0 and Yarn 4.0.2 (these should be done in the "war" directory)

    4. Docker installed and running in your environment

  3. Open the project in your favorite IDE.

Note
 Optionally, you can use the Maven wrapper in the repository. In that case, replace the mvn command by ./mvnw in the command listed bellow.
Warning
 Make sure that you follow the instruction to install Yarn 2+. See https://yarnpkg.com/getting-started/install.

Please see the architecture document to better understand the structure of the code.

How to build locally the application

Once you have installed the tools listed before, you can generate the application binary by running the command, but bewware of additional requirements in the next subsection:

mvn verify

This will run all the tests of the application. You can speed up the process by running the command:

mvn package -Dmaven.test.skip

How to run the application locally

Before starting the application, it is required to create a GitHub App, configure environment variables and have access to a PostgreSQL Database.

Environment variables

You can find the list of environment variables in .env.example.

link:.env.example[role=include]

GitHub App

The application requires the following permissions:

  • Repository content (read-only)

Once the GitHub APP created, generate a private key. It will be downloaded automatically.

The downloaded key needs to be converted using the following command:

openssl pkcs8 -topk8 -inform PEM -outform PEM -in ORIGINAL_KEY.pem -out CONVERTED_KEY.pem -nocrypt
Note
 You need to change ORIGINAL_KEY and CONVERTED_KEY with real values.

This final file is the one to point to in GITHUB_APP_PRIVATE_KEY_PATH environment variable.

Finally, you need to install the GitHub APP on your GitHub user. In the GitHub App configuration page, find the Install App link on the left side menu.

Starting a PostgreSQL database

If you don’t want to install a PostgreSQL database locally, it is possible to start the service in the Docker Compose configuration.

In order to start the database this way, you can run the following command:

docker compose up -d db

Running the application from CLI

This method is preferred if you intend to submit any modifications to the project.

In one terminal, run:

cd ./war
yarn install
yarn dev

This will build and update the front-end files when you modify them.

First remember to run mvn clean install at root. Then, at the war directory, in a second terminal run:

mvn spring-boot:run -Dskip.yarn -Dspring.profiles.active=dev

This will start the application.

Note
 Don’t forget to set the required environment variables.

Running the application with Docker Compose

If you want to simply run the project locally, you can run:

mvn package -Dmaven.test.skip
docker compose up
Note
 the required environment variables must be set in a file named .env.

Connecting to database with Docker container

If you are using Docker you can connect to the database using the following command:

docker container exec -it plugin-health-scoring-db-1 psql -U <postgres-user-name>

Run the application on Gitpod

Gitpod is a cloud-based IDE that allows developers to write, test, and deploy code from anywhere. Follow this link to get familiar with Gitpod: Getting Started with Gitpod

This project includes a configuration in .gitpod.yml to be able to contribute to it on Gitpod. The required versions of Java and Maven are installed when starting the Gitpod workspace.

In order to run the project within the Gitpod environment, follow the steps of running the application with Docker Compose.

Note
 In case the build fails on start, run mvn package -Dmaven.test.skip again.

Testing change

The project has unit and integration tests. You can run all those with

mvn verify
Warning
 The integration tests requires Docker to be installed.

Proposing changes

All proposed changes are submitted and reviewed through a GitHub pull request. To submit a pull request:

  1. Make sure your changeset is not introducing a regression by running mvn verify

  2. Create a branch prefixed with:

    1. feature/ for a new enhancement

    2. fix/ for a bugfix

    3. docs/ for documentation changes

  3. Commit your changes to this new branch

  4. Push the branch to your fork of the repository.

  5. In the GitHub Web UI, select the New pull request option

  6. Follow the pull request template

  7. Click the Create pull request button.

The pull request will be built in ci.jenkins.io.