# 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](https://contribute.sonatype.com/docs/standards/code-quality/) and [Dependency Management](https://contribute.sonatype.com/docs/standards/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](https://contribute.sonatype.com/docs/contributing/reporting-issues/) - **Dependabot** No ❌ - See [Dependency Management](https://contribute.sonatype.com/docs/standards/dependency-management/) - **Code Scanning** No ❌ - See [Code Quality](https://contribute.sonatype.com/docs/standards/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](https://github.com/sonatype-nexus-community/community-project-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](https://contribute.sonatype.com/docs/standards/repository-contents/#organization-defined-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](https://github.com/sonatype-nexus-community/community-project-template/blob/main/CONTRIBUTING.md) 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](https://github.com/sonatype-nexus-community/community-project-template/blob/main/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](https://github.com/sonatype-nexus-community/community-project-template/blob/main/README.md) 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](https://github.com/sonatype-nexus-community/.github)) 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](https://docs.sonarsource.com/sonarcloud/advanced-setup/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](https://docs.sonarsource.com/sonarcloud/advanced-setup/automatic-analysis/#additional-analysis-configuration). ### 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: ```markdown ``` Replace `community-handbook.sonatype.com` with your repository name. ### Dependency Analysis We utilise a dedicated Cloud instance of [Sonatype Lifecycle](/content/products/open-source-security-dependency-management/index.html) for Sonatype Community Projects. To add analysis, you should include something similar to the below GitHub Workflow example below. ```yaml 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](/content/products/open-source-security-dependency-management/index.html) 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](https://github.com/sonatype-nexus-community/the-cla/blob/main/.github/workflows/ci.yml) and here [for Release](https://github.com/sonatype-nexus-community/the-cla/blob/main/.github/workflows/release.yml). When implementing your scans, do reference the [official Sonatype Lifecycle documentation](https://help.sonatype.com/en/analysis.html) that relates to the languages and ecosystems in the project. ### Example GitHub Action for Continuous Integration ```yaml 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 #