[Bug Report] 1P Developer Docs: Z Shell interactions
Salutations to my fellow 1P nerds!
I just spotted something of an oversimplification (not exactly wrong, but not precisely correct, either) in the 1P Dev Docs regarding integrating the shell plugins with Z Shell, and since I couldn't find any mention of a pipeline for PR-style contributions to the docs themselves, I thought I'd raise it here.
Bug Description
This is in reference to the Circle CI Shell Plugin documentation, specifically Step 2, "Source the plugins.sh file" where there's a tab for Zsh. There it directs the reader to use this shell invocation (echo "source ~/.op/plugins.sh" >> ~/.zshrc && source ~/.zshrc) to integrate the 1P CLI with their shell's init process. The issue I see is in the use of the shorthand ~ for the user's home directory as the canonical location for those shell init files. In fact, as can be read in the Z Shell official documentation, Z Shell permits the user to place those files at any readable file path of their choosing by setting the $ZDOTDIR environment variable, which for compatibility's sake defaults to $HOME when not explicitly set.
The real world usage of this feature would seem to be on the rise, growing in concert with Freedesktop.org's Cross Desktop Group (XDG, formerly the "X Desktop Group") and their efforts to tidy up user home directories of configuration files by relocating them to the various $XDG_*******_HOME-defined paths we know and love.
Proposed Remeditation
I propose that the documentation in question display the following shell incantation in place of the one it currently has:
echo "source ${HOME}/.op/plugins.sh" >>"${ZDOTDIR:-${HOME}}/.zshrc" && source "${ZDOTDIR:-${HOME}/.zshrc"
Rationale
Now I've no doubt got at least a few people grumbling here over what would appear prima facie to be the techie equivalent of a pleonasm in using the shell syntax for defining the $ZDOTDIR variable to the value for $HOME if it is unset (:-), but I don't believe it to be one. Practically speaking, there is no implicit requirement that a user perform this invocation in the shell being modified. Let's take the example of a user who uses Bash 80% of the time, but who also uses Z Shell often enough that when they decide to begin making use of the 1P CLI and are performing these actions described in the docs, they are going to issue the commands for both Bash and Z Shell all at the same time. It is reasonable to assume that they'll be doing so from Bash, since they use it more frequently and perceive no impediment to that approach, saving them the need to open another tab in their terminal for zsh or to call it from within Bash. This is where the need to define a fallback value for $ZDOTDIR arises, because in Bash (and every other shell that's not Z Shell) that variable holds no special charism, and the commands shown would evaluate an unset $ZDOTDIR to an empty string and thus end up targeting files on the filesystem root instead.
Conclusion
Thanks for reading my proposal and I hope that even if it isn't implemented in the docs, that it may perhaps inform some of the development decisions made regarding the CLI going forward. As one personal adherent to the movement to relocate various and sundry config files from the $HOME/%USERPROFILE% directories into less well-trodden places, I'd very much like to see the 1P CLI begin to use the $XDG_CONFIG_HOME/%LOCALAPPDATA% directories on Linux/Mac and Windows, respectively, for its config and state files at some point. I know some efforts to move in that direction regarding the desktop apps have already taken place and I'm appreciative, yet nevertheless I still have a .op directory in my home directory on both Windows and Linux that if I had my druthers would live deeper in the filesystem. ;)
Once again, thank you for making such a valuable and ever-evolving product, and for being the kind of organization that responds so well to user feedback that nerds like me can feel that writing a post like this is time well-spent. Happy holidays and blessings unforeseen to you and yours as another calendar year comes to a close.
1Password Version: 8.9.11
Extension Version: 2.6.1
OS Version: Windows 11 Professional/Kubuntu 22.10 (5.19.0-27)
Browser:_ Vivaldi Snapshot 5.7.2881.6