facebook
Improve help/usage (`-h`, `-H`) formatting
Per our brief discussion in #3383, I've gone ahead and re-formatted the CLI help output. For convenience, I've attached text files containing the before/after of the help output.
Some main points with respect to the help formatting are:
- Flag/option descriptions now use proper capitalization and punctuation.
- Flag/options descriptions are now consistently aligned and formatted.
- Some non-technical references to 'zstd' have be rewritten to 'Zstandard'; the rationale here is that this output is for humans, and in instances where the compression algorithm rather than the CLI tool itself is being referred to, I think this makes sense.
- Some flag/option descriptions have been rephrased slightly (or significantly) to what I think is better phrasing. Once again, this is opinionated and I'm happy to discuss changes.
- Probably some more things I'm forgetting.
I've also cleaned up the "welcome message" a bit in a separate commit; I expect this is an opinionated change and I did it in a separate commit so it can be easily reverted.
Please let me know your thoughts.
Hi @jonpalmisc!
Thank you for your pull request and welcome to our community.
Action Required
In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.
Process
In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.
Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.
If you have received this in error or have any questions, please contact us at [email protected]. Thanks!
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!
Hi @jonpalmisc,
I've only given it a brief look but it looks great from what I've seen.
Please note that there's a test that checks the help message and it's failing, so this PR will need to make the same changes to the expected help message in the tests, please see basic/help.sh* files for the test's details.
I agree, this is a good update.
@jonpalmisc , if you have issues with the testing logic (which must be fixed before merge), I could also take over from here and modify the tests so they correspond to the new output format.
Hey guys, thanks for the feedback; glad to hear these changes are a step in the right direction. I'll take a look at fixing that test.
Looks to me like those two tests that were failing before pass now. Please let me know if you spot any other issues.
I see the 'versions-compatibility' test is still failing but it seems like that is failing on most recent PRs; given that wasn't mentioned earlier, I assume that's a known/irrelevant issue?