diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 53c2300..61f828b 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,10 +1,20 @@ + ## Description +## Breaking changes + + + +## Validation + + + ## Checklist + - [ ] I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/fleet-intelligence-client/blob/main/CONTRIBUTING.md). -- [ ] My commits are signed off (`git commit -s`) per the [Contributing Guidelines](https://github.com/NVIDIA/fleet-intelligence-client/blob/main/CONTRIBUTING.md#signing-off-your-work). +- [ ] My commits are signed off (`git commit -s`) with my real name and valid email per the [Contributing Guidelines](https://github.com/NVIDIA/fleet-intelligence-client/blob/main/CONTRIBUTING.md#signing-off-your-work). - [ ] New or existing tests cover these changes. - [ ] The documentation is up to date with these changes. diff --git a/.github/workflows/contribution-conventions.yml b/.github/workflows/contribution-conventions.yml new file mode 100644 index 0000000..33adc79 --- /dev/null +++ b/.github/workflows/contribution-conventions.yml @@ -0,0 +1,26 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 +name: Contribution conventions + +on: + pull_request: + types: [opened, edited, synchronize, reopened, ready_for_review] + +permissions: + contents: read + +jobs: + pr-title: + name: PR title + runs-on: ubuntu-latest + steps: + - name: Validate PR title + env: + PR_TITLE: ${{ github.event.pull_request.title }} + shell: bash + run: | + pattern='^(feat|fix|perf|refactor|docs|chore|test|revert)(\([a-z0-9._/-]+\))?!?: [^[:space:]].*$' + if [[ "$PR_TITLE" == *$'\n'* || ! "$PR_TITLE" =~ $pattern ]]; then + echo "::error::Expected PR title: type(scope): description (scope optional; use ! for breaking changes)." + exit 1 + fi diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b87e6a9..22e7b89 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -119,7 +119,8 @@ Additional labels must be applied to indicate whether the change is a feature, i ### Local Git hooks Local hooks are optional but recommended. They check commit subject formatting -and scan staged files for secrets before commit. +and scan staged files for secrets before commit. See the shared conventions +below for the shared conventions and PR-title validation. Install `trufflehog` before enabling the hooks: @@ -155,21 +156,39 @@ Release branches may be created for stabilization or hotfix work when needed. If a release branch exists, maintainers will document the target branch in the issue or release notes. -### Branch naming +## Commit and Pull Request Conventions -Branches used to create PRs should have a name of the form `/`, -where `` is one of: +Use the same format for commit subjects and pull request titles: -- `feat` for new features. -- `fix` for bugs or regressions. -- `docs` for documentation changes. -- `test` for test-only changes. -- `chore` for maintenance. - -Use a short dash-separated name after the slash, for example `feat/node-tags` -or `docs/report-examples`. - -### Release notes +```text +(): +``` -Pull request titles are used to generate release notes. Make them concise and -descriptive of the user-visible change. +- Allowed types: `feat`, `fix`, `docs`, `test`, `refactor`, `perf`, `chore`, `revert`. +- Scope is optional and lowercase, for example `cli`, `inventory`, or `deps`. +- Write a concise, imperative description, for example `fix(inventory): handle missing chassis`. +- For breaking changes, add `!` after the type/scope, for example `feat(cli)!: remove deprecated flag`, and explain the impact and migration in the PR body. +- Sign off every commit with `git commit -s`, using your real name and a valid email address, to comply with the DCO. +- Name branches `/`, for example `fix/missing-chassis` or `docs/configuration-guide`. Use one of the allowed types above. +- Target `main` unless maintainers specify a release branch. + +PR descriptions must explain the behavior change, link related GitHub issues +(use `Closes #123` when appropriate), report validation and remaining limitations, +and highlight breaking changes. Add relevant tests and documentation, follow the +PR template, and ensure CI passes. PR titles describe the final user-visible +result and may appear in release notes. + +Maintainers should **squash merge** each focused PR, using the PR title as the +final commit subject. Contributors may keep separate review commits; they do not +need to squash before review. Preserve all contributors' DCO `Signed-off-by:` +trailers in the final squash commit and verify the final message before merging. + +### PR title validation + +The **Contribution conventions / PR title** GitHub Actions check validates PR +titles when a PR is opened, edited, or updated. Maintainers should require this +check in branch protection and configure squash merging to use the PR title as +the final commit subject. Local commit-format hooks are optional; individual +commit messages do not become target-branch subjects when squash merging. +Contributors must still sign off every commit, and maintainers must preserve +those sign-offs in the final squash commit.