This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Contributing to Sonatype Community Projects

Wanting to engage with a Sonatype Community Project? This area documents the different ways of engaging with and the standards we expect our Community Projects to operate to.

1 - Community Roles

Individuals in the following roles are the backbone of our community.

Frequently, individuals will act in different roles at different times, or multiple at once.

For example, a maintainer will frequently act as a contributor and a contributor is likely a regular user of the tools they contribute to.

Click on a role below to learn more about it!

1.1 - Project User

A Project User engages with the project primarily by utilizing its features, following the guidelines set forth in its license. While they may not contribute directly, their usage helps validate the project’s relevance and functionality, providing passive feedback through adoption and interaction with the software.

Feedback may be provided by users through the form of GitHub Issues or Discussions, depending on the preference of the project.

This role does not require any permissions on the GitHub Project.

Next level: Project Contributor

1.2 - Project Contributor

A Project Contributor plays a pivotal role in shaping the project through code, documentation, or design. Whether fixing bugs, implementing features, or enhancing the user experience—contributors bring fresh perspectives and energy. Their work supports the project’s evolution, bridging the gap between the project’s goals and the community’s needs.

This role does not require any permissions on the GitHub Project.

How to Become a Contributor

You can be a Contributor by opening a Pull Request following our guidelines on submitting a contribution.

For your contribution to be accepted, each individual must sign our CLA, ensuring that their contributions comply with our legal requirements.

Paul Botsco (our friendly CLA Bot) will comment on your first pull request, providing you with the latest links and helpful information. It will also provide feedback should you have missed any of our contribution guidelines.

Once the CLA is signed, contributors can engage with the project by opening issues to report bugs, request features, or suggest improvements. They can also submit pull requests (PRs) to offer code, documentation, or design enhancements.

In the rare event that the CLA text is updated, Paul Botsco will comment on your next pull request to guide you through the process again.

This role does not require any permissions changes.

Next level: Project Maintainer

1.3 - Project Maintainer

The Project Maintainer is the backbone of a project’s success, balancing technical leadership with community engagement. They curate contributions, ensure code quality, and manage project direction. With an eye for detail and a commitment to the project’s vision, maintainers foster an inclusive and collaborative environment, enabling consistent growth and innovation.

Each project has a GitHub Team which contains it’s maintainers. It is named @sonatype-nexus-community/[PROJECT] - e.g. @sonatype-nexus-community/the-cla.

Project Maintainers are also Code Owners for the respective project - thus the CODEOWNERS file for the project should include the above team.

How to Become a Maintainer

Contributors who demonstrate consistent commitment to a project, offering meaningful improvements and actively engaging in discussions, may be considered for a maintainer role.

Becoming a maintainer requires building long-term trust with the Organizational Admins and the project’s existing maintainers. This trust is earned through high-quality contributions, design proposals, and a clear understanding of the project’s vision.

Maintainers not only contribute technically but also help guide the project’s direction by reviewing PRs, managing issues, and fostering collaboration within the community.

Next level: Organization Admin

1.4 - Organization Admin

The Organization Administrators serve as the strategic overseers of our GitHub organization, responsible for governance, permissions, and maintaining the integrity of the repository ecosystem. Their role ensures seamless collaboration, safeguards project resources, and provides stewardship over organizational assets — ensuring the community’s long-term sustainability and security.

How to Become an Organization Admin

Organization Admins are selected from the Sonatype OSPO and are entrusted with the responsibility of overseeing the GitHub organization’s logistics. This role is reserved for those who have demonstrated exceptional leadership and a deep understanding of the project ecosystem.

Organization Admins manage permissions, enforce policies, and ensure that this organization remains a secure and collaborative environment. With a maximum of three Organization Admins at any time, this role requires a proven track record of dedication, trustworthiness, and strategic vision within the open-source community.

2 - Contributing to a Project

We thank you in advance for contributing to our Open Source Community!

Contributions come is all shapes and sizes - and we welcome them all. We ask that for the benefit of the wider community the following guidelines are followed depending on the contribution you wish to make.

  • 💡Want to discuss an idea?
    Read our guide on discussions and ideas here.

  • 🪲 Want to report a bug or issue?
    Read our guide on issue reporting here.

  • 🧑‍💻 Want to contribute a change?
    Read our guide on sumitting contributions here.

2.1 - Discussing Ideas

Ideas are great! 💡 We welcome input from any project users.

If you want to raise one, or join the discussion, we recommend all projects use GitHub Discussions.

Please make sure you follow our Code of Conduct at all times.

2.2 - Reporting Issues or Bugs

While many of these open source efforts are supported by contributors from Sonatype, these Open Source Projects are not officially supported through Sonatype’s commercial support channels.

Please review the latest pull requests, issues, and commits to understand a projects readiness for contribution and use.

DO file suggestions and requests on the project in question using GitHub Issues, so that the community can pitch in and maintainers can easily find your input.

DO use or contribute to a Sonatype Open Source Project according to your organization’s policies and your own risk tolerance.

DON’T file Sonatype support tickets related to a Sonatype Open Source Project — it won’t reach the right people that way.

Last but not least of all: Have fun!

2.3 - Submitting a Contribution

We welcome contributions via Pull Requests to our Community Projects.

Please ensure they meet these guidelines:

  1. Has a clear and singular purpose
  2. It is backed by one or more GitHub Issues in the project
  3. Has appropriate test coverage for the Pull Requests purpose (if you add or modify functionality, make sure you add tests for this!)
  4. Meet the Projects Code Style Convention and Contribution Guidelines (see CONTRIBUTING.md in the specific Project)

If you haven’t yet, please review the requirements for contributors.

Contribution Requirements

Signed Commits

In order to help verify the authenticity of contributed code, we ask that your commits be signed. All commits must be signed off to show that you agree to publish your changes under the current terms and licenses of the project.

Here are some notes we found helpful in configuring a local environment to automatically sign git commits: - GPG commit signature verification - Telling Git about your GPG key

3 - Starting a New Project

You can share your idea for a new Project by starting a Discussion here.

Organization Admins can execute the below procedure to create new Project within the Sonatype Open Source Community.

Prerequisites

  • Ensure you have defined a clear purpose for the new project
  • Maintaniers of the project must have previously contributed to another Sonatype Open Source Project

Creating the Project

  • Create a new GitHub Repository in the Sonatype Community GitHub Organization using the Community Project Template as the template repository

    This will cause a number of default files to be placed into your new repository. It will also automatically inherit a number of Organization defined files that you do not need to redefine in your project.

GitHub Repository Configuration

See our GitHub Repository Configuration Standards.

4 - Project Standards

This section includes information relating to our Standards that we expect our Community Projects to adhere to.

4.1 - GitHub Repository

This page documents the configuration that must be applied to each Project’s GitHub Repository.

General Settings

These settings are found under Settings -> General.

  • Require contributors to sign off on web-based commits must be enabled ✅
  • Default branch should be named main
  • Features:
    • Wikis should be disabled ❌
    • Issues must be enabled ✅
    • Sponsorhips must be disabled ❌
    • Preserve this repository should be enabled ✅
    • Discussions should be enabled ✅
    • Projects should be disbaled ❌
  • Pull Requests:
    • Allow merge commits should be enabled ✅
    • Allow squash merging should be enabled ✅
    • Allow rebase merging should be disabled ❌
    • Always suggest updating pull request branches should be enabled ✅
    • Allow auto-merge should be disabled ❌
    • Automatically delete head branches should be enabled ✅

Code and automation

Branches

These settings are found under Settings -> Code and automation -> Branches.

The following Branch protection rules should be applied.

main
  • Require a pull request before merging Yes ✅
    • Require approvals Yes - 1 ✅
    • Dismiss stale pull request approvals when new commits are pushed TBC
    • Require review from Code Owners Yes ✅
    • Allow specified actors to bypass required pull requests No ❌
  • Require status checks to pass before merging Yes ✅
  • Require signed commits Yes ✅
  • Allow force pushes No ❌
  • Allow deletions No ❌

Actions

  • Fork pull request workflows from outside collaborators set to Require approval for first-time contributors

Custom Properties

Set both Flagship-Project and Project-Status accordingly.

Security

Code security and analysis

4.2 - Standard Files

This page outlines a set of required standard files and their contentst that each Project must adhere to.

If you created your GitHub Repository from our Community Template, these files will be created in your repository - you’ll just need to amend content as directed below.

Files YOU should create

Code Owners

Every repository must define who owns it.

Here are some groups you can reference if appropriate:

GroupPurpose
@sonatype-nexus-community/community-leadersLeaders of the Sonatype Open Source Community

Template files from the Community Project Template

Contributing

This file contains project-specific information aiding others in providing contributions to the project. We recommend using the template and expanding to include your project specific information such as:

  • Development Guidelines
  • Coding Conventions
  • How to test and testing expectations

License

This file contains the Open Source license applicable to this project. You can just copy the license from the template repository.

Readme

This is your projects “shop-window”. We’ve provided a boilerplate template for you. Use this to introduce the project, define it’s purpose, explain how to use it etc…

You should not repeat information contained in other documentation files (such as Contributing), but you should link to other documentation files.

Organization Defined Files

The following files are defined at the GitHub Organization level (in this repository) and you DO NOT need to copy or reproduce them in your project.

Code of Conduct

This file defines our conduct to define community standards, signal a welcoming and inclusive project, and outline procedures for handling abuse.

Security Policy

Provides instructions for how to report a security vulnerability in your project by adding a security policy to your repository.

4.3 - CI Tooling

The accepted standard is to use GitHub Actions for all automated Build, Test, CI and Release functions.

Historically, CircleCI was used, but projects must now make the migration to GitHub Actions as of September 2024.

4.4 - Code Quality

We require all Sonatype Community Projects to undertake scans by SonarCloud (first party code analysis) and Sonatype Lifecycle (third party dependency analysis) as a minimum.

First Party Code Analysis

We utilise SonarCloud’s Automatic Analysis.

Request your project is added to the Sonatype Nexus Community Sonar Cloud instance by reaching out to the Community Maintainers.

Once configured in SonarCloud, analysis will be automatic. You should configure SonarCloud Analysis as a required check for PRs into your main branch.

Additional configuration can be controlled by through the use of a .sonarcloud.properties file - read more here.

Status Badge

We encourage projects to include a SonarCloud status badge in their readme. An example to add to your README might be as follows:

[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=sonatype-nexus-community_community-handbook.sonatype.com&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=sonatype-nexus-community_community-handbook.sonatype.com)

Replace community-handbook.sonatype.com with your repository name.

Dependency Analysis

We utilise a dedicated Cloud instance of Sonatype Lifecycle for Sonatype Community Projects.

To add analysis, you should include something similar to the below GitHub Workflow example below.

name: Continue Integration Checks

on:
  pull_request:

  push:
    branches:
      - main

  workflow_dispatch:

# Env Vars
env:
  LC_APPLICATION_ID: $(echo "${{ github.repository }}" | cut -d '/' -f2)

jobs:
 
  # You might have other jobs to run in parallel here  

  code_quality:
        name: Code Quality
        runs-on: ubuntu-latest
        timeout-minutes: 5
        steps:
            - name: Checkout Code
              uses: actions/checkout@v4
              with:
                  # Disabling shallow clone is recommended for improving relevancy of reporting
                  fetch-depth: 0

            # Run any preparation steps here - such as `npm install`

            - name: Sonatype Lifecycle Evaluation
              uses: sonatype-nexus-community/iq-github-action@master
              with:
                  serverUrl: ${{ secrets.SONATYPE_LIFECYCLE_URL }}
                  username: ${{ secrets.SONATYPE_LIFECYCLE_USERNAME }}
                  password: ${{ secrets.SONATYPE_LIFECYCLE_PASSWORD }}
                  applicationId: ${{ env.LC_APPLICATION_ID }}
                  stage: Build
                  target: .

The referenced secrets are provided at a GitHub Organization level.

4.5 - Dependency Management

We use Sonatype Lifecycle to ensure our Community Projects use only the best open-source dependencies.

Each project should include Sonatype Lifecycle analysis scans during each Pull Request and upon each Release.

You can check out the real world implementation for this handbook - here for Continuous Integration and here for Release.

When implementing your scans, do reference the official Sonatype Lifecycle documentation that relates to the langugages and ecosystems in the project.

Example GitHub Action for Continuous Integration

env:
    LC_APPLICATION_ID: community-handbook.sonatype.com # <-- Our standard is to use the GitHub Repository Name

jobs:
    release:
        ...
        steps:
        ...
            - name: Sonatype Lifecycle Evaluation
              id: evaluate
              uses: sonatype/actions/evaluate@v1.0.1
              with:
                  iq-server-url: ${{ vars.SONATYPE_PLATFORM_URL }}
                  username: ${{ secrets.SONATYPE_LIFECYCLE_USERNAME }}
                  password: ${{ secrets.SONATYPE_LIFECYCLE_PASSWORD }}
                  application-id: ${{ env.LC_APPLICATION_ID }}
                  scan-targets: '.'
                  stage: build # <!-- Set to 'build' for the Continuous Integration
    ...

Example GitHub Action for Release

env:
    LC_APPLICATION_ID: community-handbook.sonatype.com # <-- Our standard is to use the GitHub Repository Name

jobs:
    release:
        ...
        steps:
        ...
            - name: Sonatype Lifecycle Evaluation
              id: evaluate
              uses: sonatype/actions/evaluate@v1.0.1
              with:
                  iq-server-url: ${{ vars.SONATYPE_PLATFORM_URL }}
                  username: ${{ secrets.SONATYPE_LIFECYCLE_USERNAME }}
                  password: ${{ secrets.SONATYPE_LIFECYCLE_PASSWORD }}
                  application-id: ${{ env.LC_APPLICATION_ID }}
                  scan-targets: '.'
                  stage: release # <!-- Set to 'release' for the Release Workflow
    ...

4.6 - Secrets Management

We currently use GitHub Secrets for our Open Source Community projects.

This is great but currently has one known drawback - PRs from Forks cannot access our secrets and as such Continous Integration GitHub Workflows will fail.

5 - Project Classifications

We use GitHub Custom Properties to indentify a Project’s Classification within our Community.

Custom Properties

Flagship-Project

This is a boolean. Where set to true, this indicates the Project has Flagship Status - i.e. it’s popular or something we want to highlight.

Project-Status

There are four options to choose from:

  1. Active - the project is being actively maintained
  2. Archived - the project is not being maintained
  3. Graduated - the project has been superseded by official Sonatype Project

The fourth option is to leave this field unset. This means the project’s status has not yet been assessed and confirmed.

You can see a list of all Projects that have not yet been assessed for status by visiting here.

5.1 - Graduation Process

For some of our Community Projects, there comes a time where Sonatype officially supports the features or functions provided by a Community Project. In these situations we mark the Community Project as Graduated by following the below process.

Graduation Preparation

Project Graduation Proposal

For the sake of historical context and community insight, a GitHub Issue should be created to explain the reasoning and expectations for graduation. This is benefitial even in cases where community engagement is low.

Look here to see a great real-world example!

Project Graduation Notice

The Community Project should have it’s README on it’s main branch updated to contain an appropriate Graduation Notice. An example might be:

> ℹ️ As of 7th November 2024, this community project has [graduated](https://contribute.sonatype.com/docs/project-classification/) and is offered as part of Sonatype's commercial offerings - see [here](https://help.sonatype.com/en/configuring-blob-stores.html#google-cloud-blob-store) for full details.
>
> 🚧 This community project will receive no further updates or maintenance.

It’s good practice to be specific about when the project graduated, and where interested parties can head to find out more.

CI/CD Closure

Any existing CI/CD configuration should be removed and projects deprovisioned from CI/CD systems.

Project Properties

The projects Custom Properties should be updated to reflect the Graduated status.

Open Issues

Any open issues should be closed with a notice of the graduation.

Graduating

Once the preparation steps are executed, the project should be marked as archived in GitHub.

6 - How To Guides

This section contains some guidance for various scenarios and tool usage.

6.1 - Running GitHub Actions Locally

You can locally test the GitHub Actions defined in this your project using nektos act.

Setup

Simply run:

act

Rancher Desktop on Mac

If you are using Rancher Desktop on Mac, you may see errors like this:

%  act -j build
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' 
[Continuous Integration/build] 🚀  Start image=ghcr.io/catthehacker/ubuntu:act-latest
[Continuous Integration/build]   🐳  docker pull image=ghcr.io/catthehacker/ubuntu:act-latest platform= username= forcePull=true
Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

You can print out your Docker contexts with the following command:

% docker context ls
NAME                DESCRIPTION                               DOCKER ENDPOINT                         ERROR
default             Current DOCKER_HOST based configuration   unix:///var/run/docker.sock             
rancher-desktop *   Rancher Desktop moby context              unix:///Users/bhamail/.rd/docker.sock

You can set the DOCKER_HOST environment variable as shown below which will allow act to use the correct Docker context:

export DOCKER_HOST=$(docker context inspect | jq -r '.[0].Endpoints.docker.Host')

See: slight modification that helps for rancher desktop

Apple Silcon

If running on Apple Silicon (ARM), launch act with this flag:

   act --container-architecture linux/amd64

Without this flag, I saw this warning:

WARN  ⚠ You are using Apple M-series chip and you have not specified container architecture, you might encounter issues while running act. If so, try running it with '--container-architecture linux/amd64'. ⚠

and this error:

...   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/1] user= workdir=
| docker compose build
[+] Building 0.0s (0/0)                                                         
| permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock: Get "http://%2Fvar%2Frun%2Fdocker.sock/_ping": dial unix /var/run/docker.sock: connect: permission denied
...

Usage

To get a list of available jobs, run:

    $ act -l

To run a specific job, use the -j flag:

    $ act -j <job-name>

For example, to run the build job from the ci.yml file, use this command:

    $ act --workflows .github/workflows/ci.yml -j build