trask / repository-practices

OpenTelemetry common repository practices

This repository exists to document common reposiory practices used across OpenTelemetry, with a couple of goals in mind:

• to help maintainers to discover new practices which are working for others and could help them as well
• to evolve these common practices over time with the input and learnings from everyone

Important: it is not a goal to document or describe anything here as "best practices", because there is too much variation and nuance, and the OpenTelemetry project values the independence and flexibility of individual repositories to define what is "best" for their respective communities.

• General automation
• Release automation
• General GitHub Actions practices
• Linting
• Security
• Issue management
• Pull request management
• Repository settings
• Contrib repository component owners

repository-practices's Issues

GitHub action versions

pin major version, e.g. actions@v3, instead of [email protected]

use dependabot to update them

Add example about collapsing the checks even with conditional jobs

Add example about collapsing the checks even with conditional jobs, e.g.

https://github.com/open-telemetry/opentelemetry-java/blob/81821296fc16a7e442becd65868f912e945b4ca8/.github/workflows/build.yml#L83-L89

Add markdown lint

(see spec repo)

Have backport workflow merge change log properly

Using variables to reduce/group dependabot updates

commenting test

Add .editorconfig?

Rename to .repository?

And include reusable workflows (linting) and composite actions (change log management to help with backporting and releasing)

Explicitly declare permissions needed for each github actions?

e.g.

# This workflow warns and then closes issues and PRs that have had no activity for a specified amount of time.
#
# You can adjust the behavior by modifying this file.
# For more information, see:
# https://github.com/actions/stale
name: Mark stale issues and pull requests

on:
  schedule:
  - cron: '44 8 * * *'

jobs:
  stale:

    runs-on: ubuntu-latest
    permissions:
      issues: write
      pull-requests: write

    steps:
    - uses: actions/stale@v5
      with:
        repo-token: ${{ secrets.GITHUB_TOKEN }}
        stale-issue-message: 'Stale issue message'
        stale-pr-message: 'Stale pull request message'
        stale-issue-label: 'no-issue-activity'
        stale-pr-label: 'no-pr-activity'

Put file links inside back ticks

e.g. CHANGELOG.md

Change log management?

To avoid PRs running into change log merge conflicts, have a section in the PR template to add the change log entry.

Then this can be copied over to backport PR.

And as part of release preparation, change log can be updated.

Codespaces?

See if reusable workflows can meet spec repo needs