New Experience best practice request: version information
lirantal opened this issue · 7 comments
Looking for someone who would be interesting to contribute a new item on proper version usage.
My take on it would be around:
- A program should support --version and -v to inspect the installed version
Further info that can be elaborated in details: A program may choose to show its version when being run in order to easily surface the version to users. Example of this is Yarn.
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
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!
@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?
(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!)
@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.
I like that @ShamimShahraeini. Want to send a PR to update the main README file and I'll merge?
I like that @ShamimShahraeini. Want to send a PR to update the main README file and I'll merge?
yes sure