[Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering

[Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering

[Shashank S]

Hello mentors and Git community,

This is my revised proposal for the “Implement promisor remote fetch
ordering” project for the December 2026 Outreachy internship.

Changes since v2:

- Corrected my description of the current behavior: it is deterministic,
but it has no separately user-configurable ordering mechanism.

- Reduced the focused Phase 1 implementation work to three days, with
review continuing asynchronously while the RFC discussion begins.

- Removed my pre-selected commitment to promisor.fetchOrder; the
configuration shape will be decided through an early mailing-list RFC.

- Corrected my description of promisor.sendFields: it already exists.
The project may extend the existing optional-field mechanism with an
ordering-related field, subject to RFC consensus.

-Added technical risks, design criteria, and explicit coordination with
active upstream work.

- Updated contribution status and restored mailing-list links.

Personal Information:
-----------------------------

Full Name: Shashank S Mogaveera
Email: shashu8660@gmail.com
GitHub: https://github.com/shashu8660
Location: Kundapur, Karnataka, India (IST, UTC+5:30)

About Me
-------------

I am a software developer interested in C programming, distributed
systems and network-facing infrastructure.

During the Outreachy contribution period, I contributed to Git’s test,
option-parsing, and repository-libification work. Studying partial
clones,the promisor-remote protocol, and Trace2 traces of lazy
fetching showed me how a missing object travels from object lookup to
a git fetch subprocess. That made promisor remote fetch ordering the
project I most want to pursue.

Past Experience with Git
---------------------------------

I have been using Git extensively for version control in my personal
projects. This contribution period was my first time engaging directly
with a mailing list-based open-source community.

Learning to use git send-email and GitGitGadget to format patches,
manage versioned rerolls, and incorporate maintainer feedback has been
a massive learning curve, but a highly rewarding one. I learned the
importance of atomic commits, clean commit messages, and the strict
rules around not ignoring Git's exit codes in shell scripts.

Contributions to the Git Community
-----------------------------------------------

1. t0081: modernize the code testing whether a file exists
    Mailing-list thread:
 https://lore.kernel.org/git/pull.2254.git.1791962806807.gitgitgadget@gmail.com/
    Status: Merged to master.
     Commit:
https://github.com/gitgitgadget/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d4

2. t2403: modernize test for directory existence
     Mailing-list thread:
https://lore.kernel.org/git/pull.2259.git.1792125111461.gitgitgadget@gmail.com/
      Status: Merged into the seen integration branch.
      Commit:
https://github.com/git/git/commit/c645a5db002ded161115dc8f6c15a40acfdde2b2

3. prune-packed: remove USE_THE_REPOSITORY_VARIABLE
     Mailing list thread:
https://lore.kernel.org/git/pull.2266.git.1792341073005.gitgitgadget@gmail.com/
     Status: “Will merge to master” according to “What’s cooking”.
    Commit :
 https://github.com/git/git/commit/936609cfa0a57e1b047c345a91fec79ab255897c

4. test-chmtime: use parse_options() to parse command-line flags
     Mailing list thread:
https://lore.kernel.org/git/pull.2280.git.1793099688076.gitgitgadget@gmail.com/
     Status: Merged into the seen integration branch.
     Commit :
https://github.com/git/git/commit/c6a318cc4b8c6f6ce1a403e497816cd195c57cf7

Project Overview: Promisor Remote Fetch Ordering
----------------------------------------------------------------------

Git can lazily fetch missing objects from multiple promisor remotes in
a partial clone. Today, Git uses a deterministic baseline order:
accepted server-advertised remotes are tried first, other configured
promisor remotes follow configuration order, and the
`extensions.partialClone` remote is tried last. However, users cannot
explicitly configure that order, and servers cannot provide a separate
ordering preference for clients to combine with local policy.

This project will design and implement a configurable ordering
mechanism for promisor remotes. The client-side configuration shape
and any protocol-v2 advertisement format will be decided through
mailing-list RFC discussion, with attention to backward compatibility,
local-versus-server precedence, and safe handling of invalid data.

Phase 0 Progress:
-------------------------

I completed the relevant onboarding work before the internship.

Build and test verification:

I built Git from source on macOS. The resulting binary reports:
[git version 2.56.GIT]

I ran the two relevant test scripts:

- t5710-promisor-remote-capability.sh reported all 33 tests passed.
- t0410-partial-clone.sh reported all 39 tests passed. Its loca
Apache-based web-server setup was skipped because Apache could not
access its configuration path on my macOS setup.


Multi-promisor-remote playground:

I created local origin, cache-a, and cache-b repositories, configured
them as promisor remotes, and created a blob:none partial clone with
no-checkout. This ensured that the commit and tree were present
locally while the content of bar remained absent.

I then accessed HEAD:bar with GIT_TRACE2_EVENT enabled.

With extensions.partialClone=origin, the Trace2 child_start event showed:

-   git fetch cache-a ...

This demonstrated that Git tried cache-a before origin.

In a second fresh clone, I configured cache-a with an unavailable URL.

Trace2 showed:

- git fetch cache-a ...
- git fetch cache-b ..

Git then fetched the missing blob successfully from cache-b; it did not
need to contact origin.

The Trace2 event promisor.fetch_count records the number of object IDs
passed to each promisor-fetch subprocess. It does not identify the
selected remote. I therefore used child_start events to establish
remote order.

Current behavior and code understanding:

I studied -
1. [https://git-scm.com/docs/partial-clone]
2. [https://git-scm.com/docs/gitprotocol-v2]
3. t/t5710-promisor-remote-capability.sh
4. t/t0410-partial-clone.sh
5. promisor-remote.c.

The current behavior is deterministic but has no separately
configurable priority mechanism:

1. lazy_fetch_objects() first calls try_promisor_remotes() for remotes
accepted through the promisor-remote protocol exchange.
2. It then calls the same helper for remaining configured promisor
remotes, whose order comes from configuration parsing order.
3. promisor_remote_init() moves the remote named by
extensions.partialClone to the tail of the list
4. If a fetch fails, Git continues with another eligible promisor
remote until all requested objects are present or no remotes remain.

My manual Trace2 experiment verifies configured-remote order and
fallback. I will not claim it independently proves
accepted-remotes-first behavior that rule is covered by the protocol
test and code path above.

Design Questions and Initial Reasoning:
-----------------------------------------------------

I do not consider the design settled before mailing-list discussion. My
initial analysis identifies the following questions.

Client configuration shape:

The RFC will compare:

- an ordered list, such as promisor.fetchOrder; and
- a per-remote numeric value, such as remote <name>.promisorPriority.

A list makes the intended sequence easy to read in one place, but must
define how values from system, global, and repository configuration
compose. A numeric value can change one remote without naming every
other remote, but requires tie-breaking and a clear convention for
unranked remotes.

The RFC will evaluate both approaches using the same criteria:

- configuration layering and overrides;
- duplicate entries or equal priorities;
- unlisted remotes;
- nonexistent or non-promisor remote names;
- interaction with accepted remotes; and
- interaction with extensions.partialClone.

I will not select an implementation representation until consensus on
these semantics is reached.

Server-advertised ordering

promisor.sendFields already exists. It controls optional fields sent
in a promisor-remote advertisement; currently supported fields include
partialCloneFilter and token.

The protocol RFC will compare two possible designs:

1. advertisement order itself expresses server preference or
2. the server advertises an explicit ordering-related field, such as a
numeric priority.

An explicit field may preserve the server’s intent even if a client later
reorders remotes, but it adds parsing, validation, and documentation
work. Advertisement order is simpler on the wire, but may be less
explicit once a client combines local and server information.

If the RFC selects a new field, the implementation will extend the
existing promisor.sendFields machinery, the promisor-remote parser,
protocol documentation, and tests. Older clients must safely ignore
the unknown field.

Precedence and persistence:

My starting principle for discussion is that an explicit local client policy
should not be silently overridden by a server, because clients may
have their own cost, reliability, or privacy constraints. One possible
policy is for server preference to order only remotes that have no
explicit local ranking.

This is a proposal for discussion, not a fixed decision. The RFC must settle:

- whether local order applies across the accepted/unaccepted two-pass
split or only within each group;
- whether extensions.partialClone remains last even when explicitly ranked;
- whether server-provided ordering is stored through the existing
promisor.storeFields mechanism; and
- whether a stored ordering value remains valid after later local
configuration changes.

Implementation Risks:

The remote list is a singly linked list, and current lazy fetching
makes two passes over it: accepted remotes, then remaining configured
remotes. A refactor must preserve this behavior until a reviewed
semantic decision changes it.

Configuration parsing is also part of the feature design . A change
must not make effective order depend accidentally on an implementation
details of config file loading, or make invalid remote names fatal
during lazy fetching.

If the protocol RFC chooses a numeric field , parsing must reject
malformed and overflowing values safely . If it chooses advertisement
order , tests must still define exactly how the client combines that
order with local policy.

Finally, active patches may land before or during the internship. I
will inspect active threads and current branches before beginning each
patch, avoid duplicating work, and adapt the plan with mentor
guidance.

13-Week Internship Plan:

Week 1: Baseline visibility and safety net

The focused baseline implementation work should take approximately
three days, not two weeks. Review can continue in parallel after
patches are sent.

Days 1–3:

- Audit current master, next, seen, and active mailing-list threads.
- Confirm which documentation and test coverage has already landed or
is in review; do not duplicate another contributor’s work.
- Where a baseline gap remains, prepare a small docs or test patch
that documents or asserts existing behavior only accepted remotes
first, configured remotes in configuration order,
extensions.partialClone last, and fallback after failure.
- Send the patch early and respond to review.

Days 4–7:

- Begin the client-configuration RFC preparation.
- Refine examples and edge cases from the local playground.
- Continue responding to any Week 1 patch review.

Week 2: Client-ordering RFC

- Send an RFC to the mailing list comparing list and numeric-priority
designs.
- Ask for agreement on configuration layering, invalid entries,
unranked remotes, accepted-remotes interaction, and
extensions.partialClone.
- Revise the proposed semantics from reviewer feedback before
beginning a behavior-changing implementation.

Weeks 3–4: Client-side implementation

After agreement on the RFC direction:

- Separate any behavior-preserving list-management refactor from the
configuration behavior change.
- Implement the agreed local configuration parser and ordering logic.
- Preserve existing behavior for users without the new configuration.
- Add tests for empty configuration, duplicate values, unknown names,
unranked remotes, accepted-remotes interaction, and the agreed
extensions.partialClone behavior.
- Update the appropriate configuration documentation:
Documentation/config/promisor.adoc
Documentation/config/remote.adoc
- Send the first coherent client-side patch series no later than the
end of Week 4, and preferably earlier if it is ready.

Week 5: Client-side review and protocol RFC preparation

- Respond to review and send rerolls of the client-side series.
- Write protocol specification wording before implementation.
- Prepare examples demonstrating both explicit-field and
advertisement-order designs.
- Identify exactly what must change in promisor.sendFields,
promisor.checkFields, and promisor.storeFields if a new field is
selected.

Week 6: Protocol RFC and discussion

- Send the protocol RFC to the mailing list.
- Discuss the field format or advertisement-order semantics,
client/server precedence, malformed data handling, backward
compatibility, and persistence.
- Incorporate review before writing server or client protocol code.

Weeks 7–8: Server advertisement and client parsing

After protocol agreement:

- Extend the server-side optional-field support to advertise the agreed
ordering information.
- Extend the client parser to recognize and validate that information.
- Keep old-client behavior safe through the existing unknown-field rule.
- Implement the agreed precedence rule between local configuration and
server information.
- Implement persistence through promisor.storeFields only if that
behavior is approved in the RFC.

Week 9: Protocol tests and first server-side series

- Add protocol-v2 tests covering valid advertisements, absent fields,
malformed values, ignored unknown fields, client-versus-server
precedence, and old-client compatibility.
- Extend the relevant tests in t5710-promisor-remote-capability.sh.
- Send the first coherent protocol/server-side patch series for review.

Weeks 10–11: Review and rerolls

- Respond promptly to review on both series.
- Keep rerolls small and explain changes with range-diffs where useful.
- Run focused tests after each revision and wider test coverage before
resubmission.
- Run leak-sanitizer testing where supported by the development environment.
- Keep documentation and tests synchronized with reviewer-approved semantics.

Week 12: Stabilization and integration readiness

- Recheck all configuration, protocol, and partial-clone documentation.
- Run the relevant test scripts and broader regression tests.
- Reproduce the key Trace2 scenarios manually to confirm the tested behavior.
- Address remaining review comments and prepare patches for maintainer
integration. The decision to advance a topic through seen, next, or
master remains with maintainers.

Week 13: Final polish and wrap-up

- Finalize release-note and user-facing documentation updates, if appropriate.
- Publish the final internship report and a concise technical summary.
- Use any remaining time only for follow-up fixes or review; dynamic
latency-based reordering and in-process failure memory remain stretch
work, not commitments.

Availability

I can commit 40 hours per week exclusively to this project throughout
the internship period. I have no university exams, classes, other
jobs, or planned vacations that conflict with 7 December 2026 through
8 March 2027.

I am based in IST (UTC+5:30) and can adjust my hours for synchronous
discussion, pair programming, and timely mailing-list replies.

Communication and Long-Term Contribution

I will publish concise weekly updates covering experiments, RFC
decisions, patches, review feedback, and next steps. I will remain
active on the mailing list and will communicate early if a schedule or
technical risk affects the plan.

After the internship, I intend to continue contributing to Git,
especially in promisor-remote and repository-libification work,
including reducing remaining unnecessary reliance on global repository
state.

Thank you

Shashank S Mogaveera

Re: [Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering

[Kaartic Sivaraam]

Hi Shashank,

On 11/6/26 18:48, Shashank S wrote:
>  
> Design Questions and Initial Reasoning:
> -----------------------------------------------------
> 
> I do not consider the design settled before mailing-list discussion. My
> initial analysis identifies the following questions.
> 
> Client configuration shape:
> 
> ... snip ...
> 
> Server-advertised ordering
> 
> ... snip ...
> 
> Precedence and persistence:
> 
> ... snip ...
> 
> Implementation Risks:
> 
> ... snip ...
> 

Thank you for the additional details! It is nice to know what all you've 
thought about.

> 13-Week Internship Plan:
> 
> ... snip ...
This plan reads a lot better!

> Availability
> 
> I can commit 40 hours per week exclusively to this project throughout
> the internship period. I have no university exams, classes, other
> jobs, or planned vacations that conflict with 7 December 2026 through
> 8 March 2027.
> 
> I am based in IST (UTC+5:30) and can adjust my hours for synchronous
> discussion, pair programming, and timely mailing-list replies.
> 
> Communication and Long-Term Contribution
> 
> I will publish concise weekly updates covering experiments, RFC
> decisions, patches, review feedback, and next steps. I will remain
> active on the mailing list and will communicate early if a schedule or
> technical risk affects the plan.
> 
> After the internship, I intend to continue contributing to Git,
> especially in promisor-remote and repository-libification work,
> including reducing remaining unnecessary reliance on global repository
> state.
> 

Sounds good. Thank you for taking the time to draft this!

-- 
Sivaraam