[RFC PATCH v1] tools: update-subtree.sh improve user experience

[Quentin Schulz]

Hi E,

On 10/27/25 7:56 AM, E Shattow wrote:
> Hi Quentin, thanks for the review.
> 
> On 10/20/25 09:01, Quentin Schulz wrote:
>> Hi E,
>>
>> On 10/15/25 10:38 AM, E Shattow wrote:
>>> Makeover of the script:
>>> - Usage now explains at each step what is expected from the user.
>>> - Default branch name is no longer hard-coded and is queried when
>>> omitted.
>>> - Additional operations 'update' and 'log' close the logic gap between
>>>     expecting the user to provide a commit id and where from this
>>> commit id
>>>     should be obtained.
>>> - Use 'set -x' context to show git invocation where appropriate
>>> - Sort options for usage output
>>> - 'pick' operation detects merge commit id and displays suggested commits
>>>
>>> Additionally the LwIP remote is now using the Savannah mirror system:
>>>
>>> https://lists.gnu.org/archive/html/savannah-users/2025-05/msg00002.html
>>>
>>
>> Please try to split changes into multiple commits. There's a lot of
>> unnecessary noise and it makes difficult to review your patch otherwise.
> 
> Yes this is incomprehensible as a diff. It should be reviewed as a
> replacement for the existing script (I do not know if that is possible
> with git format-patch, ?) I'll try to spoon feed it in a series of more
> easily reviewable patches to get where I want to.
> 

Create two patches, one which deletes the current file and the second 
which adds your new changes. Then in the cover letter say that they 
should be squashed before being applied.

Note that this is very unusual, I believe projects typically would 
rather see small incremental changes than starting from scratch.

>>
>> Here I can identify:
>>
>> - Cleaning up the comments at the top
>> - Removing set -e (why?)
> 
> set -e fails the script immediately which prevents giving the user some
> facts about an error
> 

It fails the script only if you don't do proper error handling. Which we 
should be doing.

If error handling is missing and set -e is set, the script will stop 
where it fails.
If error handling is missing and set -e is not set, the script will 
happily continue and fail in some random places later on.

I prefer the first one. Personal preference though (and likely of the 
author(s) of the original script).

>> - Moving print_usage somewhere else
>> - Changing the output of print_usage
>> - Reordering cases in the switch..case for the subtree-name
>> - Changing URL of GNU mirror (which very much looks like a typo as it
>> doesn't seem to be what the link pasted above says the new URLs should
>> look like, albeit working somehow)
> 
> I got this information from the person working on it for FSF. I will
> review to see if it is better documented somewhere, but this is their
> suggestion both the load balance URL to use and the public announcement
> reference.
> 

https://lists.gnu.org/archive/html/savannah-users/2025-05/msg00002.html 
says

     https://gitweb.git.savannah.gnu.org/gitweb/
     https://cgit.git.savannah.gnu.org/cgit/

not

https://https.git.savannah.gnu.org/git/lwip.git

I needed to go to the cgit page of the project to find the clone 
instructions where
https://https.git.savannah.gnu.org/git/lwip.git is mentioned, c.f. 
https://cgit.git.savannah.gnu.org/cgit/lwip.git/

or also on gitweb:
https://gitweb.git.savannah.gnu.org/gitweb/?p=lwip.git&view=view+git+repository

Please mention this instead of simply linking to the mailing list 
archive which doesn't mention that at all.

>> - Adding new features (each its own commit please)
>>
>> You also do not explain what your pain points were when using this
>> script. This would be useful information now for reviewing and for later
>> if/when this gets merged so we know what kind of confusion happened in
>> the past so that potential future reworks don't reintroduce the same
>> problems.
> 
> I was never able to get this to work by the description in build
> documentation. I have a choice to do a lengthy explanation in
> documentation to improve that or just make the command more
> user-friendly - I will try making it better before giving up and
> increasing the word count of the documentation.
> 

You should justify your patch. Why is it better than the current 
implementation? How is that "improving the user experience"? It improves 
yours, but maybe it's worse for everybody else now? What was confusing?

I'm not asking to write documentation, I'm asking for the reasons you 
wrote this patch so we know better than reintroducing these issues later 
on or for other scripts. With this patch here, the project cannot learn 
what it did wrong and cannot improve.

>>
>> If I remember correctly, the biggest issue was that a pull dts was
>> attempted instead of multiple cherry-picks? I believe nobody except Tom
>> (for DTS) and whoever are the maintainers of lwip/mbedtls for the
>> respective projects should be running the pull option. The diff is too
> 
> Yes, this is not clear from documentation presently. The tool should not

Agreed.

> punish the user for misuse or ignorance about commit ids before getting
> to the moment where they can begin to learn about such things.
> 

 From that, I assume you mean that you would like the tool to catch 
whether the attempted cherry-pick is a merge commit and error in that case?

Cheers,
Quentin