jetpack/install : Print instructions how to resolve composer errors

[artpi]

When you run pnpm jetpack/install, it sometimes fails with a cryptic error.
The solution is to run the composer update in the appropriate directory, but if you are a newbie in Jetpack, it cant take you days.

This simple change is just injecting a suggestion on how to resolve that when that is needed:

jetpack 😃 🚀 pnpm jetpack install                                                          (trunk)jetpack
? What type of project are you working on today? plugins
? Please choose which project jetpack
  ⠹ Installing pnpm dependencies
  ✖ Installing composer dependencies for plugins/jetpack
    → Command failed with exit code 2: composer install
Error: Command failed with exit code 2: composer install
    at makeError (/Users/artpi/GIT/jetpack/node_modules/.pnpm/[email protected]/node_modules/execa/lib/error.js:59:11)
    at handlePromise (/Users/artpi/GIT/jetpack/node_modules/.pnpm/[email protected]/node_modules/execa/index.js:114:26)
    at processTicksAndRejections (node:internal/process/task_queues:96:5) {
  shortMessage: 'Command failed with exit code 2: composer install',
  command: 'composer install',
  exitCode: 2,
  signal: undefined,
  signalDescription: undefined,
  stdout: undefined,
  stderr: undefined,
  failed: true,
  timedOut: false,
  isCanceled: false,
  killed: false,
  fix: 'To resolve issues, try running the command: `cd projects/plugins/jetpack && composer install`',
  context: [Object: null prototype] {}
}

Does this pull request change what data or activity we track or use?

No

Testing instructions

• Find a branch that triggers "run jetpack install" message
• Run pnpm composer install
• See the error (i don't know how to trigger that)
• Run the suggested command

[github-actions]

Thank you for your PR!

When contributing to Jetpack, we have a few suggestions that can help us test and review your patch:

• ✅ Include a description of your PR changes.
  
• ✅ All commits were linted before commit.
  
• 🔴 Add a "[Status]" label (In Progress, Needs Team Review, ...).
  
• ✅ Add testing instructions.
  
• ✅ Specify whether this PR includes any changes to data or privacy.
  
• ✅ Add changelog entries to affected projects
  

This comment will be updated as you work on your PR and make changes. If you think that some of those checks are not needed for your PR, please explain why you think so. Thanks for cooperation 🤖

---

The e2e test report can be found here. Please note that it can take a few minutes after the e2e tests checks are complete for the report to be available.

---

Once your PR is ready for review, check one last time that all required checks (other than "Required review") appearing at the bottom of this PR are passing or skipped.
Then, add the "[Status] Needs Team review" label and ask someone from your team review the code.
Once you’ve done so, switch to the "[Status] Needs Review" label; someone from Jetpack Crew will then review this PR and merge it to be included in the next Jetpack release.

[jeherve]

Instead of running composer install yourself, maybe we should suggest running jetpack install xxx just for the element that's causing issues?

[artpi]

The problem is that there is a variety of solutions and the current script is hiding composer error messages.
There is usually a message to run "composer update", but some of the times it wants to downgrade or be run with --ignore-platform-deps, depending on your local setup.

This is meant to at least point you to a right direction, not solve every conceivable problem.
I think in general these scripts try to do too much and are not humble enough to admit when they can't do things for you

[anomiex]

I like @jeherve's suggestion, although I'd recommend including -v to get the verbose output since, unless it was a transient network error or something, it'll probably fail again.

BTW: Running composer update on a project where composer.lock is checked in could cause you problems when submitting the PR, as it might update indirect deps like changelogger's dep on various Symfony packages. Our tools/composer-update-monorepo.sh script is safer as it avoids updating those. If you need --ignore-platform-deps, that probably means your dev environment is screwed up somehow (e.g. a too-old version of PHP).

[kraftbj]

I'll look at this closer today. I'm fine with the idea of this.

Is plugins/jetpack hardcoded for a particular reason or is that simply the project you've worked on that has been troubling? Or to phrase another way, is there something particular that installing the jetpack plugin resolves issues elsewhere in the monorepo?

Ideally, we'd bubble up the downstream error message. Adding the -v flag would output everything, of course, but if something fails that isn't accounted for in the error handling, we should aim to report it to avoid the frustration that this is in response to.

[anomiex]

Is plugins/jetpack hardcoded for a particular reason or is that simply the project you've worked on that has been troubling? Or to phrase another way, is there something particular that installing the jetpack plugin resolves issues elsewhere in the monorepo?

There shouldn't be for the composer install/upgrade. If we don't make any other changes to the message, I'd recommend interpolating the correct directory corresponding to the failed run instead of hard-coding plugins/jetpack.

Ideally, we'd bubble up the downstream error message.

That might be as simple as changing

jetpack/tools/cli/commands/install.js

Line 75 in e4fc1ba

const stdio = argv.v ? [ 'ignore', 'inherit', 'inherit' ] : [ 'ignore', 'ignore', 'ignore' ];

to have [ 'ignore', 'ignore', undefined ] for the false case. Although that might be too much in some cases, but getting just the error message and not all the other stuff composer prints would be much less straightforward. Overall I think I like the suggestion to just print a message specifying to run it with -v better.

[millerf]

This is the bulk of the message I am receiving:

[plugins/jetpack] Verifying lock file contents can be installed on current platform.
[plugins/jetpack] Your lock file does not contain a compatible set of packages. Please run composer update.
[plugins/jetpack] 
[plugins/jetpack]   Problem 1
[plugins/jetpack]     - symfony/console is locked to version v6.0.17 and an update of this package was not requested.
[plugins/jetpack]     - symfony/console v6.0.17 requires php >=8.0.2 -> your php version (7.4.32) does not satisfy that requirement.
[plugins/jetpack]   Problem 2
[plugins/jetpack]     - symfony/process is locked to version v6.0.11 and an update of this package was not requested.
[plugins/jetpack]     - symfony/process v6.0.11 requires php >=8.0.2 -> your php version (7.4.32) does not satisfy that requirement.
[plugins/jetpack]   Problem 3
[plugins/jetpack]     - symfony/service-contracts is locked to version v3.0.2 and an update of this package was not requested.
[plugins/jetpack]     - symfony/service-contracts v3.0.2 requires php >=8.0.2 -> your php version (7.4.32) does not satisfy that requirement.
[plugins/jetpack]   Problem 4
[plugins/jetpack]     - symfony/string is locked to version v6.0.17 and an update of this package was not requested.
[plugins/jetpack]     - symfony/string v6.0.17 requires php >=8.0.2 -> your php version (7.4.32) does not satisfy that requirement.
[plugins/jetpack]   Problem 5
[plugins/jetpack]     - symfony/console v6.0.17 requires php >=8.0.2 -> your php version (7.4.32) does not satisfy that requirement.
[plugins/jetpack]     - automattic/jetpack-changelogger dev-trunk requires symfony/console ^3.4 || ^5.2 || ^6.0 -> satisfiable by symfony/console[v6.0.17].
[plugins/jetpack]     - automattic/jetpack-changelogger is locked to version dev-trunk and an update of this package was not requested.
[plugins/jetpack] 

Is everyone using PHP > 8.0.2 in the JP crew?

[jeherve]

Is everyone using PHP > 8.0.2 in the JP crew?

Yes. We recommend using PHP 8.0 when working in the monorepo. You should see a recommendation to update if you run tools/check-development-environment.sh locally. Running lower versions such as PHP 7.4 can cause issues when updating lock files, as you're seeing. You can read more about it here: pdWQjU-7Y-p2

If you cannot update, you could try using the tools/composer-update-monorepo.sh script instead of manually running composer. See the discussion here for more info: #28285 (comment)

[millerf]

If you cannot update

I am updating right now. I also found a small tools called sphp that seems handy to switch between PHP versions installed with brew,,...

[artpi]

I have another tool that also uses global PHP version and it requires php7.4. I am really not a fan of global versions TBH.

[artpi]

If you cannot update, you could try using the tools/composer-update-monorepo.sh script instead of manually running composer.

If that is the solution, should jetpack update run that script instead of composer?

[jeherve]

If you cannot update

I am updating right now. I also found a small tools called sphp that seems handy to switch between PHP versions installed with brew,,...

I don't really switch often, but until now I've been happy with multiple versions installed on my machine via brew, and then switching from one to the other with brew link and brew unlink. A little utility to make that easier is nice for those who do both, though!

I am really not a fan of global versions TBH.

Yep, it's not a perfect solution; ideally we could rely on the container for everything. Unfortunately that's not always the best option or possible.

[millerf]

Unfortunately that's not always the best option or possible.

IMO the ONLY downside of docker is that it drains my macbook battery. And being nomad, I care about those things... :)