feat: add conventional commits and documentation to onboard new repos…

.commitlintrc.yml

@@ -0,0 +1,15 @@
+extends:
+  - "@commitlint/config-conventional"
+rules:
+  type-enum:
+    - 2
+    - always
+    - - feat
+      - fix
+      - docs
+      - chore
+      - refactor
+      - test
+      - ci
+      - perf
+      - revert

.envrc

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+export DIRENV_WARN_TIMEOUT=20s
+
+use flake

.github/pull_request_template.md

@@ -0,0 +1,19 @@
+## What
+<!-- One sentence summary -->
+Closes #
+
+## Why
+<!-- Motivation / problem being solved. Skip if obvious from the linked issue. -->
+
+## Testing
+<!-- How was this tested? e.g. unit, envtest, manual against vX.Y.Z -->
+
+## Notes for reviewers
+<!-- CRD/API changes, RBAC changes, new watches, breaking changes, upgrade path.
+     Delete if not applicable. -->
+
+## 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

.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

.gitignore

@@ -1,3 +1,4 @@
 .direnv
 example/common.mk
 example/bin/
+.pre-commit-config.yaml

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
+
+```
+<type>(optional scope): <description>
+```
+
+### 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
+```

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: `<name> <module>@<version>`).
+- **`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)

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;
+      };
+    };
+  });
 }