Re: RFC/Discussion - Submodule UX Improvements

[Jacob Keller <jacob.keller@gmail.com>]

On Fri, Apr 16, 2021 at 4:38 PM Emily Shaffer <emilyshaffer@google.com> wrote:
>
> Hi folks,
>
> As hinted by a couple recent patches, I'm planning on some pretty big submodule
> work over the next 6 months or so - and Ævar pointed out to me in
> https://lore.kernel.org/git/87v98p17im.fsf@evledraar.gmail.com that I probably
> should share some of those plans ahead of time. :) So attached is a lightly
> modified version of the doc that we've been working on internally at Google,
> focusing on what we think would be an ideal submodule workflow.
>
> I'm hoping that folks will get a chance to read some or all of it and let us
> know what sounds cool (or sounds extremely broken). The best spot to start is
> probably the "Overview" section, which describes what the "main path" would look
> like for a user working on a project with submodules. Most of the work that
> we're planning on doing is under the "What doesn't already work" headings.
>
> Thanks in advance for any time you spend reading/discussing :)
>
>  - Emily
>
> Background
> ==========
>
> It's worth mentioning that the main goal that's funding this work is to provide
> an alternative for users whose projects use repo
> (https://source.android.com/setup/develop#repo) today. That means that the main
> focus is to try and reach feature parity to repo for an easier transition for
> those who want to switch. As a result, some of the direction below is aimed
> towards learning from what has worked well with repo (but hopefully more
> flexible for users who want to do more, or differently).
>
> There are also a few things mentioned that are specifically targeted to ease use
> with Gerrit, which is in wide use here at Google (and therefore also a
> consideration we need to make to keep getting paid ;) ).
>
> Overview
> =======
>

One thing that I think I didn't see covered when I scanned this, that
is something I find difficult or annoying to resolve is using "blame"
with submodules. I use blame a lot to do code history analysis to
understand how something got to the way it is. (Often this helps
resolve issues or bugs by using new context to understand why an old
change was broken).

It has bothered me in the past when I try to do "git blame
<path/to/submodule>" and I get nothing. Obviously there are ways
around this: you can for example just log the path and get the commit
that changed it most recently, or try to search for when the submodule
was set to a given commit.

A sort of dream I had was a flow where I could do something from the
parent like "git blame <path/to/submodule>/submodule/file" and have it
present a blame of that files contents keyed on the *parent* commit
that changed the submodule to have that line, as opposed to being
forced to go into the submodule and figure out what commit introduced
it and then go back to the parent and find out what commit changed the
submodule to include that submodule commit.

> When the work is completed, users should be able to have a clean, obvious
> workflow when using best practices:
>
> To download the code, they should be able to run simply git clone
> https://example.com/superproject to download the project and all its submodules;
> if partial clone is configured, they should receive only the objects allowed by
> the filter in their superproject as well as in each submodule.
>
> To begin working on a feature, from the superproject they can 'git switch -c
> feature', and since the new branch is being created, a new branch 'feature' will
> be created for each submodule, pointing to the submodule's current 'HEAD'. They
> can move to a submodule directory and begin to make changes, and when they
> commit these changes normally with 'git commit' from the submodule directory,
> running git status in the superproject will reflect that a submodule has
> changed. Next, they can switch to a second submodule, making and committing more
> changes.
>
> When they are ready to send these changes which are ready for review but need to
> be linked together, they can switch back to the superproject, where 'git status'
> indicates that there are changes in both submodules. They can commit these
> changes to the superproject and use 'git push' to send a review; Git will
> recurse into affected submodules and push those submodule commits appropriately
> as well.
>
> While the user is waiting for feedback on their review, to work on their next
> task, they can 'git switch other-feature', which will checkout the branches
> specified in the superproject commit at the tip of 'other-feature'; now the user
> can continue working as before.
>
> When it's time to update their local repo, the user can do so as with a
> single-repo project. First they can 'git checkout main && git pull' (or 'git
> pull -r'); Git will first checkout the branches associated with main in each
> submodule, then fetch and merge/rebase in each submodule appropriately. Finally,
> they can 'git switch feature && git rebase', at which time Git will recursively
> checkout the branches associated with 'feature' in each submodule and rebase
> each submodule appropriately.
>