Proposal for management of step name length and number of steps within centralized linter model

[PedroDiez]

Problem description

After applying centralized linter model in PredictiveConnectivityData, some linter configurations are still raising and some way forward would like to be proposed.

Expected behavior

Step name is too long: proposal would be to extend length up to 250 characters and enabler this checking as a warning not an error due to the nature and semantic of a step can vary a lot among different APIs and test scenarios

Element Scenario too long: Configured value of 15 seems very reasonable. However it may happen that specific tests due to their nature could exceed this limit. For this reason it is proposed to settle this linter checking as a warning instead of an error.

Alternative solution

For Step name is too long in case the configured limit is considered reasonable just to enabler this linter checking as a warning

Additional context

PredictiveConnectivityData/pull/36

[hdamker]

@PedroDiez My thinking is that the rules should be decided within Commonalities (currently still home of artifacts/linting_rules/.gherkin-lintrc), also about warning vs error. The tooling repository is than only about the implementation what has been decided within Commonalities.

If you see it the same, I would transfer the issue to Commonalities.

Note: currently the linter checks are not blocking a PR merge, so exceptions can be discussed case by case as well.

cc: @Kevsy @rartych

[PedroDiez]

It is fine @hdamker

[hdamker]

There is a related discussion opened by @FabrizioMoggio in #519.

My understanding is that the current rules are defined to ensure readability and maintainability of the Gherkin files (also by non-technical people). It has also to be considered that the scenarios are intended to be declarative, not imperative with all details.

In most API repositories it was possible to solve the issues with reasonable effort (see status of the status page for roll-out of centralized linting in wiki), so there is no urgent need for changes. But we need guidance in Release Management for the release reviews of Fall25 if the current rules should be enforced or exceptions are possible.

[rartych]

The currently used gherkin-lint ruleset is based on default ruleset of the tool:
https://github.com/gherkin-lint/gherkin-lint?tab=readme-ov-file#available-rules

Some rules have been already modified, but further changes are possible: we should balance readability and maintainability with the applicability to CAMARA APIs test defintions.

I propose to use this issue, to gather other possible changes for gherrkin-lint rules.

[FabrizioMoggio]

So let me also add this (from #519):

"Number of scenarios exceeds maximum", as you can see in #519 we get that error even if the number of scenarios are just 17. I think there is an error on how this value is calculated, see: camaraproject/KnowYourCustomerMatch#28 (comment). In my understanding the example lines are counted as Scenarios.

[rartych]

For easy review here is the content of .gherkin-lintrc:

{
  "no-files-without-scenarios" : "on",
  "no-unnamed-features": "on",
  "no-unnamed-scenarios": "on",
  "no-dupe-scenario-names": ["on", "in-feature"],
  "no-dupe-feature-names": "on",
  "no-partially-commented-tag-lines": "on",
  "indentation" : [
    "on", {
      "Feature": 0,
      "Background": 2,
      "Scenario": 2,
      "Step": 2,
      "Examples": 4,
      "example": 6,
      "given": 4,
      "when": 4,
      "then": 4,
      "and": 4,
      "but": 4,
      "feature tag": 2,
      "scenario tag": 2
    }
  ],
  "no-trailing-spaces": "on",
  "new-line-at-eof": ["off", "yes"],
  "no-multiple-empty-lines": "on",
  "no-empty-file": "on",
  "no-scenario-outlines-without-examples": "on",
  "name-length": ["on", {"Feature": 190, "Step": 190, "Scenario": 190}],
  "no-restricted-tags": ["on", {"tags": ["@watch", "@wip"]}],
  "use-and": "on",
  "keywords-in-logical-order": "on",
  "no-duplicate-tags": "on",
  "no-superfluous-tags": "on",
  "no-homogenous-tags": "on",
  "one-space-between-tags": "on",
  "no-unused-variables": "on",
  "no-background-only-scenario": "on",
  "no-empty-background": "on",
  "scenario-size": ["on", { "steps-length": {"Background": 15, "Scenario": 15}}],
  "only-one-when": "off",
  "allowed-tags": ["on", {
  "patterns": [
    "^@watch$",                        
    "^@wip$",                                            
    "^@.*$"                                   
  ]
 }],
  "file-name": ["off", {"style": "kebab-case"}],
  "max-scenarios-per-file": ["on", {"maxScenarios": 50, "countOutlineExamples": true}],
  "no-restricted-patterns": ["off", {
    "Global": [
      "^globally restricted pattern"
    ],
    "Feature": [
      "poor description",
      "validate",
      "verify"
    ],
    "Background": [
      "show last response",
      "a debugging step"
    ],
    "Scenario": [
      "show last response",
      "a debugging step"
    ]
  }],
  "required-tags": ["on", {
  "tags": ["^@.*$"], // Allow any tag starting with '@'
  "ignoreUntagged": false // Enforce tagging
}]
}

It is proposed to change:

• "max-scenarios-per-file": ["on", {"maxScenarios": 50, "countOutlineExamples": true}], -->
  "max-scenarios-per-file": ["on", {"maxScenarios": 50, "countOutlineExamples": false}], examples won't be counted as separate scenarios

• "scenario-size": ["on", { "steps-length": {"Background": 15, "Scenario": 15}}], - scenario-size lets you specify a maximum step length for scenarios and backgrounds. The Scenario configuration applies to both scenarios and scenario outlines. What is the reasonable size of scenario in number of lines

• "name-length": ["on", {"Feature": 190, "Step": 190, "Scenario": 190}], - the template for scenario idetifier is: @<(mandatory)feature_identifier>_<(mandatory)number>_<(optional)short detail in lower case and using underscore “_” as the separator>