{"thread":{"id":"66790","subject":"[Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering","startedAt":"2026-11-06T13:18:36Z","lastAt":"2026-11-13T13:10:29Z","messageCount":2,"participants":["Shashank S","Kaartic Sivaraam"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"557674","messageId":"CANHmUQQvN0xQuXqTE2imochXyQuU_ag3KHb0gkGEZ-cPLFbBYg@mail.gmail.com","threadId":"66790","inReplyTo":null,"subject":"[Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering","fromName":"Shashank S","fromEmail":"shashu8660@gmail.com","sentAt":"2026-11-06T13:18:36Z","receivedAt":"2026-11-06T13:18:36Z","isPatch":false,"sender":{"key":"shashu8660@gmail.com","avatar":null},"body":"Hello mentors and Git community,\n\nThis is my revised proposal for the “Implement promisor remote fetch\nordering” project for the December 2026 Outreachy internship.\n\nChanges since v2:\n\n- Corrected my description of the current behavior: it is deterministic,\nbut it has no separately user-configurable ordering mechanism.\n\n- Reduced the focused Phase 1 implementation work to three days, with\nreview continuing asynchronously while the RFC discussion begins.\n\n- Removed my pre-selected commitment to promisor.fetchOrder; the\nconfiguration shape will be decided through an early mailing-list RFC.\n\n- Corrected my description of promisor.sendFields: it already exists.\nThe project may extend the existing optional-field mechanism with an\nordering-related field, subject to RFC consensus.\n\n-Added technical risks, design criteria, and explicit coordination with\nactive upstream work.\n\n- Updated contribution status and restored mailing-list links.\n\nPersonal Information:\n-----------------------------\n\nFull Name: Shashank S Mogaveera\nEmail: shashu8660@gmail.com\nGitHub: https://github.com/shashu8660\nLocation: Kundapur, Karnataka, India (IST, UTC+5:30)\n\nAbout Me\n-------------\n\nI am a software developer interested in C programming, distributed\nsystems and network-facing infrastructure.\n\nDuring the Outreachy contribution period, I contributed to Git’s test,\noption-parsing, and repository-libification work. Studying partial\nclones,the promisor-remote protocol, and Trace2 traces of lazy\nfetching showed me how a missing object travels from object lookup to\na git fetch subprocess. That made promisor remote fetch ordering the\nproject I most want to pursue.\n\nPast Experience with Git\n---------------------------------\n\nI have been using Git extensively for version control in my personal\nprojects. This contribution period was my first time engaging directly\nwith a mailing list-based open-source community.\n\nLearning to use git send-email and GitGitGadget to format patches,\nmanage versioned rerolls, and incorporate maintainer feedback has been\na massive learning curve, but a highly rewarding one. I learned the\nimportance of atomic commits, clean commit messages, and the strict\nrules around not ignoring Git's exit codes in shell scripts.\n\nContributions to the Git Community\n-----------------------------------------------\n\n1. t0081: modernize the code testing whether a file exists\n    Mailing-list thread:\n https://lore.kernel.org/git/pull.2254.git.1791962806807.gitgitgadget@gmail.com/\n    Status: Merged to master.\n     Commit:\nhttps://github.com/gitgitgadget/git/commit/e1bb515788e48d500c9d4e36f13c66c4daddd3d4\n\n2. t2403: modernize test for directory existence\n     Mailing-list thread:\nhttps://lore.kernel.org/git/pull.2259.git.1792125111461.gitgitgadget@gmail.com/\n      Status: Merged into the seen integration branch.\n      Commit:\nhttps://github.com/git/git/commit/c645a5db002ded161115dc8f6c15a40acfdde2b2\n\n3. prune-packed: remove USE_THE_REPOSITORY_VARIABLE\n     Mailing list thread:\nhttps://lore.kernel.org/git/pull.2266.git.1792341073005.gitgitgadget@gmail.com/\n     Status: “Will merge to master” according to “What’s cooking”.\n    Commit :\n https://github.com/git/git/commit/936609cfa0a57e1b047c345a91fec79ab255897c\n\n4. test-chmtime: use parse_options() to parse command-line flags\n     Mailing list thread:\nhttps://lore.kernel.org/git/pull.2280.git.1793099688076.gitgitgadget@gmail.com/\n     Status: Merged into the seen integration branch.\n     Commit :\nhttps://github.com/git/git/commit/c6a318cc4b8c6f6ce1a403e497816cd195c57cf7\n\nProject Overview: Promisor Remote Fetch Ordering\n----------------------------------------------------------------------\n\nGit can lazily fetch missing objects from multiple promisor remotes in\na partial clone. Today, Git uses a deterministic baseline order:\naccepted server-advertised remotes are tried first, other configured\npromisor remotes follow configuration order, and the\n`extensions.partialClone` remote is tried last. However, users cannot\nexplicitly configure that order, and servers cannot provide a separate\nordering preference for clients to combine with local policy.\n\nThis project will design and implement a configurable ordering\nmechanism for promisor remotes. The client-side configuration shape\nand any protocol-v2 advertisement format will be decided through\nmailing-list RFC discussion, with attention to backward compatibility,\nlocal-versus-server precedence, and safe handling of invalid data.\n\nPhase 0 Progress:\n-------------------------\n\nI completed the relevant onboarding work before the internship.\n\nBuild and test verification:\n\nI built Git from source on macOS. The resulting binary reports:\n[git version 2.56.GIT]\n\nI ran the two relevant test scripts:\n\n- t5710-promisor-remote-capability.sh reported all 33 tests passed.\n- t0410-partial-clone.sh reported all 39 tests passed. Its loca\nApache-based web-server setup was skipped because Apache could not\naccess its configuration path on my macOS setup.\n\n\nMulti-promisor-remote playground:\n\nI created local origin, cache-a, and cache-b repositories, configured\nthem as promisor remotes, and created a blob:none partial clone with\nno-checkout. This ensured that the commit and tree were present\nlocally while the content of bar remained absent.\n\nI then accessed HEAD:bar with GIT_TRACE2_EVENT enabled.\n\nWith extensions.partialClone=origin, the Trace2 child_start event showed:\n\n-   git fetch cache-a ...\n\nThis demonstrated that Git tried cache-a before origin.\n\nIn a second fresh clone, I configured cache-a with an unavailable URL.\n\nTrace2 showed:\n\n- git fetch cache-a ...\n- git fetch cache-b ..\n\nGit then fetched the missing blob successfully from cache-b; it did not\nneed to contact origin.\n\nThe Trace2 event promisor.fetch_count records the number of object IDs\npassed to each promisor-fetch subprocess. It does not identify the\nselected remote. I therefore used child_start events to establish\nremote order.\n\nCurrent behavior and code understanding:\n\nI studied -\n1. [https://git-scm.com/docs/partial-clone]\n2. [https://git-scm.com/docs/gitprotocol-v2]\n3. t/t5710-promisor-remote-capability.sh\n4. t/t0410-partial-clone.sh\n5. promisor-remote.c.\n\nThe current behavior is deterministic but has no separately\nconfigurable priority mechanism:\n\n1. lazy_fetch_objects() first calls try_promisor_remotes() for remotes\naccepted through the promisor-remote protocol exchange.\n2. It then calls the same helper for remaining configured promisor\nremotes, whose order comes from configuration parsing order.\n3. promisor_remote_init() moves the remote named by\nextensions.partialClone to the tail of the list\n4. If a fetch fails, Git continues with another eligible promisor\nremote until all requested objects are present or no remotes remain.\n\nMy manual Trace2 experiment verifies configured-remote order and\nfallback. I will not claim it independently proves\naccepted-remotes-first behavior that rule is covered by the protocol\ntest and code path above.\n\nDesign Questions and Initial Reasoning:\n-----------------------------------------------------\n\nI do not consider the design settled before mailing-list discussion. My\ninitial analysis identifies the following questions.\n\nClient configuration shape:\n\nThe RFC will compare:\n\n- an ordered list, such as promisor.fetchOrder; and\n- a per-remote numeric value, such as remote <name>.promisorPriority.\n\nA list makes the intended sequence easy to read in one place, but must\ndefine how values from system, global, and repository configuration\ncompose. A numeric value can change one remote without naming every\nother remote, but requires tie-breaking and a clear convention for\nunranked remotes.\n\nThe RFC will evaluate both approaches using the same criteria:\n\n- configuration layering and overrides;\n- duplicate entries or equal priorities;\n- unlisted remotes;\n- nonexistent or non-promisor remote names;\n- interaction with accepted remotes; and\n- interaction with extensions.partialClone.\n\nI will not select an implementation representation until consensus on\nthese semantics is reached.\n\nServer-advertised ordering\n\npromisor.sendFields already exists. It controls optional fields sent\nin a promisor-remote advertisement; currently supported fields include\npartialCloneFilter and token.\n\nThe protocol RFC will compare two possible designs:\n\n1. advertisement order itself expresses server preference or\n2. the server advertises an explicit ordering-related field, such as a\nnumeric priority.\n\nAn explicit field may preserve the server’s intent even if a client later\nreorders remotes, but it adds parsing, validation, and documentation\nwork. Advertisement order is simpler on the wire, but may be less\nexplicit once a client combines local and server information.\n\nIf the RFC selects a new field, the implementation will extend the\nexisting promisor.sendFields machinery, the promisor-remote parser,\nprotocol documentation, and tests. Older clients must safely ignore\nthe unknown field.\n\nPrecedence and persistence:\n\nMy starting principle for discussion is that an explicit local client policy\nshould not be silently overridden by a server, because clients may\nhave their own cost, reliability, or privacy constraints. One possible\npolicy is for server preference to order only remotes that have no\nexplicit local ranking.\n\nThis is a proposal for discussion, not a fixed decision. The RFC must settle:\n\n- whether local order applies across the accepted/unaccepted two-pass\nsplit or only within each group;\n- whether extensions.partialClone remains last even when explicitly ranked;\n- whether server-provided ordering is stored through the existing\npromisor.storeFields mechanism; and\n- whether a stored ordering value remains valid after later local\nconfiguration changes.\n\nImplementation Risks:\n\nThe remote list is a singly linked list, and current lazy fetching\nmakes two passes over it: accepted remotes, then remaining configured\nremotes. A refactor must preserve this behavior until a reviewed\nsemantic decision changes it.\n\nConfiguration parsing is also part of the feature design . A change\nmust not make effective order depend accidentally on an implementation\ndetails of config file loading, or make invalid remote names fatal\nduring lazy fetching.\n\nIf the protocol RFC chooses a numeric field , parsing must reject\nmalformed and overflowing values safely . If it chooses advertisement\norder , tests must still define exactly how the client combines that\norder with local policy.\n\nFinally, active patches may land before or during the internship. I\nwill inspect active threads and current branches before beginning each\npatch, avoid duplicating work, and adapt the plan with mentor\nguidance.\n\n13-Week Internship Plan:\n\nWeek 1: Baseline visibility and safety net\n\nThe focused baseline implementation work should take approximately\nthree days, not two weeks. Review can continue in parallel after\npatches are sent.\n\nDays 1–3:\n\n- Audit current master, next, seen, and active mailing-list threads.\n- Confirm which documentation and test coverage has already landed or\nis in review; do not duplicate another contributor’s work.\n- Where a baseline gap remains, prepare a small docs or test patch\nthat documents or asserts existing behavior only accepted remotes\nfirst, configured remotes in configuration order,\nextensions.partialClone last, and fallback after failure.\n- Send the patch early and respond to review.\n\nDays 4–7:\n\n- Begin the client-configuration RFC preparation.\n- Refine examples and edge cases from the local playground.\n- Continue responding to any Week 1 patch review.\n\nWeek 2: Client-ordering RFC\n\n- Send an RFC to the mailing list comparing list and numeric-priority\ndesigns.\n- Ask for agreement on configuration layering, invalid entries,\nunranked remotes, accepted-remotes interaction, and\nextensions.partialClone.\n- Revise the proposed semantics from reviewer feedback before\nbeginning a behavior-changing implementation.\n\nWeeks 3–4: Client-side implementation\n\nAfter agreement on the RFC direction:\n\n- Separate any behavior-preserving list-management refactor from the\nconfiguration behavior change.\n- Implement the agreed local configuration parser and ordering logic.\n- Preserve existing behavior for users without the new configuration.\n- Add tests for empty configuration, duplicate values, unknown names,\nunranked remotes, accepted-remotes interaction, and the agreed\nextensions.partialClone behavior.\n- Update the appropriate configuration documentation:\nDocumentation/config/promisor.adoc\nDocumentation/config/remote.adoc\n- Send the first coherent client-side patch series no later than the\nend of Week 4, and preferably earlier if it is ready.\n\nWeek 5: Client-side review and protocol RFC preparation\n\n- Respond to review and send rerolls of the client-side series.\n- Write protocol specification wording before implementation.\n- Prepare examples demonstrating both explicit-field and\nadvertisement-order designs.\n- Identify exactly what must change in promisor.sendFields,\npromisor.checkFields, and promisor.storeFields if a new field is\nselected.\n\nWeek 6: Protocol RFC and discussion\n\n- Send the protocol RFC to the mailing list.\n- Discuss the field format or advertisement-order semantics,\nclient/server precedence, malformed data handling, backward\ncompatibility, and persistence.\n- Incorporate review before writing server or client protocol code.\n\nWeeks 7–8: Server advertisement and client parsing\n\nAfter protocol agreement:\n\n- Extend the server-side optional-field support to advertise the agreed\nordering information.\n- Extend the client parser to recognize and validate that information.\n- Keep old-client behavior safe through the existing unknown-field rule.\n- Implement the agreed precedence rule between local configuration and\nserver information.\n- Implement persistence through promisor.storeFields only if that\nbehavior is approved in the RFC.\n\nWeek 9: Protocol tests and first server-side series\n\n- Add protocol-v2 tests covering valid advertisements, absent fields,\nmalformed values, ignored unknown fields, client-versus-server\nprecedence, and old-client compatibility.\n- Extend the relevant tests in t5710-promisor-remote-capability.sh.\n- Send the first coherent protocol/server-side patch series for review.\n\nWeeks 10–11: Review and rerolls\n\n- Respond promptly to review on both series.\n- Keep rerolls small and explain changes with range-diffs where useful.\n- Run focused tests after each revision and wider test coverage before\nresubmission.\n- Run leak-sanitizer testing where supported by the development environment.\n- Keep documentation and tests synchronized with reviewer-approved semantics.\n\nWeek 12: Stabilization and integration readiness\n\n- Recheck all configuration, protocol, and partial-clone documentation.\n- Run the relevant test scripts and broader regression tests.\n- Reproduce the key Trace2 scenarios manually to confirm the tested behavior.\n- Address remaining review comments and prepare patches for maintainer\nintegration. The decision to advance a topic through seen, next, or\nmaster remains with maintainers.\n\nWeek 13: Final polish and wrap-up\n\n- Finalize release-note and user-facing documentation updates, if appropriate.\n- Publish the final internship report and a concise technical summary.\n- Use any remaining time only for follow-up fixes or review; dynamic\nlatency-based reordering and in-process failure memory remain stretch\nwork, not commitments.\n\nAvailability\n\nI can commit 40 hours per week exclusively to this project throughout\nthe internship period. I have no university exams, classes, other\njobs, or planned vacations that conflict with 7 December 2026 through\n8 March 2027.\n\nI am based in IST (UTC+5:30) and can adjust my hours for synchronous\ndiscussion, pair programming, and timely mailing-list replies.\n\nCommunication and Long-Term Contribution\n\nI will publish concise weekly updates covering experiments, RFC\ndecisions, patches, review feedback, and next steps. I will remain\nactive on the mailing list and will communicate early if a schedule or\ntechnical risk affects the plan.\n\nAfter the internship, I intend to continue contributing to Git,\nespecially in promisor-remote and repository-libification work,\nincluding reducing remaining unnecessary reliance on global repository\nstate.\n\nThank you\n\nShashank S Mogaveera\n\n"},{"id":"558386","messageId":"17a5f239-1b95-4909-b3f4-b9555039ef2e@gmail.com","threadId":"66790","inReplyTo":"CANHmUQQvN0xQuXqTE2imochXyQuU_ag3KHb0gkGEZ-cPLFbBYg@mail.gmail.com","subject":"Re: [Outreachy] Project Proposal [v3]: Implement promisor remote fetch ordering","fromName":"Kaartic Sivaraam","fromEmail":"kaartic.sivaraam@gmail.com","sentAt":"2026-11-13T13:10:29Z","receivedAt":"2026-11-13T13:10:29Z","isPatch":false,"sender":{"key":"kaartic.sivaraam@gmail.com","avatar":"https://avatars.githubusercontent.com/u/12448084?v=4"},"body":"Hi Shashank,\n\nOn 11/6/26 18:48, Shashank S wrote:\n>  > Design Questions and Initial Reasoning:\n> -----------------------------------------------------\n> > I do not consider the design settled before mailing-list discussion. My\n> initial analysis identifies the following questions.\n> > Client configuration shape:\n> > ... snip ...\n> > Server-advertised ordering\n> > ... snip ...\n> > Precedence and persistence:\n> > ... snip ...\n> > Implementation Risks:\n> > ... snip ...\n> Thank you for the additional details! It is nice to know what all you've thought about.\n\n> 13-Week Internship Plan:\n> > ... snip ...\nThis plan reads a lot better!\n\n> Availability\n> > I can commit 40 hours per week exclusively to this project throughout\n> the internship period. I have no university exams, classes, other\n> jobs, or planned vacations that conflict with 7 December 2026 through\n> 8 March 2027.\n> > I am based in IST (UTC+5:30) and can adjust my hours for synchronous\n> discussion, pair programming, and timely mailing-list replies.\n> > Communication and Long-Term Contribution\n> > I will publish concise weekly updates covering experiments, RFC\n> decisions, patches, review feedback, and next steps. I will remain\n> active on the mailing list and will communicate early if a schedule or\n> technical risk affects the plan.\n> > After the internship, I intend to continue contributing to Git,\n> especially in promisor-remote and repository-libification work,\n> including reducing remaining unnecessary reliance on global repository\n> state.\n> Sounds good. Thank you for taking the time to draft this!\n\n-- \nSivaraam\n\n\n"}]}