CONTRIBUTING.md

Contributing to GitactionBoard

Table of contents

• How to start contributing
  • Prerequisites
  • Tests
  • Formatting
  • Security Checks
  • Run application locally
    • Run backend with frontend
    • Run only backend
    • Run only frontend with mock data
  • Commits
    • Types
  • Build docker image
• Submitting a Pull Request
  • Your PR is merged!
• Release new version
  • Generate changelog
  • Release a new Docker image

How to start contributing

If you are not sure how to begin contributing to GitactionBoard, have a look at the issues tagged under good first issue.

Prerequisites

• jEnv
• Java 21
• Docker
• Hadolint
• ShellCheck
• Prettier
• talisman
• Trivy
• Node.js v20
• nvm
• all-contributors cli (only for maintainers)

Tests

Tests are separated into unit and integration test sets. To denote an integration test it needs to be annotated as @IntegrationTest.

To run only backend unit tests:

./gradlew test

To run integration tests:

./gradlew integrationTest

To run all the verifications:

./run.sh test

To run all backend verifications:

./run.sh backend-test

To run all frontend verifications:

./run.sh frontend-test

To run the mutation tests for backend:

./run.sh pitest

Test sets are runs in order, with unit tests first, followed by integration tests. Should there be a failure in the unit tests the task execution stops there, e.g. a prerequisite for running integration tests will be working unit tests.

Formatting

This project uses the following tools to follow specific style guide

• spotless for Java files
• Prettier for json, js, css, html and md files
• Hadolint for Dockerfile
• ShellCheck for sh files

To run format:

./run.sh format

Security Checks

This project uses the following tools to find security vulnerabilities

• org.owasp.dependencycheck to find vulnerable dependencies
• talisman to validate the outgoing changeset for things that look suspicious - such as authorization tokens and private keys
• Trivy to find vulnerabilities in Docker image

To run OWASP dependency check:

./run.sh check

To run Trivy check:

./run.sh trivy-verify

Run application locally

This service can be run locally.

Run backend with frontend

To run the application with complete backend and frontend locally, run the following command:

./run.sh run-locally <github auth token>

Run only backend

To run the only backend application, run the following command:

./run.sh run-locally <github auth token> false

Run only frontend with mock data

This application make uses of mockoon to start mock api server needed for local frontend development.

To run the only frontend application with mock api data, run the following command:

./run.sh run-frontend-locally

Commits

This repository follows Conventional Commits. Therefor whenever you are committing the changes make sure to use proper type.

Types

• feat for a new feature for the user, not a new feature for build script. Such commit will trigger a release bumping a MINOR version.
• fix for a bug fix for the user, not a fix to a build script. Such commit will trigger a release bumping a PATCH version.
• chore for Update something without impacting the user (ex: bump a dependency in package.json).
• perf for performance improvements. Such commit will trigger a release bumping a PATCH version.
• docs for changes to the documentation.
• style for formatting changes, missing semicolons, etc.
• refactor for refactoring production code, e.g. renaming a variable.
• test for adding missing tests, refactoring tests; no production code change.
• build for updating build configuration, development tools or other changes irrelevant to the user.

Note

Add ! just after type to indicate breaking changes

Build docker image

To build docker image run:

./run.sh docker-build

Submitting a Pull Request

To send in a pull request

1. Fork the repo.
2. Create a new feature branch based off the main branch.
3. Provide the commit message with the issue number and a proper description as per commits style.
4. Ensure that all the tests pass.
5. Submit the pull request.

Your PR is merged!

Congratulations 🎉🎉 The GitactionBoard team thanks you ✨.

Once your PR is merged, your contributions will be publicly visible on the Readme.

Release new version

Generate changelog

• The changelog can be easily generate the changelog by running following command

./run.sh generate-changelog

Release a new Docker image

A new docker image can be published to docker hub using CI/CD. To achieve the same we need to follow the following steps:

• Create a new release version by running following command

./run.sh bump-version

• Push the newly created tag to GitHub

git push origin "$(git describe --tags)"

Note

We are following semantic versioning strategy using io.alcide:gradle-semantic-build-versioning plugin