README scaffolding runs against installed instead of current version
schlessera opened this issue · comments
The wp scaffold package-readme for a given command runs against the files in the current working directory, but uses the command dump from the version of the command that is currently installed through the package manager for parsing the docblocks. This causes the docblocks to not reflect the current state of the files.
Two specific issues that arise from this:
- A change to the content of a docblock is only reflected by the scaffolding command if that change is pushed and installed to the package manager version.
- If a command implementation is added at the same time as it is referenced in the
composer.json->extra->commandssection, this will cause a runtime error, as thecomposer.json->extra->commandsis "live" while the docblocks reflect the codebase without that added command.
The expected behaviour should be that the command docblocks are parsed from the current set of files in the working directory, not from within the version installed through the package manager.
The problem seems to be the wp cli cmd-dump here: https://github.com/wp-cli/scaffold-package-command/blob/master/src/ScaffoldPackageCommand.php#L244
That produces the docblock output for the installed commands, not for the command that is currently being worked on.
The expected behaviour should be that the command docblocks are parsed from the current set of files in the working directory, not from within the version installed through the package manager.
I think this is due to the nature of the autoloader, not specific to wp scaffold package-readme, no?
One workaround is to wp package install <git-url>, and then work from that installed version (which is what I do).
I think this is due to the nature of the autoloader, not specific to wp scaffold package-readme, no?
No, I think that parsing the current code should not have anything to do with the autoloader or the installed commands. Right now, for parsing the docblocks, the actual files to parse are never even touched. Some completely different folder is being parsed instead.
Right now, it is really: "make change in folder A" -> "scaffold looks for change in folder B". In some scenarios, A & B happen to be either similar enough to work, or be symlinks from one to the other. Then everything works fine. But if you're just working in a separate clone of the codebase somewhere, it will never work correctly.
No, I think that parsing the current code should not have anything to do with the autoloader or the installed commands.
But it does.
Right now, for parsing the docblocks, the actual files to parse are never even touched. Some completely different folder is being parsed instead.
This is based on the loaded classes, not a static reading of the PHPdoc: https://github.com/wp-cli/wp-cli/blob/master/php/commands/src/CLI_Command.php#L494
I'd suggest taking a step back to understand the implementation, which is different than what you're describing right now. Of course, we can change the implementation, but the existing implementation is different than your understanding of it.
Yes, I'm aware this is different. But I'd argue that the scaffolding tools should work on the files you point them to, not something unrelated that is installed somewhere else.
It sure is easier to just dump loaded commands, but I think that is just the wrong approach, as it creates unexpected results.
But I'd argue that the scaffolding tools should work on the files you point them to, not something unrelated that is installed somewhere else.
Can you suggest how this would work, in practicality? And, if it's a substantial degree of effort, might it be easier to address this issue with documentation?
I think it should work by making the code that parses the docblocks more modular, so that you can choose where to point it to. I already had a quick look into the code, and it is spread across multiple functions and levels of the code, so probably not an easy fix.
It is not easy to solve as documentation either, though. The documentation then needs to document how you go about tricking Composer into working on the same package that you already have installed through the WP-CLI package manager. In every other scenario, the end result is basically: work on A, generate docs from B.
The documentation then needs to document how you go about tricking Composer into working on the same package that you already have installed through the WP-CLI package manager.
Isn't this wp package install <dir> ?
In every other scenario, the end result is basically: work on A, generate docs from B.
I'm confused as to why you need to have two separate copies of the codebase. You should only have one.
Isn't this wp package install
?
Does that pull in the <dir> as a new "path" repository, or does it copy the <dir> into the package folder?
I'm confused as to why you need to have two separate copies of the codebase. You should only have one.
It's not so much the need for this, rather than what my workflow happened to be when my expectations didn't match what the scaffolding tool was doing.
Yes, you can tell people to only ever work on installed packages when using the scaffolding. But that doesn't make the bug go away. The scaffolding tool will effectively use a combination of the installed and the current command to do its work, resulting in wrong documentation and runtime errors. So, at the very least, it should be consistent and look into the installed command only, instead of using both.
Again, to summarize:
It reads the list of commands, the documentation sections as well as the custom documentation text from the composer.json file in the current working directory BUT reads the docblocks from the commands in the directory of the installed command of the same name, which could potentially be something completely different. If you have a v1 of a command installed and are working in a separate folder on a rewrite of that command for v2, the README scaffolding will produce random garbage.
Does that pull in the
<dir>as a new "path" repository, or does it copy the<dir>into the package folder?
The former.
It reads the list of commands, the documentation sections as well as the custom documentation text from the composer.json file in the current working directory BUT reads the docblocks from the commands in the directory of the installed command of the same name, which could potentially be something completely different.
Oh, I see. Could we detect this scenario and warn if it happens?
@schlessera ^ I'm still not clear what's actionable out of this issue.
The most obvious action would be to rewrite the parsing of the docblocks to actually go over the files in the folder you're working in. Right now, it uses the wp cli cmd-dump output, which means it works off of an installed and active command instead.
However, this is potentially a lot of work, as the docblock parsing code probably needs a major refactor first before it can be easily used within two totally different contexts.
However, this is potentially a lot of work, as the docblock parsing code probably needs a major refactor first before it can be easily used within two totally different contexts.
This is a pretty extreme solution (refactoring docblock parsing code which somehow magically determines which docblock you want to be parsed) to a relatively obscure edge case (generating a package README where you accidentally have the package installed twice on the system).
We can tackle this later if it proves to be a common problem.