From fd787576b254253cf86e52057c7bfd0e3a898112 Mon Sep 17 00:00:00 2001 From: Niklas Voss Date: Thu, 30 Apr 2026 16:51:48 +0200 Subject: [PATCH] feat: add conventional commits and documentation to onboard new repositories --- .commitlintrc.yml | 15 ++++ .envrc | 5 ++ .github/pull_request_template.md | 19 ++++ .github/workflows/conventional-commits.yml | 41 +++++++++ .gitignore | 1 + docs/CONTRIBUTING.md | 44 +++++++++ docs/NEW_REPO.md | 100 +++++++++++++++++++++ flake.nix | 14 ++- 8 files changed, 237 insertions(+), 2 deletions(-) create mode 100644 .commitlintrc.yml create mode 100644 .envrc create mode 100644 .github/pull_request_template.md create mode 100644 .github/workflows/conventional-commits.yml create mode 100644 docs/CONTRIBUTING.md create mode 100644 docs/NEW_REPO.md diff --git a/.commitlintrc.yml b/.commitlintrc.yml new file mode 100644 index 0000000..c15318b --- /dev/null +++ b/.commitlintrc.yml @@ -0,0 +1,15 @@ +extends: + - "@commitlint/config-conventional" +rules: + type-enum: + - 2 + - always + - - feat + - fix + - docs + - chore + - refactor + - test + - ci + - perf + - revert diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..9f363e1 --- /dev/null +++ b/.envrc @@ -0,0 +1,5 @@ +#!/usr/bin/env bash + +export DIRENV_WARN_TIMEOUT=20s + +use flake diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..67577fc --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,19 @@ +## What + +Closes # + +## Why + + +## Testing + + +## Notes for reviewers + + +## Checklist +- [ ] Tests added/updated +- [ ] No breaking changes (or upgrade path documented above) +- [ ] Readable commit history (squashed and cleaned up as desired) +- [ ] AI code review considered and comments resolved diff --git a/.github/workflows/conventional-commits.yml b/.github/workflows/conventional-commits.yml new file mode 100644 index 0000000..cc9c8dc --- /dev/null +++ b/.github/workflows/conventional-commits.yml @@ -0,0 +1,41 @@ +name: Conventional Commits + +on: + pull_request: + branches: ["main"] + types: [opened, edited, synchronize, reopened] + +permissions: + pull-requests: read + +jobs: + pr-title: + name: PR Title + runs-on: ubuntu-latest + steps: + - uses: amannn/action-semantic-pull-request@v5 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + types: | + feat + fix + docs + chore + refactor + test + ci + perf + revert + requireScope: false + + commitlint: + name: Commit Messages + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + - uses: wagoid/commitlint-github-action@v6 + with: + configFile: .commitlintrc.yml diff --git a/.gitignore b/.gitignore index 360f312..fd6f254 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ .direnv example/common.mk example/bin/ +.pre-commit-config.yaml diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..d33efa6 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,44 @@ +# Contributing to dev-kit + +## Commit Convention + +This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification. Both PR titles and individual commit messages are validated in CI. + +### Format + +``` +(optional scope): +``` + +### Allowed Types + +| Type | Purpose | +| ---------- | ---------------------------------------------------- | +| `feat` | A new feature | +| `fix` | A bug fix | +| `docs` | Documentation changes | +| `chore` | Maintenance tasks (deps, CI config, etc.) | +| `refactor` | Code changes that neither fix a bug nor add a feature | +| `test` | Adding or updating tests | +| `ci` | CI/CD pipeline changes | +| `perf` | Performance improvements | +| `revert` | Reverting a previous commit | + +### Examples + +``` +feat: add commitlint pre-commit hook +fix: use recursive merge for hook overrides +docs: document default git hooks +chore(deps): update nixpkgs input +refactor: extract mkDefaultAttrs helper +``` + +### Breaking Changes + +Append `!` after the type/scope to indicate a breaking change: + +``` +feat!: change mkShell interface +refactor!: rename preCommitHooks parameter +``` diff --git a/docs/NEW_REPO.md b/docs/NEW_REPO.md new file mode 100644 index 0000000..8e88ec8 --- /dev/null +++ b/docs/NEW_REPO.md @@ -0,0 +1,100 @@ +# New Repository Setup + +This guide walks through setting up a new repository in the opendefensecloud organization with dev-kit integration. + +## 1. Create the repository + +Create the repo on GitHub (via UI or `gh repo create`) under the `opendefensecloud` organization. Select `Apache-2.0` as the license. + +## 2. Bootstrap the dev environment + +Copy the files from `example/` into your project root and adjust them: + +- **`flake.nix`** — Set `goVersion`, add extra `packages`, and configure `preCommitHooks` as needed. If your project does not use Go, omit `goVersion`. +- **`Makefile`** — Pin `DEV_KIT_VERSION` to a release tag (e.g. `v1.0.0`). Implement the `fmt` and `lint` targets or disable their pre-commit hooks in `flake.nix`. +- **`tools.lock`** — Add any Go tool dependencies your project needs (one per line: ` @`). +- **`renovate.json`** — Copy as-is. The custom managers handle `DEV_KIT_VERSION` in your Makefile and entries in `tools.lock`. + +Add an `.envrc` for direnv integration: + +```bash +#!/usr/bin/env bash +export DIRENV_WARN_TIMEOUT=20s +use flake +``` + +After copying, run `direnv allow` to activate the dev shell. + +## 3. Configure repository settings + +Run: + +```sh +make repo-settings +``` + +This reconciles labels, merge strategy (merge commits only, auto-merge enabled, delete branch on merge), secret scanning, and the `protect-main` branch ruleset. See `make help` for details. + +## 4. Set up GitHub organization secrets + +The following secrets must be whitelisted for your repository at the organization level +(Settings > Secrets and variables > Actions > Repository access): + +| Secret | Used by | +| -------------------- | ---------------------------------- | +| `ADD_TO_PROJECT_PAT` | `issues-add-to-project` workflow | + +If your project uses private runners, whitelist the repository in the runner group settings +(Settings > Actions > Runner groups). + +## 5. Copy GitHub workflows + +Copy the relevant workflows from `.github/workflows/` in this repository: + +| Workflow | Purpose | +| ------------------------------- | ------------------------------------------------------- | +| `conventional-commits.yml` | Validates PR titles and commit messages against Conventional Commits | +| `issues-add-labels.yaml` | Automatically adds `needs-triage` label to new issues | +| `issues-add-to-project.yml` | Adds new issues and PRs to the org project board | +| `release-drafter.yaml` | Drafts release notes from merged PRs | + +If using release-drafter, also copy `.github/release-drafter.yml` (the config file). + +If using commitlint (recommended), copy `.commitlintrc.yml` to your project root and enable the hook in `flake.nix`: + +```nix +preCommitHooks = { + commitlint.enable = true; +}; +``` + +## 6. Add the pull request template + +Copy `.github/pull_request_template.md` from this repository into your project. It provides a +standard structure for PR descriptions across the organization: + +``` +.github/ + pull_request_template.md +``` + +## 7. Check Renovate onboarding + +Renovate should automatically open an onboarding PR once `renovate.json` is present. +Verify that: + +- The onboarding PR appears and the dependency dashboard is created. +- The custom managers detect `DEV_KIT_VERSION` in your Makefile and entries in `tools.lock`. +- If your project has a `go.mod`, standard Go module updates are picked up as well. + +If Renovate is not enabled, check that the Renovate GitHub App is installed for the organization and has access to your repository. + +## 8. Final checklist + +- [ ] `direnv allow` works and drops you into the dev shell +- [ ] `make help` lists all available targets +- [ ] `make repo-settings` ran successfully +- [ ] GitHub workflows are in place and passing +- [ ] Renovate onboarding PR has been merged +- [ ] Organization secrets are whitelisted for the repo +- [ ] Private runners are whitelisted (if applicable) diff --git a/flake.nix b/flake.nix index 080c9ec..fffaf9b 100644 --- a/flake.nix +++ b/flake.nix @@ -24,7 +24,7 @@ }; }; - outputs = { nixpkgs, git-hooks, go-overlay, gomod2nix, ... }@inputs: { + outputs = { self, nixpkgs, flake-utils, git-hooks, go-overlay, gomod2nix, ... }@inputs: { lib.mkShell = { system, packages ? [], preCommitHooks ? {}, goVersion ? null, shellHook ? "", ... }: let pkgs = import nixpkgs { @@ -91,5 +91,15 @@ pkgs.gotools ]; }; - }; + } // flake-utils.lib.eachDefaultSystem (system: { + devShells.default = self.lib.mkShell { + inherit system; + preCommitHooks = { + fmt.enable = false; + lint.enable = false; + osv-scanner.enable = false; + commitlint.enable = true; + }; + }; + }); }