Skip to content
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.

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

Convert public-function parameter names to singular nouns with plural aliases #523

Open
hmmwhatsthisdo opened this issue Sep 26, 2024 · 0 comments

Comments

@hmmwhatsthisdo
Copy link
Contributor

Context

Jira's API frequently uses plural-form nouns in API response properties (e.g. labels), JQL queries, etc. Some of JiraPS's cmdlet parameters are named in alignment with the corresponding API methods/parameters/etc.

On the other hand, PowerShell's cmdlet development guidelines recommend singular-noun parameter names instead of plural-form.

As a result, JiraPS has a mixture of:

  • Strictly-plural parameter names
  • Strictly-singular parameter names
  • Singular parameter names with plural aliases
  • Plural parameter names with singular aliases

This lack of homogeneity confuses users and impacts discoverability of features. For example, if a user calls New-JiraIssue with the -Labels parameter, but then tries changing New to Set, -Labels is no longer a valid parameter. Users may believe that Set-JiraIssue does not support updating labels, which is not accurate (the parameter name has simply changed to -Label)

Description

To align with PowerShell best practices and support backwards compatibility for users expecting JiraPS to use similar verbiage as the API, we should use singular-form parameter names with plural-form aliases.

Additional Information

#522 solved this for -Label (nee -Labels) in New-JiraIssue and Set-JiraIssue, but other cmdlets likely have similar problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant