repo-conventions

RepoConventions

Applies shared repository conventions.

RepoConventions applies shared repository conventions from a .github/conventions.yml file.

Quick Start

Install the tool globally, or run it ad hoc with dnx.

dotnet tool install --global repo-conventions
# or
dnx repo-conventions --help

Create .github/conventions.yml in the repository you want to manage.

For example, to add a convention that installs a workflow that opens a PR nightly when convention changes are needed:

repo-conventions add Faithlife/CodingGuidelines/conventions/repo-conventions-workflow

This is the .github/conventions.yml that should have been created:

conventions:
  - path: Faithlife/CodingGuidelines/conventions/repo-conventions-workflow

Commit .github/conventions.yml, then run repo-conventions apply from the repository root, which creates and commits the workflow. Use repo-conventions add <path> --open-pr to add the reference, apply it, and open a PR in one run.

Configuration

RepoConventions reads .github/conventions.yml.

• conventions is required and lists convention references in the order they are applied.
• Each convention entry must have path and may have settings.
• Use pull-request to control the settings of any PR opened by repo-conventions apply --open-pr.

Regarding convention paths:

• Remote paths use owner/repo/path@ref. If path is omitted, the repository root is used. If @ref is omitted, the remote default branch is used.
• Local relative paths start with ./ or ../ and are resolved relative to the configuration file, or start with / and are resolved from the repository root.

CLI

repo-conventions add <path> [<path> ...] adds convention references to .github/conventions.yml, creating the file if needed.

repo-conventions add <path> --open-pr adds convention references, commits them, applies conventions, and opens or updates a PR for the created commits.

repo-conventions apply applies configured conventions and creates commits as needed.

repo-conventions apply --open-pr applies conventions, creates commits, and opens or updates a PR for any created commits.

When applying conventions, run from the repository root, and start with a clean working tree. With --open-pr, there should also be no unpushed local commits.

More Documentation

• Detailed configuration
• Authoring conventions