Administrative Projects

Administrative Projects and their requirements #

This document describes the baseline setup for Administrative projects of the OpenRail Association. Administrative projects are internal tools and configurations that support the OpenRail Association’s operations. They are not incubated projects but still follow high standards.

purl-tools is a good reference implementation that applies all practices described below.

Repository Settings #

Configure the repository with these settings:

  • Require pull request reviews: At least 1 approval before merging (for repos with multiple maintainers)

GitHub Actions Permissions #

Under Settings → Actions → General:

  • Set “Fork pull request workflows from outside collaborators” to Require approval for all outside collaborators
  • Set “Workflow permissions” to Read repository contents and packages permissions (least privilege)

Badge and Listing #

All administrative projects must display the OpenRail Administrative badge in their README.md:

[![OpenRail Administrative Project](https://openrailassociation.org/badges/openrail-project-admin.svg)](https://link.openrailassociation.org/admin-projects)

They must also be listed in the OpenRail Projects overview under the “Administrative Projects” section.

Python Projects #

For Python-based projects, we strongly recommend uv as the package manager and build tool, ruff for linting and formatting, and ty for type checking. See purl-tools for a working example of pyproject.toml and the CI test workflow.

The CI test workflow must run at minimum:

  • Linting and format checking (ruff)
  • Type checking (ty)
  • Functional tests on all supported Python versions (if applicable)
  • REUSE compliance check

Security Practices #

Administrative projects follow the security best practices, which includes the following mandatory items:

  • Dependency management: Use Renovate extending the shared OpenRail configuration for automated dependency updates and pinned action digests
  • CI workflow security: Run zizmor to detect security issues in GitHub Actions workflows
  • Vulnerability monitoring: Run a weekly check of the latest release against vulnerability databases (for projects that publish releases)
  • Security policy: Provide a SECURITY.md as described in the security practices

Depending on the type of the project, certain practices may be relaxed. Check the linked security practices document for indicators.

Releases #

Administrative projects automate their releases using release-please and Conventional Commits. Since squash merging is enforced, the PR title serves as the commit message and must follow the Conventional Commits format. See release practices for details and purl-tools for a working example.

Depending on the project, this requirement can be relaxed. Check the linked release practices document for indicators.

Licensing #

All administrative projects must be REUSE compliant.

Summary Checklist #

When creating a new administrative project: