mirrors/git-annex
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions

Merge branch 'master' of ssh://git-annex.branchable.com

Browse source
This commit is contained in:
Joey Hess 2024-02-07 16:21:31 -04:00
commit 644317e86f
No known key found for this signature in database
GPG key ID: DB12DB0FF05F8F38
5 changed files with 199 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

22
doc/todo/add_--json-progress_support_in_push_and_pull/comment_2_ff0b1ca16b03d2e6c8331645adad84a6._comment Normal file
View file

@ -0,0 +1,22 @@
[[!comment format=mdwn
username="jstritch"
avatar="http://cdn.libravatar.org/avatar/56756b34ff409071074762951d270002"
subject="comment 2"
date="2024-02-06T16:10:56Z"
content="""
To me, the purpose of any progress message is twofold: 1) let the user know the program is not stuck and 2) provide information about what was happening if it does get stuck. Push and pull do this now without JSON.
I agree the same JSON progress object format should be used for all commands. Currently the action progress information includes: command, file, input, byte-progress, total-size, and percent-progress.
The calling application is able to \"know\" which command it issued to cause the progress reports.
A separate, optional field could be added for the particular remote involved. For example, messages like \"Copy file A to remote-one X% complete\" and \"Export file B to remote-two X% complete\" should be possible.
I'm in favor of documenting data structures. Forcing developers to reverse-engineer the structure is inefficient at best. While the principle that all git-annex json output should be discoverable by simply running the command sounds good, I find it leaves much to be desired. Just to find out what's available, someone must setup and run the command. I suggest updating the requirement to \"All git-annex JSON output objects are documented.\"
Users will get impatient and grow frustrated without some type of indication work is in progress.
I'm OK with leaving Git operations silent for now.
Please improve the end-user experience by devising a way to inform the user git-annex is making progress with JSON.
"""]]

24
doc/todo/add_--json-progress_support_in_push_and_pull/comment_3_a11ee71f4ee907b011aebcfe270b7ee3._comment Normal file
View file

@ -0,0 +1,24 @@
[[!comment format=mdwn
username="jstritch"
avatar="http://cdn.libravatar.org/avatar/56756b34ff409071074762951d270002"
subject="comment 3"
date="2024-02-07T15:52:18Z"
content="""
Additional clarification of my posts above:
1) JSON allows optional fields. That is, fields which are only present when needed. I am specifically saying not to include all fields every time with `null` values as needed.
2) Occasionally tacking the remote name onto the end of a string named `command` is not discoverable. The `command` key would have to be renamed to something like `commandAndSometimesRemote` to be discoverable. jstritch's naming rule #5: If a name needs a conjunction to accurately describe it, the design can be improved.
3) The optional field name is more easily observed than the optional string content.
4) Consider the application code consuming the JSON. A test for the presence of the remote name is required either way. Do you want those applications writing the test \"if the command value contains one space\" or \"if the remote key is present\"? Code is written once and read hundreds of times. The second test conveys the intent, reducing maintenance cost.
5) The application code to deal with splitting the string and handling each part becomes unnecessary with the optional field.
6) The documentation of the JSON could include a matrix showing the key name and its data type versus the commands, similar to a feature comparison table.
7) Documenting the JSON does not make it less discoverable.
I hope you find this information helpful to improve the end-user experience. Let me know if you have any questions.
"""]]