Project Standards

• 1: GitHub Repository
• 2: Standard Files
• 3: CI Tooling
• 4: Code Quality
• 5: Dependency Management
• 6: Secrets Management

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

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.

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:

[![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.

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

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.