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.
This is the multi-page printable view of this section. Click here to print.
Contributing to Sonatype Community Projects
- 1: Contributing to a Project
- 2: Starting a New Project
- 3: Project Standards
- 3.1: GitHub Repository
- 3.2: Standard Files
- 3.3: CI Tooling
- 3.4: Code Quality
- 3.5: Dependency Management
- 3.6: Secrets Management
- 4: Project Classifications
- 5: How To Guides
1 - 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.
1.1 - Discussing Ideas
Ideas are great π‘
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.
1.2 - Reporting Issues or Bugs
Whilst these open source efforts are supported by Sonatype Contributors, 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.
File suggestions and requests on the Sonatype Open Source Project in question using GitHub Issues, so that the community can pitch in.
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!
1.3 - Submitting a Contribution
We welcome contributions via Pull Requests to our Community Projects.
Please ensure they meet these guidelines:
- Has a clear and singular purpose
- It is backed by one or more GitHub Issues in the project
- Has appropriate test coverage for the Pull Requests purpose (if you add or modify functionality, make sure you add tests for this!)
- Meet the Projects Code Style Convention and Contribution Guidelines (see
CONTRIBUTING.md
in the specific Project)
If you’ve not signed our latest Contributor License Agreement (CLA), you’ll be prompted on the Pull Request by our CLA Bot - PaulBotsco.
2 - Starting a New Project
You can share your idea for a new Project by starting a Discussion here.
Note
Only Organizational Owners 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
- To be a maintanier or owner of a project, you need to have previously contributed to another Sonatype Open Source Project
Info
Having contributed previously means you’ll have signed our CLA and understand our Community workflows.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
3 - Project Standards
This section includes information relating to our Standards that we expect our Community Projects to adhere to.
3.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
3.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
.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 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.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.
3.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.
3.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
...
3.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.
4 - 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:
- Active - the project is being actively maintained
- Archived - the project is not being maintained
- 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 - How To Guides
This section contains some guidance for various scenarios and tool usage.
5.1 - Running GitHub Actions Locally
You can locally test the GitHub Actions defined in this your project using nektos act.
Setup
Simply run:
act
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