Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
146 lines (104 loc) · 7.06 KB

CONTRIBUTING.md

File metadata and controls

146 lines (104 loc) · 7.06 KB
Raw

INDIGO IAM developer guide

Thank you for investing your time in contributing to our project!

In this guide you will get an overview of the contribution workflow from opening an issue, creating a PR, reviewing, and merging the PR.

Development environment

The INDIGO IAM service is a Maven project built with Java 17.

Run

$ mvn package

to build the project, or

$ mvn package -DskipTests

to skip tests execution.

You can use your favorite IDE for development.
In case you are using Eclipse:

  • install the Spring Tools 4 plugin to use Spring buttons and configurations
  • import the Java Google style formatter (available here) to format your code.

In case you are using Visual Studio Code:

  • install Spring Boot Extension Pack
  • set java.format.settings.url to this url: formatter (or download the file and set the url to its local path)
  • set java.format.settings.profile to GoogleStyle (CNAF)
  • create a launch configuration in .vscode/launch.json like:
{
    "configurations": [
        {
            "type": "java",
            "name": "IamLoginService",
            "request": "launch",
            "cwd": "${workspaceFolder}",
            "mainClass": "it.infn.mw.iam.IamLoginService",
            "projectName": "iam-login-service",
            "args": "--spring.profiles.active=h2-test,dev",
            "envFile": "${workspaceFolder}/.env"
        }
    ]
}
  • use the Spring Boot Dashboard to run and debug the applications

Run the app

The main package is iam-login-service, listening by default on http://localhost:8080. To run it

  • enable the h2 and dev Spring profiles: these profiles allow to run the app in developer mode, where an in-memory database is enabled and populated with test users, clients, groups, etc. A web interface of the database is available at http://localhost:8080/h2-console. A test administrator can login into IAM with admin/password credentials, while a test user with test/password. Connection to the database is possible by inserting the following parameters:
    • Driver Class: org.h2.Driver
    • JDBC URL: jdbc:h2:mem:iam
    • User Name: sa
    • Password:
  • the main class to be run is it.infn.mw.iam.IamLoginService.

From the command line iam-login-service can be run with:

mvn -pl iam-login-service -am spring-boot:run -Dspring-boot.run.profiles=h2-test,dev

The iam-test-client package is a simple web application used to showcase an authorization code flow where iam-login-service is the OAuth Authorization Server. It listens by default on http://localhost:9090/iam-test-client. The main class to be run is it.infn.mw.tc.IamTestClientApplication. From the command line iam-test-client can be run with:

mvn -pl iam-test-client -am spring-boot:run

The voms-aa package is a micro-service which provides backward-compatible VOMS support for a Virtual Organization managed by iam-login-service. It listens by default on http://localhost:15000. The main class to be run is it.infn.mw.voms.VomsService. From the command line iam-voms-aa can be run with:

mvn -pl iam-voms-aa -am spring-boot:run -Dspring-boot.run.profiles=h2

Repository workflow

There are few rules that we want to follow during our development phase to make the history of this repository as clean as possible:

  • the master branch is the one containing the latest official release
  • the develop branch is a branch with a successful build, ready for next release
  • when you want to develop some feature, create a new branch starting from develop
    • if you spot a problem within IAM, search if an issue already exists. If not, create a new issue
    • create a new branch named issue-<number>
    • develop your own solution
    • when you are satisfied with your work, create a Pull Request from branch issue-<number> to develop
    • wait for the GitHub workflow to finish running. If the build succeeds, a Sonar analysis for code quality runs. Please fix spotted problems, if any. We want to keep as much code coverage as possible (a lower threshold is set to 85%), so add JUnit tests to the uncovered parts of your code.

Pull Request workflow

When you are finished with the changes, create a pull request, also known as a PR, and

  • add someone of the team as reviewer
  • link the PR to related issue
  • once you submit your PR, a team member will review your proposal
    • we may ask questions or request additional information
    • we may ask for changes to be made before a PR can be merged, either using suggested changes or pull request comments
    • as you update your PR and apply changes, mark each conversation as resolved.

Commits

Even tough we will squash all commits of a PR into an inclusive, long commit, we invite you to follow few best practices:

  • fist letter of the commit must be capital
  • tenses in the commit must not be past-like
  • the first line of the commit must be included within 50 characters. Add a new blank line if you want to add more explanation of your commit (this will make more readable a git log --oneline command output, for instance).

Useful references

OAuth standard

Presentations