See below for a revised project application. More comments would be appreciated. Thanks to Shawn, Dscho and Andreas for already offering some help! Title: git-submodule for multiple, active developers on active trees Abstract: This project focuses on upgrading git-submodule to manage code created in external projects in ways that allow users to safely branch and merge that code without loss of data or routine merge conflicts. This will incorporate some unfinished patches, but will also include making substantial changes to the underlying code of git-submodule. Content: Today, git-submodule is a solid component designed to allow developers to leverage the work of others by incorporating external code into a project. However, as most core developers are not heavy users of the feature its implementation is underdeveloped [1], which creates problems when it does not act according to developers’ expectations based on the robustness of other git features. This project would devote a summer of work to filling in the gaps so that git-submodule contains the features necessary to fully exploit its potential to track, update and edit external codebases incorporated into a super-project. Submodules are unique in their goal. As opposed to “remotes,” which also incorporate external code into a project, submodules maintain the distinct nature of code and separate projects’ histories. This is perfect for the intended nature of “embedding foreign repositories in dedicated subdirectories of the source tree.”[2] For example, managing plug-ins within a larger, standalone project that depends on them is an important technique to leverage others' work and shorten the development process made much more difficult by the shortcomings of git-submodule and require laborious workarounds or explicit manual content management.[3] Adding the most commonly requested features would give current users a desired tool, boost git’s credibility by providing a common feature among revision control systems, make the adoption of git for new and existing projects easier and, as a result, likely boost git’s overall usage. This project will consist of several stages: an initial community based design review and investigation of specific requirements; specifying and documenting the planned changes; and writing, debugging and merging the code and related tests. A few specific changes that this project will likely include are: *move objects of submodules into base .git/ directory **This would accomplish two goals. It would protect submodules from being overwritten, and implicitly, modified content from potentially being lost. This can happen when a branch with a submodule is replaced by checking out a branch of a super-project that does not contain the submodule. As well, this would centralize submodule management into one location. The added benefits of fully using git's ability to branch and merge submodules makes it worth adding complexity in the .git directory to accomplish this. Basically, this would add support for local branches of submodules.[4] *make git-submodule help with merging **Instead of issuing merge conflicts on updated submodule references, this will allow submodules on default detached HEAD so that changes from the local repo can be committed without first pulling changes from the shared repository. This made 'submodules...unsuitable for active development'.[5] Clearly losing this kind of functionality impairs the overall usability of git and should be fixed. Essentially, this would enable branch and merging between local and remote repositories. *protect changes in local submodules when doing “git submodule update” **This is similar to the previous point, in that changes need to be protected or merged or warnings issued when updating the submodule. The potential to lose work with no warning is a big no-no. *prevent unintentional super-project push without previous submodule push **A common mistake made when using git-submodule is to commit and push the super-project, without first pushing the latest commits in the submodule. This problem will require some brainstorming to find a good solution. *make git submodules easy to remove ** Adding a submodule has UI, removing one should as well.[6] There shouldn't have to be a tutorial on how to do it.[7] These major changes are in addition to some bug-fixes which include: git submodule summary should output to the pager by default; and finishing the implementation of git submodule recurse [8]. The tentative timeline is: End of May – Conclusively finish the public discussion regarding features to be added to git-submodule Beginning of June – work on git submodule remove as a way to become familiar with the code and accomplish an "easy" first win. Middle of June – move objects of submodules into base .git/ directory. This should take up the majority of the month and will likely constitute the major portion of contributed code for the summer. Middle of July – make submodules deal with updated references, this is the second key component of upgrading submodules for use on active trees. End of July – protect changes in local submodules during “git submodule update”. This will interact with the previous work, and might implicitly be solved by it, if not, it Middle of August – if time permits, finish git submodule recurse. This timeline should allow adequate flexibility while establishing deadlines that ensure that the project will be completed in a timely and efficient manner. Most development will need to occur within git-submodules.sh, without changing much plumbing, however, other files might be affected by more substantial changes. While git-submodule is stable and operational, it has not seen much change beyond bug-fixes. After reaching its current feature complete status, the last time a feature of any novelty was included in a public release was August 2008. However, some work has already been started by different contributors who have started patches, but not seen their inclusion into a public release.[9][10] The project will incorporate and conclude these patches. At the end of the project, one metric by which to evaluate its success will be its acceptance in online communities. The final goal is to make git a top-tier version control system in its management of external code repositories. My main usage of git started as an intern when managing a summer project that had many of the requirements that make git-submodule problematic: built in a web application framework and dependent on plug-ins, some of which were managed in SVN. Even though the Ruby on Rails community has popularized the use of git-submodule to manage plug-ins, and quite a bit has been written on the topic, a significant portion of explanations end either in frustration or convoluted workarounds. Personally, the problems and confusing nature of git-submodule led me to give up on it altogether, and manage the code and updates to it by hand. The need for improvement is clearly indicated by the frequency with which improvements are requested (for example, in the Git 2009 User Survey responses [11]). I currently am finishing my sophomore year as an Electrical Engineer at the University of Pennsylvania (and dual-majoring in the Wharton School of Business). I started to develop professionally when I took a year off between high school and college to work for a small firm in Silicon Valley, California developing diagnostic imaging software for quality assurance and research on their products. Last summer I developed a Ruby on Rails-based engine to test user-designed investment strategies for QED Benchmark, a boutique hedge fund. [1]http://article.gmane.org/gmane.comp.version-control.git/79167 [2]http://www.kernel.org/pub/software/scm/git/docs/git-submodule.html [3]http://flavoriffic.blogspot.com/2008/05/managing-git-submodules-with-gitrake.html?showComment=1210125780000#c1605130977296198852 [4]http://marc.info/?l=git&m=121726233001151&w=2 [5]http://flavoriffic.blogspot.com/2008/05/managing-git-submodules-with-gitrake.html?showComment=1211380200000#c3897235118548537475 [6]See http://pitupepito.homelinux.org/?p=24, for an example of how the current process is hard. [7]http://git.or.cz/gitwiki/GitSubmoduleTutorial [8]http://article.gmane.org/gmane.comp.version-control.git/69834 [9]http://marc.info/?l=git&m=121676896924019&w=2 [10]http://article.gmane.org/gmane.comp.version-control.git/88724/match=gitmodules [11] Thanks, P Baker -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
