From: Shashank S Date: Fri, 06 Nov 2026 13:18:36 GMT Subject: [Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering Message-ID: 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 .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