Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
309 lines (224 loc) · 10.1 KB

CONTRIBUTING.md

File metadata and controls

309 lines (224 loc) · 10.1 KB
Raw

Contributing to CycloneDX Gradle Plugin

Welcome to the CycloneDX Gradle Plugin project! We appreciate your interest in contributing to this open source project. This guide will help you get started with setting up your development environment and understanding our contribution process.

Table of Contents

  1. Getting Started
  2. Development Environment Setup
  3. Working with Gradle Toolchains
  4. Code Style and Formatting
  5. Building and Testing
  6. Publishing Plugin Locally
  7. Submitting Contributions
  8. Releasing
  9. Community Guidelines

Getting Started

The CycloneDX Gradle Plugin creates Software Bill of Materials (SBOM) from Gradle projects, supporting the CycloneDX specification. All open issues are welcome to contributors, and we value contributions of all sizes - from bug reports and documentation improvements to new features.

Before contributing, please:

Development Environment Setup

Prerequisites

  • Java Development Kit (JDK): Java 8 or higher
  • Git: For version control
  • IDE: IntelliJ IDEA, Eclipse, or VS Code with Java support

Clone the Repository

git clone https://github.com/CycloneDX/cyclonedx-gradle-plugin.git
cd cyclonedx-gradle-plugin

Working with Gradle Toolchains

This project uses Gradle toolchains to ensure compatibility across different Java versions. The build is configured to:

  • Target Java Version: Java 8 (for maximum compatibility)
  • Testing: Multiple LTS Java versions (8, 11, 17, 21, 25)
  • Gradle: Java 25

Testing with Multiple Java Versions

Tests are automatically run against multiple Java versions:

# Run tests with all supported Java versions
./gradlew test

# Run tests with a specific Java version
./gradlew testJava8
./gradlew testJava11
./gradlew testJava17
./gradlew testJava21

Configuring Local Toolchains

If you need to specify custom Java installations, you can configure toolchains in your global gradle.properties file ( ~/.gradle/gradle.properties):

# Define custom Java installation paths
org.gradle.java.installations.paths=/path/to/jdk8,/path/to/jdk11,/path/to/jdk17,/path/to/jdk21
# Disable automatic detection if needed
org.gradle.java.installations.auto-detect=false

Code Style and Formatting

This project uses the Spotless plugin with PalantirJavaFormat for consistent code formatting.

Code Style Requirements

  • Formatter: PalantirJavaFormat
  • Line Length: 120 characters
  • Indentation: 4 spaces
  • License Header: Required on all Java files

Working with Spotless

This project uses Spotless plugin that will:

  • Check code formatting during build
  • Apply automatic license headers
  • Format code according to PalantirJavaFormat standards

Running Spotless

# Check for formatting violations
./gradlew spotlessCheck

# Apply formatting fixes automatically
./gradlew spotlessApply

Code Style Documentation

For detailed information about the PalantirJavaFormat style, see:

Building and Testing

Building the Plugin

# Clean and build the project
./gradlew clean build

Running Tests

# Run all tests
./gradlew test

# Run tests with specific Java version
./gradlew testJava11

# Run tests with verbose output
./gradlew test --info

Continuous Integration

The project uses GitHub Actions for CI/CD. All pull requests must:

  • Pass all tests on multiple Java versions (8, 11, 17, 21)
  • Pass Spotless formatting checks
  • Build successfully
  • Every commit must be signed off with git commit -s to acknowledge the Developer Certificate of Origin (DCO)

Publishing Plugin Locally

To test your changes with other projects, you can publish the plugin to your local Maven repository:

Local Publishing Steps

  1. Build and publish locally:

    ./gradlew publishToMavenLocal

  2. Configure your test project to use the local plugin by adding to settings.gradle or settings.gradle.kts:

    pluginManagement {
    repositories {
        mavenLocal()  // This must be first for priority
        gradlePluginPortal()
        mavenCentral()
    }
}

  3. Use the plugin in your test project's build.gradle:

    plugins {
    id 'org.cyclonedx.bom' version '<version>'
}

Verifying Local Installation

After publishing locally, you can verify the installation:

# Check local Maven repository
ls ~/.m2/repository/org/cyclonedx/cyclonedx-gradle-plugin/

Submitting Contributions

Pull Request Process

  1. Fork the repository
  2. Create a branch for your feature or fix: 
    git checkout -b feature/my-new-feature
  3. Make your changes following the coding standards
  4. Run tests and formatting: 
    ./gradlew spotlessApply
./gradlew test
  5. Commit your changes with a clear message: 
    git commit -s -m "feat: add support for new SBOM feature"
  6. Push to your fork and create a pull request

Pull Request Guidelines

  • Clear Description: Explain what changes you made and why
  • Tests: Include tests for new functionality
  • Documentation: Update documentation for new features
  • Small Changes: Keep PRs focused and manageable
  • Code Quality: Ensure all checks pass (formatting, tests, build)

Commit Message Format

We follow conventional commit format:

  • feat: for new features
  • fix: for bug fixes
  • docs: for documentation changes
  • style: for formatting changes
  • refactor: for code refactoring
  • test: for adding tests
  • chore: for maintenance tasks

Releasing

Publishing a GitHub Release is the maintainer's release authorization. The Publish CI workflow validates and builds the tagged commit, generates and verifies its attestations, uploads the release SBOM, and publishes the plugin to the Gradle Plugin Portal.

Prepare and rehearse a release

  1. Update the project version in build.gradle.kts and the literal plugin versions in the README examples. Keep the release-SBOM bootstrap plugin on the latest already-published version until after the release, and keep intentional compatibility fixtures pinned to the releases they test.
  2. Merge the release-preparation change and wait for Build CI to pass on master.
  3. Before the first release after changing Publish CI, open Actions > Publish CI, select Run workflow, choose master, and run it manually.
  4. Confirm that the rehearsal succeeds for the intended version and commit. Its summary records the source ref and SHA-256 digest of every release artifact; the same artifacts are also available as a workflow-run download.

A manual Publish CI run uses a read-only build job and cannot execute the release-only jobs or steps that upload or publish a release. Gradle Plugin Portal secrets are referenced only by the production step. Rehearsal attestations describe the selected branch commit; the production run creates new attestations for the immutable release tag.

Publish the release

  1. Open Releases > Draft a new release on GitHub.
  2. Create cyclonedx-gradle-plugin-<version> at the exact master commit that passed the required checks and any rehearsal, then prepare the release notes.
  3. Publish the release as the latest release. This starts Publish CI; no separate manual publication command or approval is required.
  4. Confirm that Publish CI succeeds, the release contains its versioned CycloneDX SBOM, and the new version is available from the Gradle Plugin Portal.
  5. In a follow-up change, advance the release-SBOM bootstrap plugin and its release-artifact expectation to the newly published version.

Community Guidelines

Open Issues

All open issues are welcome to contributors! Whether you're a beginner or experienced developer, there are issues suitable for all skill levels. Look for:

  • Good First Issue: Great for newcomers
  • Help Wanted: Issues that need community assistance
  • Bug: Issues requiring fixes
  • Enhancement: Feature requests and improvements

Getting Help

If you need help with:

  • Development Questions: Open a discussion or comment on relevant issues
  • CycloneDX Specification: Visit CycloneDX.org
  • Community Support: Join the CycloneDX Slack

Code Review Process

  1. All contributions require review from project maintainers
  2. Feedback will be provided constructively and promptly
  3. Address review comments and update your PR
  4. Once approved, maintainers will merge your contribution

Contributor Recognition

We value all contributions and recognize contributors through:

  • Attribution in release notes
  • Contributor acknowledgments
  • Community recognition

Additional Resources

Thank you for contributing to CycloneDX Gradle Plugin! Your efforts help improve software supply chain security for the entire community.