Comments (7)
Is there strong consensus on -v
being used as an alias for --version
? Many GNU and other "long-lived" CLIs use the short-v as a flag for verbose
. Indeed, some tooling even increases the verbosity level based on the number of Vs.
-v
: "debug"
-vv
: "trace"
-vvv
: "silly"
--version
: version info
from nodejs-cli-apps-best-practices.
I did some research on version flags for Commander: tj/commander.js#1621 (comment)
The long flag --version
is very common, the short flag varies. The references I found cover the full spread, one -v
, one -V
, and one mentioned both verbose and version for -v
!
- https://tldp.org/LDP/abs/html/standard-options.html
- https://unix.stackexchange.com/a/108141
- http://www.catb.org/~esr/writings/taoup/html/ch10s05.html
from nodejs-cli-apps-best-practices.
(I won't volunteer to take it up thanks, busy elsewhere. But I might get to it some quiet day when I am looking for something to contribute to!)
from nodejs-cli-apps-best-practices.
I like that @ShamimShahraeini. Want to send a PR to update the main README file and I'll merge?
yes sure
from nodejs-cli-apps-best-practices.
@jasonkarns good point indeed. I don't have a strong opinion on forcing that, but rather to have some good research on conventions, hopefully, those that also apply and have been employed in POSIX compliant tooling so this would indeed not confuse users.
@shadowspawn thank you for chiming in (π). How about we kick this off with a PR for updating this information as part of the best practices section and go with --version
as the recommended one. In the details part, we can share the pitfalls as to why it might not be a good idea to add -v
as a short flag. @shadowspawn would you like to take it up to push a PR?
from nodejs-cli-apps-best-practices.
@lirantal What about having a new section called Versioning, including some content like the ones below?
1. Include a --version
Flag
β
Do: A program may choose to show its version when being run in order to easily surface the version to users and allow users to check the application's version easily.
β Otherwise: Users won't know which version they are using, making it challenging to track updates or report issues accurately.
π¦ Recommended packages
Tools like npm
or yarn
offer version management features that simplify handling dependencies and versioning.
> π Tip
>
> Use the option of automating version increments that these tools bring, (e.g., npm version
) to reduce the risk of human error and streamline the release process.
2. Use Semantic Versioning
β
Do: It provides a clear, standardized way to convey version information, making it easier for users to understand the significance of updates.
β Otherwise: Users might not understand the impact of updates, leading to confusion or unexpected behavior.
3. Provide Version Information in a 'package.json' file
β
Do: This ensures consistency across your project and makes it easy to automate version updates.
β Otherwise: Difficulty in tracking dependencies and managing your project's version.
4. Display Version in Error Messages and Help Text
β
Do: Users can include version information when reporting issues, aiding debugging and support.
β Otherwise: Debugging becomes more challenging, and users might not know which version to reference when seeking help.
5. Backward Compatibility
β
Do: Ensuring backward compatibility with older versions of your app allows users to upgrade without breaking their workflows.
β Otherwise: Frequent updates that break compatibility can frustrate users and hinder adoption.
6. Publish Versioned Releases on npm
β
Do: Publishing your app on npm with version tags enables users to easily install specific versions.
β Otherwise: Users can't access previous versions, which might be necessary for compatibility or troubleshooting.
7. Update Your App's Version Documents
β
Do: Clear release notes inform users about changes, enhancements, and bug fixes in each version; A changelog helps users understand what has changed between versions and whether it affects their use case.
β Otherwise: Users won't know what to expect in new versions, which can lead to frustration or confusion. They also may struggle to assess whether they should upgrade or not.
from nodejs-cli-apps-best-practices.
I like that @ShamimShahraeini. Want to send a PR to update the main README file and I'll merge?
from nodejs-cli-apps-best-practices.
Related Issues (20)
- How to perform user authentication in CLI? HOT 6
- Idea: add a section for CLI tools
- Updates needed for up to date Node.js runtime features
- Do you have plans to translate it into other languages? HOT 1
- New Practice: Distinguish STDOUT from STDERR
- Caveat: Accept STDIN somewhat counter to Empathetic CLI HOT 1
- [author required] New Practice: Support shell completion HOT 7
- Updating layout suggestions HOT 26
- Request: New experience best practice request: i18n HOT 2
- New Distribution Practice: Exclude unnesessary files from npm publish HOT 5
- GitLocalize: Problems with the structure of the .md file HOT 5
- Upgrade severals examples from require to import. HOT 1
- New feature: document other CLI related resources HOT 5
- New feature: document a new section for popular command line frameworks HOT 7
- Cleanup configuration files (if any) when uninstalling the package HOT 5
- Add the Crowdin internationalization integration tool to the project HOT 15
- remove 2.3 Cleanup configuration files chapter as it does not work since npm v7 HOT 2
- Can I use GitLocalize to translate documentsοΌ HOT 9
- Good first issue: add Crowdin badge to the repository
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from nodejs-cli-apps-best-practices.