From f3fdc3f1384593fbd234cf4229698ccd54743e62 Mon Sep 17 00:00:00 2001 From: Zdenek Kraus Date: Thu, 16 Oct 2025 14:42:40 +0200 Subject: [PATCH 1/4] ADD: DESIGN_GUIDE.md Design guide is suppose to be a set of guidelines and tips on how to desing tests, write commits, submit a review PRs, and anything that might be usefull. --- DESIGN_GUIDE.md | 67 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 DESIGN_GUIDE.md diff --git a/DESIGN_GUIDE.md b/DESIGN_GUIDE.md new file mode 100644 index 000000000..233a25bcd --- /dev/null +++ b/DESIGN_GUIDE.md @@ -0,0 +1,67 @@ +# The Design Guide - How to design tests, and how to review them + +This is not a rule book, just a compilation of guidelines, tips, and thoughts. + +## Atomic tests + +While atomic test cases are a great way of designing test at unit test level, +for End-to-End tests it might not be great Return of Investment. But please consider +atomic test case design principles in your test design. + +* Is it possible to extract some portion of my test into fixture/setup? +* Could some of it be reused by multiple test cases? +* Is that possible to do, while not destroying tests runtime or making complex fixture desing? + +Just considering the principles, might give you an idea of new test cases, that +might be useful to write. + +## Commits + +1. Consider using https://www.conventionalcommits.org/en/v1.0.0/ (.gitmessage) + +## Creating PRs + +1. To promote quality code, request 2 reviewers +1. Link relevant issues, and/or summarize the changes +1. Consider providing a verification steps in the PR description (might have a tool for that) + +## Reviewing PRs + +1. Focus on readability +1. Is the test placed in correct path? +1. Consider test structure and design, can it be improved without impacting runtime? +1. Is the test easy to debug on Failure or Error? + +### precommit hook + +Consider using some secret guarding precommit hooks in your git setup, to prevent secret leaking. + +### .gitmessage + +Currently optional, you may use a file (conventionally) named `.gitmessage`, +and configure your git to use it as a commit message template. + +For example `.gitmessage`: + +```text +# test: +# test(): + +# Description: + + +# Footer: + + +# See also: https://www.conventionalcommits.org/en/v1.0.0/ +``` + +And git configuration: + +```shell +git config commit.template=.gitmessage +``` + +next time you commit, your editor will be prefilled with the templates, and as +usual, anything that is a comment `#` will be ignored. + From c6ae09fc30009b06dc9ae26f89ce53cb9e9239d2 Mon Sep 17 00:00:00 2001 From: Zdenek Kraus Date: Mon, 13 Apr 2026 15:37:37 +0200 Subject: [PATCH 2/4] Update DESIGN_GUIDE.md Co-authored-by: Emma Roche --- DESIGN_GUIDE.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/DESIGN_GUIDE.md b/DESIGN_GUIDE.md index 233a25bcd..86981ec94 100644 --- a/DESIGN_GUIDE.md +++ b/DESIGN_GUIDE.md @@ -24,6 +24,8 @@ might be useful to write. 1. To promote quality code, request 2 reviewers 1. Link relevant issues, and/or summarize the changes 1. Consider providing a verification steps in the PR description (might have a tool for that) +1. Ensure CI checks pass before opening a PR (e.g., DCO sign-off, code analysis, GitGuardian) +1. Use a draft PR to share work in progress and gather early feedback before marking it ready for review ## Reviewing PRs From 5d6d31a6ae1dfe70c1f9e8d42c837f5be877aef8 Mon Sep 17 00:00:00 2001 From: Zdenek Kraus Date: Mon, 13 Apr 2026 15:37:45 +0200 Subject: [PATCH 3/4] Update DESIGN_GUIDE.md Co-authored-by: Emma Roche --- DESIGN_GUIDE.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/DESIGN_GUIDE.md b/DESIGN_GUIDE.md index 86981ec94..73b9b4edb 100644 --- a/DESIGN_GUIDE.md +++ b/DESIGN_GUIDE.md @@ -18,6 +18,9 @@ might be useful to write. ## Commits 1. Consider using https://www.conventionalcommits.org/en/v1.0.0/ (.gitmessage) +1. Run `make reformat` and `make commit-acceptance` locally to catch code analysis or formatting issues before committing and pushing +1. Sign off commits by adding the `-s` flag (`git commit -s`) +1. Optionally, sign commits with the `-S` flag (`git commit -S`) if you have a GPG or SSH key configured — this verifies commit authenticity on GitHub ## Creating PRs From da376699ceb42d907530909c8ff80fe404124f7d Mon Sep 17 00:00:00 2001 From: Zdenek Kraus Date: Mon, 13 Apr 2026 15:51:12 +0200 Subject: [PATCH 4/4] Distilled an update of DESIGN_GUIDE.md from CLAUDE.md where the rules are written and up to date. Signed-off-by: Zdenek Kraus --- DESIGN_GUIDE.md | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/DESIGN_GUIDE.md b/DESIGN_GUIDE.md index 73b9b4edb..1ccdf1413 100644 --- a/DESIGN_GUIDE.md +++ b/DESIGN_GUIDE.md @@ -15,6 +15,26 @@ atomic test case design principles in your test design. Just considering the principles, might give you an idea of new test cases, that might be useful to write. +## Fixture Design + +1. Use simple, descriptive names: `route`, `authorization`, `backend`, `gateway`, `hostname`, `client` +1. For multiple instances of the same resource, append a number to secondary resources: `route2`, `backend2`, `authorization2` +1. The primary resource always uses the plain name without a number +1. Use `blame()` to generate unique, scoped names for Kubernetes resources: `blame("gw")` → `"gw-alice-tc-abc"` +1. Choose appropriate fixture scope: + * `scope="session"` - Created once per test run (e.g., `cluster`, `backend`, `gateway`) + * `scope="module"` - Created per test module (e.g., `route`, `authorization`, `rate_limit`) + * `scope="function"` - Created per test (rarely used, only for parametrized or stateful tests) + +## Code Quality + +1. **Every module and fixture must have a short, descriptive docstring** + * Module docstrings describe the test scope + * Fixture docstrings describe what they create or return, not how +1. **Always look for a more correct solution before disabling a pylint warning** + * Legitimate uses: `# pylint: disable=unused-argument` for pytest dependency ordering + * Legitimate uses: `# pylint: disable=invalid-name` for Kubernetes API camelCase fields + ## Commits 1. Consider using https://www.conventionalcommits.org/en/v1.0.0/ (.gitmessage) @@ -26,7 +46,7 @@ might be useful to write. 1. To promote quality code, request 2 reviewers 1. Link relevant issues, and/or summarize the changes -1. Consider providing a verification steps in the PR description (might have a tool for that) +1. Use the `/pr-description` command to generate comprehensive PR descriptions with verification steps 1. Ensure CI checks pass before opening a PR (e.g., DCO sign-off, code analysis, GitGuardian) 1. Use a draft PR to share work in progress and gather early feedback before marking it ready for review @@ -39,7 +59,19 @@ might be useful to write. ### precommit hook -Consider using some secret guarding precommit hooks in your git setup, to prevent secret leaking. +Consider using secret guarding precommit hooks in your git setup to prevent secret leaking: + +1. Install pre-commit framework: https://pre-commit.com/ +1. Use gitleaks (https://github.com/gitleaks/gitleaks) or similar tools to detect hardcoded secrets +1. Example `.pre-commit-config.yaml`: + ```yaml + repos: + - repo: https://github.com/gitleaks/gitleaks + rev: v8.18.2 + hooks: + - id: gitleaks + ``` +1. Install hooks: `pre-commit install` ### .gitmessage