Skip to content

Latest commit

 

History

History
95 lines (53 loc) · 5.35 KB

CONTRIBUTING.md

File metadata and controls

95 lines (53 loc) · 5.35 KB

Contributing to Fortify SSC Parser Plugin Utility Libraries

Contribution Agreement

Contributions like bug fixes and enhancements may be submitted through Pull Requests on this repository. Before we can accept 3rd-party pull requests, you will first need to sign and submit the Contribution Agreement. Please make sure to mention your GitHub username when submitting the form, to allow us to verify that the author of a pull request has accepted this agreement.

Information for Developers

The following sections provide information that may be useful for developers of the fortify-ssc-parser-util project.

Conventional commits & versioning

Versioning is handled automatically by release-please-action based on Conventional Commits. Every commit to the main branch should follow the Conventional Commits convention. Following are some examples; these can be combined in a single commit message (separated by empty lines), or you can have commit messages describing just a single fix or feature.

chore: Won't show up in changelog

ci: Change to GitHub Actions workflow; won't show up in changelog

docs: Change to documentation; won't show up in changelog

fix: Some fix (#2)

feat: New feature (#3)

feat!: Some feature that breaks backward compatibility

feat: Some feature
  BREAKING-CHANGE: No longer supports xyz

See the output of git log to view some sample commit messages.

release-please-action invoked from the GitHub CI workflow generates pull requests containing updated CHANGELOG.md and version.txt files based on these commit messages. Merging the pull request will result in a new release version being published; this includes publishing the image to Docker Hub, and creating a GitHub release describing the changes.

The build.gradle script reads the version number of the last published release from version.txt, by default this will result in a version named x.y.z.SP-SNAPSHOT, indicating that this is a snapshot of an upcoming Service Pack release. Note the 'Service Pack' here just means 'the next version after the last published release'. We never actually release service packs; once the 'Service Pack' is ready for release, a new version number will be generated by release-please-action based on the Conventional Commit messages.

This default behavior can be modified by passing the -PisReleaseVersion property, in which case the build.gradle will generate a version named x.y.z.RELEASE. This should fit nicely with Gradle semantics, which states that for example 1.0-RELEASE < 1.0-SP1.

Gradle Wrapper

It is strongly recommended to build this project using the included Gradle Wrapper scripts; using other Gradle versions may result in build errors and other issues.

Commonly used commands

All commands listed below use Linux/bash notation; adjust accordingly if you are running on a different platform. All commands are to be executed from the main project directory.

  • ./gradlew tasks --all: List all available tasks
  • Build & publish:
    • ./gradlew clean build: Clean and build the project
    • ./gradlew build: Build the project without cleaning
    • ./gradlew publishToMavenLocal: Publish this build as a snapshot version to the local Maven repository for testing purposes
    • ./gradlew publishToOSSRH: Publish this build as a snapshot version to OSSRH; usually only done from a GitHub Actions workflow
    • ./gradlew publishToOSSRH closeOSSRHStagingRepository -PisReleaseVersion=true: Publish this build as a release version to the OSSRH staging area; use this for first-time publishing to check release contents
    • ./gradlew publishToOSSRH closeAndReleaseOSSRHStagingRepository -PisReleaseVersion=true: Publish this build as a release version to Maven Central; usually only done from a GitHub Actions workflow

All OSSRH-related tasks require the following Gradle properties to be set:

  • signingKey: GPG secret key used to sign the artifacts
  • signingPassword: Password for the GPG secret key
  • OSSRHUsername: Sonatype OSSRH user name
  • OSSRHPassword: Sonatype OSSRH password

These properties can be set on the command line, in a local gradle.properties file, or through environment variables named ORG_GRADLE_PROJECT_<propertyName>. For automated build pipelines, it is recommended to use a Sonatype OSSRH token rather than actual username and password.

Automated Builds & publishing

A GitHub Actions ci.yml workflow is used to automatically build and publish both snapshot versions and release versions to OSSRH/Maven Central:

This document was auto-generated from CONTRIBUTING.template.md; do not edit by hand