Skip to content

Make description of _GROUP_ID more obvious #6683

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+3 −3
Open

Make description of _GROUP_ID more obvious #6683

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions docs/UsersGuide.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1136,10 +1136,10 @@ _SKIP_CHAINED_DEPS:: Do not schedule parent test suites which are specified in `
_INCLUDE_CHILDREN:: Include children that would otherwise not be considered when
filtering test suites via the `TEST` parameter.

_GROUP:: Job templates *not* matching the given group name are ignored. Does *not*
affect obsoletion behavior.
_GROUP:: Limiting lookup for job templates only to group with matching name.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now not a full sentence anymore.

Suggested change
_GROUP:: Limiting lookup for job templates only to group with matching name.
_GROUP:: Limits the lookup for job templates to only the group with matching name.

I must say that I still find the previous/current description the best.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

Both sentences are grammatically correct, but they have slightly different meanings and common usage.

When you say:

"Limit the lookup for job templates to groups with a matching name."

The word "groups" is being used in a general sense. You're talking about the class of all groups that have this characteristic (a matching name). This is the more common and natural way to phrase a general rule or instruction.

When you add "the":

"Limit the lookup for job templates to the groups with a matching name."

You are referring to a specific, previously-mentioned, or well-understood set of groups. It implies that there is a particular collection of groups you are already talking about.

In this context, since the sentence is likely a general statement of a rule or a system's behavior, omitting "the" is more appropriate. It makes the sentence a clear, concise, and universal instruction, not one that depends on a specific, already-identified set of groups.

I would say we should not use "the" in that case so if it is ok for you I will change that to Limits the lookup for job templates to only group with matching name. basically your version but w/o "the" before groups

Copy link
Contributor

@Martchus Martchus Sep 2, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The sentence "Limits the lookup for job templates to only group with matching name." is not identical to the sentence "Limit the lookup for job templates to groups with a matching name.". Only the latter is grammatically correct (according to the AI response which is also in-line with my understanding). The latter uses "groups" (plural) instead of "group" singular.
(EDIT: Technically the first sentence is also correct if you think of "group" as a verb. However, then the sentence is not conveying the meaning it is supposed to convey. Because of this ambiguity I suggested the change in the first place. And I still find the version before this change the easiest to make sense of.)

So you may change it to "Limit the lookup for job templates to groups with a matching name.". However, I chose "the group" (article and singular) in my suggestion because there will only be one group with a matching name and we specify this name here. So the setting refers to a specific group. The AI also says that one should use "the" when referring to a specific group. (The AI thinks in terms of multiple groups here but it cannot know that we only specify and refer to a single group here.) So I still think my initial suggestion is best.

Does *not* affect obsoletion behavior.

_GROUP_ID:: Same as `_GROUP` but allows to specify the group directly by ID.
_GROUP_ID:: Limiting lookup for job templates only to group with matching ID.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again, not a full sentence. And isn't it good to refer to _GROUP as the current description does? This makes it immediately clear that both parameters do the same thing - the group is just specified in a different way.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

well it is hard to argue because it is personal thing but for me it was not clear what exactly is "the same"

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, but I'm not sure how that cannot be clear :-)

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Same as _GROUP" means "Behaves the same as _GROUP"... maybe "Limit the lookup by group ID, as an alternative to using _GROUP" would be more explicit?

_PRIORITY:: Sets the priority value for the new jobs (which otherwise defaults
to the priority of the job template)

Expand Down