Project Standards | Sonatype Open Source Community Handbook

Project Standards

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

1 - GitHub Repository

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

The use of must and should indicate whether it is a requirement or strong guideline.

Any setting not explicitly documented below is not considered part of the standards at the time of publication.

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 disabled ❌
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 ✅
- Checks according to Code Quality and Dependency Management must be covered
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

Private vulnerability reporting No ❌ - See Reporting Issues
Dependabot No ❌ - See Dependency Management
Code Scanning No ❌ - See Code Quality
Secret scanning TBC

2 - Standard Files

This page outlines a set of required standard files and their contents 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.

There are a number of files you might think need creating that are not in the Template - see Organization Files.

Files YOU should create

Code Owners

This file must be named CODEOWNERS and be in the .github folder at the root of your project.

Every repository must define who owns it.

Here are some groups you can reference if appropriate:

Group	Purpose
`@sonatype-nexus-community/community-leaders`	Leaders of the Sonatype Open Source Community

Template files from the Community Project Template

Contributing

This file must be named CONTRIBUTING.md and be in the root of your project.

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 must be named LICENSE and be in the root of your project.

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

The approved license for Sonatype Community Projects is Apache-2.0.

Readme

This file must be named README.md and be in the root of your project.

This is your projects “shop-window”. We’ve provided a boilerplate template for you. Use this to introduce the project, define its 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.

There must be a section The Fine Print at the end of the file as per the template.

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.

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 - 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:

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
ev:
  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.

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 languages 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
    ...

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 Continuous Integration GitHub Workflows will fail.