8000 Inconsistent verb mood in command options and descriptions · Issue #36973 · symfony/symfony · GitHub
[go: up one dir, main page]
Skip to content

Inconsistent verb mood in command options and descriptions #36973

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

Jump to bottom
Closed
danepowell opened this issue May 26, 2020 · 7 comments
Closed

Inconsistent verb mood in command options and descriptions #36973

danepowell opened this issue May 26, 2020 · 7 comments
Labels
Bug Console Status: Needs Review

Comments

@danepowell
Copy link
Contributor
danepowell commented May 26, 2020 •
edited
Loading

Symfony version(s) affected: dev-master

Description
Built-in Symfony options and commands, such as in the Console and Framework Bundle, use inconsistent mood in option and command descriptions.

How to reproduce
Look at the option and command descriptions in AssetsInstallCommand.php and HelpCommand.php, just for example.

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
...
  --symlink             Symlinks the assets instead of copying it
...
Available commands:
  help                  Displays help for a command
...
  assets:install        Installs bundles web assets under a public directory

Note that some verbs are in the indicative mood ("Symlinks") and some are imperative ("Display").

This is not only grammatically inconsistent, but the inconsistency makes it difficult for downstream projects to choose a consistent standard when implementing commands.

Possible Solution
Reword all command options and descriptions to use a consistent mood, ideally the imperative mood (no trailing "s") since that's more concise, matches the commands themselves, and is in line with what I tend to see for other more traditional frameworks and commands (such as Unix man pages), and random internet people seem to prefer it. But I don't really care as long as it's consistent.

Bonus points for declaring this along with rationale in a Symfony style guide or documentation.
@danepowell danepowell added the Bug label May 26, 2020
@danepowell danepowell changed the title Inconsistent verb mood Inconsistent verb mood in command options and descriptions May 26, 2020
@stof
Copy link
Member
stof commented May 26, 2020

and random internet people seem to prefer it.

This link is not about command help, but about commit messages. And here, the main argument is consistency with git-generated messages, not personal preference.

@danepowell
Copy link
Contributor Author

Fair enough, there's just not a lot of explicit guidance on this so you have a stretch a bit to find it 😄 Like I said, I don't really care as long as it's consistent and mindfully chosen.

@xabbuh xabbuh added the Console label May 26, 2020
@carsonbot
Copy link

Hey, thanks for your report!
There has not been a lot of activity here for a while. Is this bug still relevant? Have you managed to find a workaround?

@carsonbot
Copy link

Hello? This issue is about to be closed if nobody replies.

@danepowell
Copy link
Contributor Author

I think this is still valid, but I don't know how to move it forward. I'm happy to provide a PR but a maintainer needs to choose the approach.

@carsonbot carsonbot removed the Stalled label Mar 4, 2021
@fabpot
Copy link
Member
fabpot commented Mar 4, 2021

I think using imperative everywhere is the way to go. Up for a PR? I would say on 4.4.

@danepowell danepowell mentioned this issue Mar 5, 2021
Merged
danepowell added a commit to danepowell/symfony that referenced this issue Mar 5, 2021
@danepowell
Fix symfony#36973: Command description consistency
01e18b0
@danepowell danepowell mentioned this issue Mar 5, 2021
Merged
@danepowell
Copy link
Contributor Author

Thanks, I agree! Here are the corresponding PRs:

@fabpot fabpot closed this as completed Mar 6, 2021
fabpot added a commit that referenced this issue Mar 6, 2021
@fabpot
minor #40387 Fix #36973: Command description consistency (danepowell)
57fb475 
This PR was merged into the 4.4 branch.

Discussion
----------

Fix #36973: Command description consistency

| Q             | A
| ------------- | ---
| Branch?       | 4.4
| Bug fix?      | yes
| New feature?  | no
| Deprecations? | no
| Tickets       | Fix #36973
| License       | MIT
| Doc PR        | symfony/symfony-docs#15062

This rewords command descriptions and options to use consistent verb mood.

Commits
-------

01e18b0 Fix #36973: Command description consistency
fabpot added a commit that referenced this issue Mar 6, 2021
@fabpot
Merge branch '4.4' into 5.2
7ed3d36 
* 4.4:
  Fix #36973: Command description consistency
  Render email once
fabpot added a commit that referenced this issue Mar 6, 2021
@fabpot
Merge branch '5.2' into 5.x
e53bb8b 
* 5.2:
  Fix #36973: Command description consistency
  Render email once
javiereguiluz added a commit to symfony/symfony-docs that referenced this issue Apr 16, 2021
@javiereguiluz
minor #15062 Command naming conventions (danepowell)
ce5f517 
This PR was squashed before being merged into the 4.4 branch.

Discussion
----------

Command naming conventions

This is a partial fix for symfony/symfony#36973, to be reviewed along with symfony/symfony#40387

Commits
-------

60f8569 Command naming conventions
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Bug Console Status: Needs Review
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
5 participants
@fabpot @stof @xabbuh @danepowell @carsonbot
0