feat: add check-update subcommand

[natescherer]

Hello! This is my attempt to complete the work that was done in #1031. (Should close #1020, as well.)

What's Changed

Here's what I've changed versus the previous PR, by type:

Outstanding changes requested in discussions on old PR

• Subcommand updated to check-update
• Hard-coded exit code when an update is detected to 5
  • 2 was discussed in the previous PR but I changed it based on Ambiguous exit code 2 #1328
• Tests added

Necessary Updates

• Restructured to match updates made to project in the intervening years

Other Changes

• Minor rewording
• Added --check-update-output-as-json flag for integrating with CI/scripts/etc
  • I'm not in love with this name but seeing as how I had to add it at the Worker level I figured I should make it pretty specific

Questions/To-Do

I have a few questions for the maintainers:

• Are we sure that having the app exit with an error when there is an update is the right pattern?
  • I preserved it based on the work previously done, but if I was designing this from scratch, I wouldn't consider an update being available an error in the classic sense
  • My addition of --check-update-output-as-json provides a hook for scripts to detect if there is an update, from the discussions I saw before that seemed to be the overall intention of the exit code
• What level of documentation would you like for this subcommand?
  • Maybe a docs/checking_for_updates.md?

Thanks for making such an awesome tool! Please let me know if there are changes you'd like me to make.

[sisp]

Thanks for contributing this feature to Copier, @natescherer! 🙇

I've left a couple of inline comments.

[natescherer]

@sisp While I'm working on those changes, would appreciate your thoughts on the two questions I raised at the bottom of the PR, thanks. 🙏

[sisp]

Regarding the exit code: I think exiting with 0 when there's no update (i.e., the project is up-to-date) and with non-zero otherwise seems reasonable. At least Cruft follows a similar approach. The specific non-zero exit code is another question. Cruft exits with 1 when there is an update, but 1 is already used for, e.g., precondition errors like a missing old template reference. Exit code 2 is used for indicating unsafe templates without explicit user trust, but this error can only occur for copy and update operations but never when checking for an update. I think it's fine to use the same exit code for different errors by different subcommands.

[...] but if I was designing this from scratch, I wouldn't consider an update being available an error in the classic sense

What exactly do you mean by "in the classic sense"?

---

Regarding documentation: How about adding a section on our "Updating a project" page, similar to Cruft's corresponding section?

[natescherer]

Sounds good re: the documentation.

As far as what I mean by "in the classic sense" this is probably my SRE brain talking, but I tend to see any application ending with a non-zero status code as indicating that there is some failure in execution, but there's no failure/error/issue when the sub command checks and sees there is an update; the update checking process worked just fine. Hopefully that makes sense?

[natescherer]

Hi @sisp, I've completed updating the following:

• Your suggested changes
• Adding doc to Updating a Project
• Changing status code when an update is detected from 5 to 1

Let me know if there's anything else you'd like me to change!

[natescherer]

Okay, should now be up-to-date with the latest round of revisions. I've also resolved the conflict with master.

• Doc update
• Test restructured
• Using explicit params
• Update checking function moved out of worker and into _main.py function get_update_data
• CLI output logic moved from _main.py into _cli.py

Let me know if anything else needs changed!

[natescherer]

Fixed a couple other issues I noticed after syncing with master. Should actually be ready for your review again now.

[sisp]

Looks pretty good already, I've left a few more comments. 🫣

[natescherer]

Latest round of changes completed.

Let me know if there's anything else you'd like me to change!

[sisp]

Nice! 🤩 Just some minor polishing, then we should be good to go. 🚀

[natescherer]

Ready for your review again!