diff --git a/.gitignore b/.gitignore index 29949d4658..eb676c0ab1 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ /_site /Gemfile.lock +/vendor diff --git a/GSoC-Participants.md b/GSoC-Participants.md new file mode 100644 index 0000000000..d9a68bf751 --- /dev/null +++ b/GSoC-Participants.md @@ -0,0 +1,211 @@ +--- +layout: default +title: GSoC participants +--- + +This document collects the list of contributors who've contributed +to Git via GSoC. + + + +### 2025 + +1. Ayush Chandekar [ [project](https://summerofcode.withgoogle.com/programs/2025/projects/no7dVMeG) ] [ [final report](https://ayu-ch.github.io/2025/08/29/gsoc-final-report.html) ] [ [blog](https://ayu-ch.github.io/) ] +2. Lucas Seiki Oshiro [ [project](https://summerofcode.withgoogle.com/programs/2025/projects/fGgMYHwl) ] [ [final report](https://lucasoshiro.github.io/gsoc-en/#final-report) ] [ [blog](https://lucasoshiro.github.io/gsoc-en/#weeks) ] +3. Meet Soni [ [project](https://summerofcode.withgoogle.com/programs/2025/projects/xVrT5e2q) ] [ [final report](https://inosmeet.github.io/posts/gsoc25/gsoc25_final/) ] [ [blog](https://inosmeet.github.io/posts/gsoc25/) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/programs/2025/organizations/git) +- [Rev News article](https://git.github.io/rev_news/2025/05/31/edition-123/) + +### 2024 + +1. Jialuo She [ [project](https://summerofcode.withgoogle.com/archive/2024/projects/ukm4PTEF) ] [ [final report](https://luolibrary.com/2024/08/25/GSoC-Final-Report/) ] [ [blog](https://luolibrary.com/) ] +2. Ghanshyam Thakkar [ [project](https://summerofcode.withgoogle.com/archive/2024/projects/e9C4rhrv) ] [ [final report](https://spectre10.github.io/posts/gsoc_final_report/) ] [ [blog](https://spectre10.github.io/) ] +3. Chandra Pratap [ [project](https://summerofcode.withgoogle.com/archive/2024/projects/tlh611d7) ] [ [final report](https://chand-ra.github.io/2024/08/24/GSoC-Final-Report.html) ] [ [blog](https://chand-ra.github.io/) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2024/organizations/git) +- [Rev News article](https://git.github.io/rev_news/2024/05/31/edition-111/) + +### 2023 + +1. Shuqi Liang [ [project](https://summerofcode.withgoogle.com/archive/2023/projects/Rkbc1Abe) ] [ [final report](https://cheskaqiqi.github.io/2023/08/22/Final/) ] [ [blog](https://cheskaqiqi.github.io/tags/GSoC/) ] +2. Kousik Sanagavarapu [ [project](https://summerofcode.withgoogle.com/archive/2023/projects/rck3kmq2) ] [ [final report](https://five-sh.github.io/2023/08/26/the-final-report) ] [ [blog](https://five-sh.github.io/blog) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2023/organizations/git) +- [Rev News article](https://git.github.io/rev_news/2023/06/30/edition-100/) + +### 2022 + +1. Shaoxuan Yuan [ [project](https://summerofcode.withgoogle.com/archive/2022/projects/hz4rcOUB) ] [ [final report](https://ffyuanda.github.io/blog/GSoC-final-blog/) ] [ [blog](https://ffyuanda.github.io/tags/#learn) ] +2. Abhradeep Chakraborty [ [project](https://summerofcode.withgoogle.com/archive/2022/projects/UPtA6qdf) ] [ [final report](https://medium.com/@abhra303/gsoc-final-report-feaaacfae737) ] [ [blog](https://medium.com/@abhra303) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2022/organizations/git) +- [Rev News article](https://git.github.io/rev_news/2022/06/30/edition-88/) + + +### 2021 + +1. ZheNing Hu [ [project](https://summerofcode.withgoogle.com/archive/2021/projects/5443907994779648) ] [ [final report](https://github.com/adlternative/adlternative.github.io/blob/gh-pages/blogs/gsoc/GSOC-Git-Final-Blog.md) ] [ [blog](https://github.com/adlternative/adlternative.github.io/tree/gh-pages/blogs/gsoc/) ] +2. Atharva Raykar [ [project](https://summerofcode.withgoogle.com/archive/2021/projects/5071550033690624) ] [ [final report](https://github.com/tfidfwastaken/gitnotes/blob/main/final-report.md) ] [ [blog](https://github.com/tfidfwastaken/gitnotes/tree/main) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2021/organizations/6398200235163648) +- [Rev News article](https://git.github.io/rev_news/2021/05/27/edition-75/) + + +### 2020 + +1. Shourya Shukla [ [project](https://summerofcode.withgoogle.com/archive/2020/projects/4541259818991616) ] [ [final report](https://shouryashukla.blogspot.com/2020/08/the-final-report.html) ] [ [blog](https://shouryashukla.blogspot.com/search/label/GSoC) ] +2. Abhishek Kumar [ [project](https://summerofcode.withgoogle.com/archive/2020/projects/6510085276172288) ] [ [final report](https://github.com/abhishekkumar2718/GSoC20/blob/master/README.md) ] [ [blog](https://abhishekkumar2718.github.io/gsoc/) ] +3. Hariom Verma [ [project](https://summerofcode.withgoogle.com/archive/2020/projects/6123927484497920) ] [ [final report](https://harry-hov.github.io/blogs/posts/the-final-report) ] [ [blog](https://harry-hov.github.io/blogs/posts/) ] + + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2020/organizations/5445576591671296) +- [Rev News article](https://git.github.io/rev_news/2020/05/28/edition-63/) + + +### 2019 + +1. Rohit Ashiwal [ [project](https://summerofcode.withgoogle.com/archive/2019/projects/5390155215536128) ] [ [final report](https://web.archive.org/web/20210727190950/https://rashiwal.me/2019/final-report/) ] [ [blog](https://web.archive.org/web/20210515085551/https://rashiwal.me/) ] +2. Matheus Tavares [ [project](https://summerofcode.withgoogle.com/archive/2019/projects/4787791739748352) ] [ [final report](https://matheustavares.gitlab.io/posts/gsoc-final-report) ] [ [blog](https://matheustavares.gitlab.io/tags/git/) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2019/organizations/6548634445807616) +- [Rev News - May 2019](https://git.github.io/rev_news/2019/05/22/edition-51/) + + +### 2018 + +1. Pratik Karki [ [project](https://summerofcode.withgoogle.com/archive/2018/projects/5389615745728512) ] [ [final report](https://github.com/prertik/GSoC2018?tab=readme-ov-file) ] [ [blogs](https://prertik.github.io/categories/git/) ] +2. Paul-Sebastian Ungureanu [ [project](https://summerofcode.withgoogle.com/archive/2018/projects/6700324135895040) ] [ [final report and blogs](https://github.com/ungps/gsoc2018?tab=readme-ov-file) ] +3. Alban Gruin [ [project](https://summerofcode.withgoogle.com/archive/2018/projects/6165469845258240) ] [ [final report](https://github.com/agrn/gsoc2018?tab=readme-ov-file) ] [ [blogs](https://blog.pa1ch.fr/category/gsoc-2018.html) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2018/organizations/4840889583140864) +- [Rev News - May 2018](https://git.github.io/rev_news/2018/05/16/edition-39/) + +### 2017 + +1. Prathamesh Chavan [ [project](https://summerofcode.withgoogle.com/archive/2017/projects/5434523185577984) ] [ [final report](https://docs.google.com/document/d/1RmUvJBf4x8TI71Fltg8xWP-s7zkhz3bGPyEJMgRx91Y/edit#heading=h.5r7i4cugqwi3) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2017/organizations/5061577619275776) +- [Rev News - Oct 2017](https://git.github.io/rev_news/2017/10/11/edition-32/) + +### 2016 + +1. Pranit Bauva [ [project](https://summerofcode.withgoogle.com/archive/2016/projects/5595001820020736) ] [ [final report](https://docs.google.com/document/d/1Uir0a8cRYlWANuzoU4iTDtEvPukvtTJcC_dB3KJUgqM/edit#heading=h.mipx2w79za4f) ] + +#### References + +- [GSoC archive](https://summerofcode.withgoogle.com/archive/2016/organizations/5532648021688320#projects-list) +- [Rev News - Oct 2016](https://git.github.io/rev_news/2016/09/14/edition-19/) + +### 2015 + +1. Karthik Nayak [ [project](https://www.google-melange.com/archive/gsoc/2015/orgs/git/projects/karthiknayak94.html) ] [ [fork](https://github.com/KarthikNayak/git) ] [ [a mailing list mail](https://public-inbox.org/git/553F7A50.1080907@gmail.com/) ] +2. Paul Tan [ [project](https://www.google-melange.com/archive/gsoc/2015/orgs/git/projects/pyokagan.html) ] [ [fork](https://github.com/pyokagan/git) ] [ [a mailing list mail](https://public-inbox.org/git/CACRoPnQ5_r-26J4gBHc27KZt3X9KAU7eFkA3vz_GE6_dP-Uyug@mail.gmail.com/) ] + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2015/orgs/git) +- [Rev News - May 2015](https://git.github.io/rev_news/2015/05/13/edition-3/#other-news) + +### 2014 + +1. Tanay Abhra [ [project](https://www.google-melange.com/archive/gsoc/2014/orgs/git/projects/tanayabh.html) ] +2. Fabian Ruch [ [project](https://www.google-melange.com/archive/gsoc/2014/orgs/git/projects/bafain.html) ] + + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2014/orgs/git) +- [GSoC retrospective](https://public-inbox.org/git/vpqsik1yg1l.fsf@anie.imag.fr/) + + +### 2013 + +***Did not participate*** + + +### 2012 + +1. Thomas Gummerer [ [project](https://www.google-melange.com/archive/gsoc/2012/orgs/git/projects/tgummerer.html) ] +1. Michael Schubert [ [project](https://www.google-melange.com/archive/gsoc/2012/orgs/git/projects/schu.html) ] +1. Florian Achleitner [ [project](https://www.google-melange.com/archive/gsoc/2012/orgs/git/projects/flyingflo.html) ] + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2012/orgs/git) + + +### 2011 + +1. Carlos Martín Nieto [ [project](https://www.google-melange.com/archive/gsoc/2011/orgs/git/projects/carlosmn.html) ] +1. Ramkumar Ramachandra [ [project](https://www.google-melange.com/archive/gsoc/2011/orgs/git/projects/artagnon.html) ] +1. Fredrik Gustafsson [ [project](https://www.google-melange.com/archive/gsoc/2011/orgs/git/projects/iveqy.html) ] + + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2011/orgs/git) + + +### 2010 + +1. Vicent Marti [ [project](https://www.google-melange.com/archive/gsoc/2010/orgs/git/projects/tanoku.html) ] +1. Ramkumar Ramachandra [ [project](https://www.google-melange.com/archive/gsoc/2010/orgs/git/projects/artagnon.html) ] +1. Bo Yang [ [project](https://www.google-melange.com/archive/gsoc/2010/orgs/git/projects/struggleyb.html) ] + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2010/orgs/git) + +### 2009 + +1. Nick Edelen [ [project](https://www.google-melange.com/archive/gsoc/2009/orgs/git/projects/sirnot.html) ] + +#### References + +- [GSoC archive](https://www.google-melange.com/archive/gsoc/2009/orgs/git) + + +### 2008 + +1. Joshua Roys (_project_: GitTorrent) [ [final e-mail](https://lore.kernel.org/git/48C05FB5.3010901@gmail.com/) ] +2. Sverre Rabbelier (_project_: git-statistics) [ [final e-mail](https://lore.kernel.org/git/bd6139dc0809041544o427356c9i40a28b1c182817eb@mail.gmail.com/) ] +3. Lea Wiemann (_project_: Gitweb caching) [ [idea discussion](https://lore.kernel.org/git/483C4CFF.2070101@gmail.com/#t) ] +4. Marek Zawirski (_project_: Eclipse plugin push support) [ [final e-mail](https://lore.kernel.org/git/48C564ED.7050402@gmail.com/) ] +5. Miklos Vajna (_project_: git-merge builtin) [ [final e-mail](https://lore.kernel.org/git/20080904225559.GP16514@genesis.frugalware.org/) ] +6. Stephan Beyer (_project_: git-sequencer) [ [final e-mail](https://lore.kernel.org/git/20080904223653.GA15170@leksak.fem-net/) ] + +#### References + +- [GSoC archive](https://developers.google.com/open-source/gsoc/2008?csw=1#git-development-community) +- [Mail about GSoC participant summary](https://lore.kernel.org/git/200809042315.58898.jnareb@gmail.com/) +- [GSoC selection summary](https://lore.kernel.org/git/20080422013201.GA4828@spearce.org/) + + +### 2007 + +1. Carlos Rica (_project_: Shell script to C builtin conversions) +2. Luiz Capitulino (_project_: Libification) + +#### References + +- [GSoC archive](https://developers.google.com/open-source/gsoc/2007?csw=1#git-development-community) +- [GSoC report](https://lore.kernel.org/git/20070903034201.GP18160@spearce.org/) diff --git a/Gemfile b/Gemfile index a7bf33a1b8..3cc8ef00a1 100644 --- a/Gemfile +++ b/Gemfile @@ -2,3 +2,7 @@ source 'https://rubygems.org' # Because https://help.github.com/articles/using-jekyll-with-pages/ gem 'github-pages', group: :jekyll_plugins + +# gem "webrick", "~> 1.7" # N.B. we may not want to fix this Gemfile to Ruby 3 +gem "webrick" +gem 'jekyll-redirect-from' \ No newline at end of file diff --git a/General-Application-Information.md b/General-Application-Information.md new file mode 100644 index 0000000000..7a2402b95d --- /dev/null +++ b/General-Application-Information.md @@ -0,0 +1,359 @@ +--- +layout: default +title: General Application Information +--- + +This is the page where people who want to apply to the Git project for +the Google Summer of Code (GSoC), Outreachy, or other such mentoring +programs can get information about what the Git project would like to +see in an application. + +*Please read this page completely before focusing on a project or a + microproject ideas, or microproject general information. + Specifically, also read the "AI guidelines" section to know our + stance regarding the usage of AI tools.* + + +## Microproject (required) + +It is required that applicants who want to apply to the Git +project for the GSoC or Outreachy complete a tiny, code-related +"microproject" as part of their application. Please refer to our +[general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information) +for more information. Completing a microproject is not only an important +way for us to get experience with applicants, but it will also help +applicants become familiar with Git's development and submission +process. + +## Reviewing (not required but appreciated) + +Also, working in Git project is not only about writing your own +patches. Constructively critiquing design and implementation of +patches by other people is also an important skill you need to learn +in order to effectively collaborate with others. So, if you have time +and inclination, it would be beneficial to read and understand other +applicants' patches (or any other patch submitted to the mailing-list), +think if you agree that the problem they are trying to solve is worth +solving, the approach they are taking is the best way (or if you think +of a better way to solve it), etc., and respond to their patches with +the result of your thinking as a review. + +## Application (required) + +A complete application should include a presentation of yourself +(include any argument that may convince mentors that you are able to +complete the project) and detailed explanations about your +project. See also the "Note about giving back and mentoring" below. + +Project ideas are just ... ideas! The list we provide is not +exhaustive, and more importantly each idea only includes a summary of +what is to be done. An application must include detailed plans on the +design, timeline ... A typical application takes several pages. + +If you are applying for the GSoC, you should already have read +[the GSoC Contributor Guide](https://google.github.io/gsocguides/student/writing-a-proposal) +by now, but re-read it if needed. + +If you are applying for Outreachy there is very likely similar +documentation on their web site that you should follow. + +Please, include link(s) to the mailing-list discussion(s) related to +your microproject in your application (e.g. linking to +[lore.kernel.org](https://lore.kernel.org/git/)). If you participate +in the review of other patches, then you may also include links to +discussions that would support your application. Please also describe +the status of the patches you have sent and maybe reviewed: Have they +been merged already in an official branch maintained by Junio? What +does [Junio's "What's cooking in git.git" emails](https://lore.kernel.org/git/?q=s%3A%22What%27s+cooking+in+git.git%22) +say about it? In general it's a good idea to describe all your Git +related work so far with a good amount of detail. + +If the mentoring program allows different project "sizes", like for +example 'Small', 'Medium' and 'Large', or different project +"duration", like from 12 weeks to 22 weeks, please tell us in you +application which project size or duration you prefer. It's usually +not difficult for us to adapt a project we propose to different sizes +or durations. + +Applicants must send drafts of their proposal on the mailing-list +before submitting it officially to GSoC or Outreachy to get feedback +from the community. They are strongly encouraged to publish a draft on +the official GSoC or Outreachy website *and* post it to the mailing +list for discussion. + +Getting your proposal right can follow the same process as usual patch +submission for Git, as described in the +[microprojects](https://git.github.io/General-Microproject-Information) page and +in `Documentation/SubmittingPatches` in Git's source code. It is also +expected that you will send several versions of your draft, responding +to comments on the list. Please plan to send the first draft early +enough so that a number of reviews and improvements cycles can happen. + +If you are not sure about your proposal, you can discuss that in the +same email where you introduce yourself or in separate emails. Please +use "[GSoC]" or "[Outreachy]" at the beginning of the subject of such +emails. + +## Summary + +In summary, all applicants must (not necessarily in this order): + +* Complete a [microproject](https://git.github.io/General-Microproject-Information). + +* Write a detailed application explaining their project. + +* Discuss their project by posting drafts of their application on the + mailing-list long before the deadline. See the "Note about getting + involved early" below. + +In your application, and in the discussions related to projects you +are interested in, it is a good idea to: + +* Include link(s) to the mailing-list discussion(s) related to the + project you chose in your application or you are interested in, for + example previous discussions or patch series about the topic. There + might be interesting discussions about the topics that are several + year old. It is also a good idea to summarize them. + +* Include link(s) to the mailing-list discussion(s) related to the + previous drafts of your application itself. + +* Include link(s) to the mailing-list discussion(s) related to your + microproject. If your microproject patches have been merged, please + give the merge commits. Otherwise give their branch names and + current status in the last "What's cooking in git.git" email from + Junio. + +* Include what is suggested in + [the GSoC Contributor Guide](https://google.github.io/gsocguides/student/writing-a-proposal) + or the equivalent guidelines for Outreachy. + +([lore.kernel.org](https://lore.kernel.org/git/) can be +used for searching the mailing list and linking to previous +discussions.) + +## AI guidelines + +The use of Artificial Intelligence related tools ("AI" or "AIs" for +short), like Large Language Models ("LLMs"), by developers is becoming +more and more popular, but that's not a reason to blindly use them, +especially when working on the Git project. + +### Legal issues + +In general, it's not clear if AI generated code or documentation are +acceptable in the Git project. Authors contributing to Git are +required to "sign off" the patches they contribute, and to agree with +the Developer’s Certificate of Origin, also called DCO, (see +), while the DCO +says basically that authors of a patch should be sure about the origin +of its content. + +As we cannot usually be sure how AIs have been trained and that they +are not just repeating proprietary existing code or documentation they +saw during their training, we cannot accept much AI generated code or +documentation in general. Now, if it's only a few lines to fix a bug +or to implement a common pattern or summarize something, and if that +looks specific enough to a current concrete problem a developer is +working on, that might be OK. + +Anyway as the situation is not clear for the Git project and probably +many other open source projects, you should be very prudent regarding +this. + +### Be very careful with AI output + +For a number of reasons, not just legal ones, developers should really +make sure that they treat what AIs produce very carefully. They +should: + + - triple check everything, especially regarding our guidelines + (indent, style, commit message guidelines, etc, see especially the + SubmittingPatches and CodingGuidelines docs as well as the other + pages on this website) and the feedback reviewers already gave + them or others, + + - build and test changes, using existing, new or manual tests, to + check that the changes are correct, perform well and don't produce + garbage output, + + - doubt anything they don't fully understand, or anything that might + not match our guidelines or feedback, and + + - fix, simplify, adapt, reword or change anything that is + suspicious, bloated, too formal, or that they don't understand, or + that doesn't match our guidelines or our feedback. + +Yeah, AIs still often hallucinate or just produce bad code, commit +messages, documentation or output, even when you point out their +mistakes. + +### We don't accept AI output as-is + +It's unacceptable to send us something that is obvious AI slop, or +that sounds overly formal or bloated, or that looks good on the +surface but makes no sense, or that senders don’t understand or cannot +explain. It just wastes our time and we cannot accept it. We want to +interact with and mentor humans, not AIs. + +For example, it's unacceptable to have an AI generate a commit message +where it just describes what the code in the commit does, instead of +the purpose of the change, and then send that to us. + +In general, it's unacceptable to send AI-generated patches or messages +as-is to the mailing list or to mentors' or developers' personal email +addresses. We won't consider candidates doing that. + +For another, unfortunately common, example, it's unacceptable to send +us an application that has obviously been AI generated and doesn't +follow our guidelines or the feedback we previously gave to other +applicants. Those applications will be dropped. + +### Blindly using AI is far worse than not applying + +As bad AI use is growing in general, not just to apply to mentoring +programs, more and more tools and ways are being developed to find out +and fight against bad AI use. + +So people who apply by sending us AI generated output as-is, not only +waste their time, and our time, for no result, but they also leave +evidence on our mailing list archive of their bad behavior. + +For example, employers already use social media screening tools or +candidate assessment software when hiring people, and it's likely that +those tools, which often already use AI, are, or will be able to find +out soon about such bad behavior. + +### Better ways to use AIs + +Developers would often likely get better results, learn more and have +a better overall experience by asking AIs to only explain things, and +guide them step by step towards producing a solution by themselves, +rather than by asking for a full solution that they would then mostly +copy-paste. + +They can also use AIs to help with debugging, or with checking for +obvious mistakes, things that can be improved, things that don't match +our style, guidelines or our feedback, before sending it to us. + +## Note about the number of slots + +The Git organization usually has very limited mentoring capacity. +These days we usually accept between around 1 to 3 GSoC contributors +(in the Summer) or Outreachy interns (in the Winter). + +## Note about giving back and mentoring + +We appreciate very much GSoC contributors and Outreachy interns who +stay around after the mentoring period is over. It is very nice to see +them on the mailing list, even if they don't contribute much. It's of +course better when they continue to contribute though, even by just +reviewing a patch from time to time. + +Some people have been around for more than 10 years, others have +become regular contributors and that's great! + +One very nice way to contribute and to give back is to mentor or +co-mentor other contributors or interns coming after you. It helps +create more opportunities for more contributors and interns like you, +as mentoring capacity is the main factor preventing us from accepting +more contributors and interns. If each contributor or intern accepted +to co-mentor twice (for example once in the Summer and once in the +Winter) just after they have been mentored, our mentoring capacity +could increase significantly each year. + +Even though successful former contributors/interns usually have +adequate technical ability to be a successful mentor, unfortunately +few of them have been willing to just co-mentor once along with an +experienced mentor. + +Other free or open source projects have done better than us on +this. At the Google Summer of Code Mentor Summit for example, more +than 30% of the mentors are usually former contributors. + +Here is a quote by a mentor (Carlos Fernandez Sanz) on the GSoC +Mentors List, that describes very well how we see GSoC and Outreachy: + +"GSoC is (for us, anyway) more about growing the community than +getting stuff done. If they don't stick around their value diminishes +a lot, even if they do a great job [...]. The [contributors] that did +a great job but completely left the community [...] are just a +memory... the ones that have been with us and that are now mentors +[...], long after they participated in GSoC, are the ones we love :-)" + +Consider showing us in your application previous mentoring, giving +back and community activities that you have done, especially related +to free or open source software. + +## Note about refactoring projects versus projects that implement new features + +Over the years we have been favoring refactoring projects over +possibly more interesting projects that implement new features. +Refactoring projects are usually easier to do step by step, and to get +code merged step by step which is encouraging. + +In general refactoring projects are worthwhile to do even if the +project is not finished at the end of the GSoC and even if the +contributor or intern stops contributing after that. In those cases it +is often a good idea to later finish the refactoring either by +ourselves or by proposing it to another GSoC contributor or Outreachy +intern. This way the work of contributors, interns and mentors is not +likely to be wasted. + +With a project that implements a feature, there is a risk, if it's too +complex or too difficult, that the feature will not be finished and +that nothing, or nearly nothing, will have been merged during the GSoC +or Outreachy internship. There is also the risk that another way to +implement the feature will appear later in the GSoC or Outreachy +internship, and all, or nearly all, the work of the contributor or +intern and mentors will have been mostly wasted. It could also appear +that the use cases the feature was envisioned to be used in, are +better addressed by other improvements or a different workflow. + +Another potential issue is that a new feature might be prone to naming +or user interface discussions which could last for a long time or +could not result in clear decisions. + +Therefore we think that we should be very careful before proposing to +an applicant, or accepting, a project that implements a new feature. +People suggesting such a project should at least carefully consider +the above potential issues and see if they can be mitigated before the +project is submitted. + +As [suggested by Google](https://google.github.io/gsocguides/mentor/defining-a-project-ideas-list) +(but this is true for Outreachy internships too), we emphasize that an +applicant proposing something original must engage with the community +strongly before and during the application period to get feedback and +guidance to improve the proposal and avoid the above potential issues. + +## Note about getting involved early + +The process of reviewing microproject patches and applications on the +mailing list can take a lot of time. Depending on your experience and +the tools you are already familiar with or not, it can also take some +time to set up and get used to properly sending emails and patches to +the mailing list, interacting with people on the mailing list, reading +the documentation, getting used to the code base, etc. That's why we +strongly suggest getting involved very early, like several months, +before the deadline. + +The more we can see that you invest in learning and participating in +Git's development, the more we can be confident that you are motivated +and will likely stay in the community. + +This doesn't necessarily mean that you have no chance at all of +getting accepted if you get involved quite late. It depends on how +other applicants are doing and how many available mentors we have or +can find. But anyway you start with a significant handicap compared to +other applicants who got involved early. + +It might therefore be a good idea to find a project idea that is not +yet being pursued by an applicant who started getting involved much +earlier than you. This means that you might have to find a project +idea that we haven't proposed in our idea list. + +The good side of this is that this project idea along with your +enthusiasm for it and the skills you show might encourage Git +developers to mentor you even if they weren't planning to mentor in +the first place. It could also happen that someone, who was only +planning to co-mentor, could agree to fully mentor you alone. diff --git a/General-Microproject-Information.md b/General-Microproject-Information.md new file mode 100644 index 0000000000..c98caeab81 --- /dev/null +++ b/General-Microproject-Information.md @@ -0,0 +1,596 @@ +--- +layout: default +title: General Microproject Information +--- + +## Introduction + +It is strongly recommended that people who want to apply to the Git +project for the Google Summer of Code (GSoC), Outreachy, or other such +mentoring programs, called "applicants" in this document, submit a +small code-related patch to the Git project as part of their +application. We call the whole process of submitting such a small +code-related patch a "microproject". + +People who want to get involved in Git development outside mentoring +programs can also benefit from information on this page to get +started, though it might be a bit less relevant to them. If they want, +they can use something like "[FirstTimer]", "[Newbie]", "[Newcomer]" +instead of "[GSoC]" or "[Outreachy]" in the emails they send. + +Anyway if you want to work on a microproject, or more generally if you +want to start getting involved in Git development, please read on +*all* the rest of this page. + +## What is a microproject? + +Think of these microprojects as the "Hello, world" of getting involved +with the Git project; the coding aspect of the change can be almost +trivial, but to make the change the applicant has to become familiar +with many of the practical aspects of working on the Git project. + +Git development is based on sending successive versions of patches or +patch series to the mailing list until they are considered good and +correct by the reviewers and Junio Hamano, the maintainer, who will +merge them. This process usually takes quite some time. By sending +drafts of your microproject patches to the mailing list long before +the deadline, you can show us that you are willing and able to work +well using the Git development process. + +It is *expected* that what you send will need several rounds of +reviews and discussions. If you are not sure at all about a patch you +can mark it as RFC in the subject. See [section below](#use-a-tag-like-gsoc-outreachy-etc-in-your-subject) +about how to mark patches as RFC. + +Consider [a sample email thread](https://public-inbox.org/git/1386590745-4412-1-git-send-email-t.gummerer@gmail.com/T/#u), +which shows how a developer proposed a change and a patch to implement +it. The problem being solved, the design of the proposed solution, +and the implementation of that design were all reviewed and discussed, +and after several iterations an improved version of the patch was +accepted into our codebase. As a GSoC contributor, or Outreachy intern, +you will be playing the role of the developer and engaging in a +similar discussion. Get familiar with the flow, need for clarity on +both sides (i.e. you need to clearly explain your design, and need to +ask for clarifications when questions/suggestions you are offered are +not clear enough), the pace at which the discussion takes place, and +the general tone of the discussion, to learn what is expected of you. + +## Summary of the steps needed to complete a microproject + +To complete a microproject, you will have to go through approximately +the following steps: + +* Download the source code: clone the repository using the + [Git via Git](https://git-scm.com/downloads) instructions and read + the `README` file. + +* Build the source code: this is described in the file `INSTALL`. + +* Glance over our coding guidelines in the file + `Documentation/CodingGuidelines`. We take things like proper code + formatting very seriously. + +* Read about the process for submitting patches to Git: this is + described in `Documentation/SubmittingPatches`. A more detailed + step-by-step guide could be found in [`Documentation/MyFirstContribution.txt`](https://git-scm.com/docs/MyFirstContribution). + +* The "[Hacking Git](/Hacking-Git/)" page + could also serve as a handy resource. It points to resources + on various topics related to working on Git. + +* Select a microproject and check that it has not yet been taken or + discussed by searching the mailing list. Please read all the + sections below related to finding or selecting a microproject. + +* Send an email to the mailing list where you describe the + microproject you want to work on, the way you want to do it, and + maybe talk a bit about yourself. Make sure the email you send has a + subject that starts with "[GSoC]" or "[Outreachy]". + +* **Make the actual change.** (Funny, this is the only part they teach + you about in college.) + +* Run the test suite and make sure it passes 100%: this is described + in the file `t/README`. (If you have added new functionality, you + should also add new tests, but most microprojects will not add new + functionality.) + +* Commit your change. Surprise: we use Git for that, so you will need + to gain at least + [a basic familiarity](https://git-scm.com/docs) with using + Git. Make sure to write a good commit message that explains the + reason for the change and any ramifications. You can find information + on writing a good commit message in the + ["Describe your changes well" section of the `SubmittingPatches` document](https://git-scm.com/docs/SubmittingPatches#describe-changes). + Remember to make sure + that you agree with our "Developer's Certificate of Origin" (whose + text is contained in `Documentation/SubmittingPatches`), and to + signify your agreement by adding a `Signed-off-by` line. Instructions + on how to add the sign-off is covered in the `SubmittingPatches` + document. + +* *Optional, but recommended:* + + With an account at GitHub or GitLab, you can use the CI to test your changes + on Linux, Mac and Windows. See + [GitHub exmamples](https://github.com/git/git/actions/workflows/main.yml), [GitLab examples](https://gitlab.com/git-scm/git/-/pipelines) of recent CI runs. + + To run these tests against your own branch: + * **GitHub**: [create a fork](https://help.github.com/articles/fork-a-repo/) of [Git](https://github.com/git/git) on GitHub and switch to it. At the + top bar select [Actions tab](https://github.com/git/git/actions) + and perform the initial setup to enable it for your fork. After enabling it, + CI will run for a specific branch of your fork whenever you push new changes + to it in GitHub. You can monitor the test state of all your branches in the + same [Actions tab](https://github.com/git/git/actions) of your fork. + * **GitLab**: [create a fork](https://docs.gitlab.com/user/project/repository/forking_workflow/#create-a-fork) of [Git](https://gitlab.com/git-scm/git) on GitLab and switch to it. CI will run for a specific branch of your fork whenever you push new changes + to it in GitHub. You can monitor the test state of all your branches in the [Build > Pipeline](https://gitlab.com/git-scm/git/-/pipelines) section of your fork. + + If a branch did not pass all test cases then it is marked with a red cross. In + that case you can click on the failing job and navigate to + `ci/run-build-and-tests.sh` and/or \ + `ci/print-test-failures.sh`. You can also + download "Artifacts" which are tarred (or zipped) archives with test data + relevant for debugging. Fix the problem and push your fix to your fork. + This will trigger a new CI build. Ensure all tests pass. + +* Submit your change to the Git mailing list. For this step you + probably want to use the commands `git format-patch` and `git + send-email`. Make sure that your email is formatted correctly: send + a test version of the email to yourself and see if you can apply it + to your repository using `git am`. Alternatively you may use + [GitGitGadget](https://gitgitgadget.github.io/) or + [submitGit](https://submitgit.herokuapp.com/). + + When you submit your patch, please mention that you plan to apply + for the GSoC or Outreachy. You can use "[GSoC PATCH ...]" or + "[Outreachy PATCH ...]" in the subject of the emails you send for + that purpose. This will ensure that we take special care not to + overlook your application among the large pile of others. + +* Expect feedback, criticism, suggestions, etc. from the mailing list. + + *Respond to it!* and follow up with improved versions of your + change. Even for a trivial patch you shouldn't be surprised if it + takes two or more iterations before your patch is accepted. *This + is the best part of participating in the Git community; it is your + chance to get personalized instruction from very experienced peers!* + +The coding part of the microproject should be very small (say, 10-30 +minutes). We don't require that your patch be accepted into the +"master" branch by the time of your formal application; we mostly want +to see that you have a basic level of competence and especially the +ability to interact with the other Git developers. + +## Only ONE quality focused microproject per applicant + +Applicants please attempt only **ONE** microproject. We want quality, +not quantity! (Also, it takes work to collect the ideas, and it would +be nice to have enough microprojects for everybody.) + +### Change only a few files + +This means that for a microproject that consists in refactoring or +rewriting a small amount of code, your patch should change only +**ONE** file, or perhaps 2 files if they are closely related, like +"foo.c" and "foo.h". + +If you change a test file, the title of your patch (after the +"[GSoC PATCH ...]" or "[Outreachy PATCH ...]" part) should start +with "tXXXX: " where tXXXX is the start of the filename of the test +script you change. If you change "foo.c" or "foo.h", the title of your +patch should probably start with "foo: ". + +If you create a function to refactor existing code, it's possible that +more files would be changed, but the changes should be trivial in most +of them. + +### Research existing related work + +In general it's a good idea to check on the mailing list archive +([lore.kernel.org](https://lore.kernel.org/git/) and +[Public Inbox](https://public-inbox.org/git/) are your friends) what +other GSoC or Outreachy applicants attempting a microproject have +already been told this year or any previous year, as hopefully it will +help you avoid some mistakes. As some microproject ideas haven't +changed for years, some similar microprojects might have been +attempted many times already and you can learn a lot from these +attempts. + +The more you research your microproject and take advantage of that, +the more confident we can be that you will be able to solve many +problems when working on your real GSoC or Outreachy project. So it's +a very good thing to show that you have researched your microproject +and taken into account what you have found. + +### After it's done, work on different things + +If you've already done a microproject and are itching to do more, then +get involved in other ways, like finding and fixing other problems in +the code, or improving the documentation or code comments, or helping +to review other people's patches on the mailing list, or answering +questions on the mailing list or in IRC, or writing new tests, etc., +etc. In short, start doing things that other Git developers do! +Alternatively you can of course focus on your project proposal. + +## Be very careful when using AI tools + +There is an "AI guidelines" section on our +General-Application-Information page: + +https://git.github.io/General-Application-Information/ + +Please read it and make sure you use AI very carefully. + +## How to find ideas for microprojects + +First check the specific page(s) or information about Git +microprojects related to your program that should have been published +on this site or on the GSoC or Outreachy site. But then still read on +everything below! + +It's also possible that we haven't taken the time to put up a page +listing microprojects ideas for your program. The pages we used to +create for that were named "XXXX Applicant Microprojects" where XXXX +is the program name and a date, for example "SoC 2016 Applicant +Microprojects" for the GSoC in 2016, or "Outreachy Winter 2021-2022 +Applicant Microprojects" for Outreachy in 2021-2022. See the following +directory to find these old pages that might still be useful: + +https://git.github.io/Historical-SoC-Outreachy/ + +Any small code-related change would be suitable for a +microproject. Just remember to keep the change small! It is much +better for you to finish a small but complete change than to try +something too ambitious and not get it done. + +Though we don't require that your patch be accepted into the "master" +branch by the time of your formal application, we still expect that a +good number of iterations between discussions and improvements has +happened. Don't be surprised if we reject your application after you +send something out of the blue just before the deadline, even if what +you did is very significant and/or of high quality! + +If you don't like for some reason the microprojects that are proposed +related to your program, or if you just want more choice, you may find +other ideas for microprojects by searching the mailing list +() or the code base itself. In the code +base you could search the code itself or the tests (in the "t" +directory). + +When you find something you are interested to work on, please ask +first on the mailing list if it's worth doing and if it's appropriate +for a microproject before starting to work on what you find. Even if +it looks straightforward, there could be hidden reasons why it is too +difficult or just inappropriate. + +You can also always send an email to the mailing list to ask if people +have other microproject ideas, but before that please check that +someone participating in the same program as you has not already done +that recently. + +### Searching for bug reports + +Git has no official bug tracker or bug list. On + we recommend that people report bugs +directly on the Git mailing list. + +On the mailing list people sending bug reports are likely to use +things like "[BUG]", "bug", "issue" or "crash" in the subject of their +emails. So it can be a good idea to search for that. + +Most bugs are usually fixed soon after they are reported or are well +known behaviors or limitations though. So don't expect too much. + +[GitGitGadget](https://gitgitgadget.github.io/), which can be used to +send patches from a GitHub repository to the Git mailing list, has its +own list of Git issues on: + + + +There are even a couple ideas marked as #leftoverbits, i.e. curated +and copied from the Git mailing list see: + + + +And there are a couple of project ideas marked as "good first issue": + + + +that might be interesting to look at. + +There is another non official bug tracker dedicated to Git issues on: + + + +Git for Windows also has it's own issue tracker: + + + +But of course the Git for Windows issues might not apply to Git +itself. Please check that before talking about them on the Git mailing +list. + +In general it's a very good idea to check that you can reproduce the +bug on the latest version of Git before working on it. + +Also some bugs are difficult to understand and require too much or too +difficult work for a microproject, so don't spend too much time on +them if it appears that they might not be simple to fix, and don't +hesitate to ask on the mailing list if they are a good microproject. + +### Searching for #leftoverbits in the mailing list + +People have recently started to add "#leftoverbits" to their emails +when they think further small work on the topic could be useful. + +You can easily search that using: + + + +But don't forget to search to check if what you find has already been +addressed. If it has not been addressed, please ask first on the +mailing list if it's a good idea to work on that. + +As for bugs, and many things really, you can also ask if you are not +sure it's simple enough to fix. + +### Searching the code base itself + +Your best bet is probably to search for strings like "FIXME", "TODO", +"NEEDSWORK", or maybe "NEED-WORK", and "BUG" (though not the "BUG()" +macro). + +You can also search (`git grep` is your friend) for common patterns in +the code and try to find or create a function to refactor them. + +### Searching the tests + +Tests are in the "t" directory and can be run by launching "make" in +this directory. Doing that you will see that there are a number of +tests that are marked with "# TODO known breakage", like for example: + +"not ok 28 - git checkout -f: replace submodule with a directory must fail # TODO known breakage + +These tests start with "test_expect_failure" instead of +"test_expect_success". They document that something is not working as +it should perhaps be working. And it might be an interesting +microproject to fix that. + +Note that it is especially wise to first search the mailing list and +then ask on the list before working on one of these +"test_expect_failure", because if we bothered to document a failure +but not fix it, that is often because the fix is non-trivial. + +You could also check if some commands have no test for some of their +options and it could be an interesting microproject to add a test for +one of those options. + +### Searching the mailing list for other ideas + +You can search the mailing list for words like "low hanging fruit", or +"low-hanging fruits", "hint, hint", "later", "we should", "I plan +to"... + +## How to introduce yourself to the community + +It's likely that you will introduce yourself to the community around +the same time you are going to start working on a micro-project. + +### Tell us about you, or not + +We don't require you to send us a special introductory email or to +tell us about your skills, interests, experience, background, +etc. Feel free to tell us what you want about yourself if you wish +though. + +Make sure to specify your mentoring program clearly as +[suggested below](#use-a-tag-like-gsoc-outreachy-etc-in-your-subject). + +### Thoroughly check your eligibility in the program + +Before you introduce yourself, it's very important that you thoroughly +check as soon as possible that you are eligible for the mentoring +program you are interested in. + +This is especially important for Outreachy, which has strict rules and +is enforcing them. Their rules are available on: + +https://www.outreachy.org/docs/applicant/#eligibility + +Especially if you are a student, please check the section about the +rules for students, and especially check this one: + +"University students must have 42 consecutive days free from school +and exams during the internship period." + +The Outreachy organizers will check this rule with your university. +They will disqualify you if there is any requirement, especially this +one, that you don't meet. + +If you start applying to the Git project, this will deter others from +applying. We usually have very few projects and can only accept very +few applicants. So if others want to apply, they know they will have +to compete with you and possibly others, and they might prefer to find +another project with less competition. + +It happened recently that only two people applied for a project we +proposed, and both were later found to not be eligible because of +their university requirements. So in the end, we couldn't mentor +anyone for the project we proposed, which is bad for everyone. + +So please thoroughly check your eligibility before introducing +yourself, and please confirm in your introduction that you have +checked all the requirements and that you indeed meet them all. + +### Don't ask us to find a micro-project for you + +As we usually don't know your interests, skills, experience, +background, etc, it's hard for us to select a micro-project for +you, and it's part of your job as an applicant to research a good +micro-project for you. It will show us that you will be able to +select a good project for you and properly research it. + +### Do ask for help, but be specific + +You can ask for help if there are things you don't understand in a +micro-project description, or if you have some trouble working on your +micro-project or even finding a micro-project. But please be very +specific in your questions and tell us in detail what you searched or +tried, what you expected and what didn't work as you +expected. Something like "I couldn't find a good micro-project for +me", for example, doesn't tell us much, and doesn't give us any idea +about how we could help you. + +## Why it's better to introduce yourself by directly emailing the mailing list + +We understand that some people are a bit shy or reluctant to email the +mailing list directly and interact with people there, but that's +something that is required to contribute to Git. So you will have to +do it at one point anyway. + +Also please understand that there are often a significant number of +people interested in participating in programs like GSoC or Outreachy, +and mentors prefer to answer questions once and for all on the mailing +list instead of many times privately to everyone interested in +participating. + +Emailing mentors privately will not give you any advantage. On the +contrary it might just signal potential mentors that you are not very +willing to interact with the mailing list. It will also increase the +workload of mentors for possibly no good reason which is not something +they like. + +Mentors will be willing to properly mentor those who have been +selected to participate in the mentoring program, but until then they +cannot, and don't want to, privately mentor several people to help +them be selected. It wouldn't be fair to those who are doing the right +thing and interacting with the mailing list directly. + +## Some conventions and tips + +It can be intimidating to introduce yourself or send your first patch +to the mailing list, but we hope that the following conventions and +tips will help you get properly started. + +### Start your own email thread + +When you introduce yourself to the Git mailing list, please start your +own email thread instead of replying to a thread where someone else +introduced themself, or worse a completely unrelated thread. + +### Use a tag, like [GSoC], [Outreachy], etc, in your subject + +Yeah, we insist on this because many applicants don't do it despite +the fact that it helps everyone, especially themselves. + +It helps because efficiently searching the mailing list is not so +easy. Having such a tag at the start in the subject makes it much +easier to find what applicants or contributors from a program have +done. And applicants should be very interested in searching for what +other applicants or contributors participating in GSoC or Outreachy +have been doing in the past, for example what kind of microproject +they have chosen, how their proposal looked like, etc. + +If you're using `format-patch` for sending your patches to the mailing list, +you can add this tag as follows: + +``` +git format-patch --subject-prefix='GSoC PATCH' + +(or) + +git format-patch --subject-prefix='Outreachy PATCH' +``` + +If you want to mark your patch as RFC, use + +``` +git format-patch --rfc --subject-prefix='GSoC PATCH' + +(or) + +git format-patch --rfc --subject-prefix='Outreachy PATCH' +``` + +### Reply inline + +Many people these days use the "top posting" posting style, but we +usually reply inline instead, which is also called the "interleaved +posting" posting style. See +https://en.wikipedia.org/wiki/Posting_style for more information about +these styles. + +So please don't just reply on top of the email you are replying +to. Instead, just expand the email you are replying to and put your +comments in it. + +### Put ALL the co-mentors in To: or Cc: + +When emailing about something related to your program (GSoC or +Outreachy or ...) and when you know who are your possible +(co-)mentors, put them all in To: or Cc:. If you email or reply and +forget to put one of your (possible) co-mentors in the loop, it can +only create confusion or additional useless synchronization work for +your mentors and ultimately make it harder for them to help you. + +If you have something personal to say to only one of your mentors, +it's Ok to not put others in To: or Cc:, but otherwise, please, make +it a habit to put them all in the loop when you contact them. + +Tip: just use "Reply-all" when you reply to an email. + +### Don't be formal + +We are used to not using titles, like "Sir", "Mr", etc, and not being +formal. Yeah, it can be difficult, as in some areas or countries, +people are supposed to be formal with mentors, professors or people +older or more experienced than themself. But please try to be as +informal as us. + +### Tell us your first name or how you want to be called + +Most people on the mailing list like to call each other and to be +called using their first name, or sometimes a nickname. So that's how +we would like to call you. So let us know your firstname or how you +want to be called. + +Yeah, sometimes it seems obvious, but sometimes it's really not, as +for example in some countries people commonly have 4 different names, +in others they usually mention their first name after their last name +(instead of before), in yet others, first names are usually +abbreviated in non obvious ways, etc. + +So please make it clear. + +### Tell us the pronouns we should use + +Again, yeah, it's often obvious, but often it's not. So please tell us +if we should use "He/him/his", "She/her/her(s)", "They/them/their(s)", +or another pronoun to talk about you. + +### Confirm that you pass the requirements + +Programs like Outreachy or GSoC usually have requirements for +applicants. Sometimes applicants have to be accepted by the program +organizers after they have shown they satisfy the requirements. + +In any case it's interesting for us and others to know soon how you +currently stand regarding the requirements and maybe the acceptance +process. + +See also the "Thoroughly check your eligibility in the program" +section above. + +### Tell us what steps you have already taken + +We can better help you and suggest the next steps for you to take if +we know what steps you have already taken. + +So if you have read this documentation, tell us. If you have already +started or finished a Git tutorial, tell us too. If you have only +built Git from source, tell us. If you have already sent patches on +the Git mailing list to improve Git, tell us. + +We don't need to know about the computer science knowledge or C or +shell language programming experience you have, but telling us where +you are regarding developing Git is definitively helpful. diff --git a/Hacking-Git.md b/Hacking-Git.md new file mode 100644 index 0000000000..7dd16d6658 --- /dev/null +++ b/Hacking-Git.md @@ -0,0 +1,146 @@ +--- +layout: default +title: Hacking Git +--- + +The goal of this document is not to be a tutorial, but rather to point +to interesting material that has already been written. + +The goal is also not to list all the articles, tools or resources +about Git or its internals. There are a lot of good resources, +including [free books](http://git-scm.com/book/en/v2/), and the +[archive of our newsletter](https://git.github.io/rev_news/archive/), +about that elsewhere. So on this page we focus on what is the most +interesting for developers starting to work on Git. + +Contributions are welcome though! Please contact us on the Git Mailing +list (at [git@vger.kernel.org](mailto:git@vger.kernel.org)) or open an +issue or a pull request on our +[GitHub repo](https://github.com/git/git.github.io/) to discuss or +suggest improvements. Thanks! + +## Building Git + +* ["`INSTALL`"](https://github.com/git/git/blob/master/INSTALL) to build using [Make](https://www.gnu.org/software/make/). + +* ["`meson.build`"](https://github.com/git/git/blob/master/meson.build) to build using [Meson](https://mesonbuild.com/). + +* ["Installing from Source"](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#_installing_from_source) in the Pro Git book + +* [The top of the Makefile](https://github.com/git/git/blob/master/Makefile), for special "Makefile knobs" + +## Understanding the Git code base + +* ["A birds-eye view of Git’s source code"](https://git-scm.com/docs/user-manual#birdview-on-the-source-code) in the Git User’s Manual + +* [Fabien Sanglar's Git Source Code Review](https://fabiensanglard.net/git_code_review/architecture.php) + +* [DeepWiki git/git, an AI generated introduction level overview](https://deepwiki.com/git/git) + +* [Boost Your Programming Skills by Reading Git's Code](https://www.freecodecamp.org/news/boost-programming-skills-read-git-code/) + +## Getting started hacking and contributing + +* ["My First Contribution"](https://git-scm.com/docs/MyFirstContribution) + +* ["My First Object Walk"](https://github.com/git/git/blob/master/Documentation/MyFirstObjectWalk.adoc) + +* [Matheus' tutorial](https://matheustavares.gitlab.io/posts/first-steps-contributing-to-git) + +* [Eric Ju's "Contribute-to-Git: A beginner's Guide" wiki](https://gitlab.com/gitlab-org/git/-/wikis/Contribute-to-Git:-A-beginner's-Guide) + +* ["Hacking Git"](https://git-scm.com/docs/user-manual#hacking-git) in the Git User's Manual + +* ["`Documentation/technical`"](https://github.com/git/git/tree/master/Documentation/technical), technical documentation (also viewable at `https://git-scm.com/docs/`) + +* [Our General Microproject Information](https://git.github.io/General-Microproject-Information/) can help understand the process of contributing and find issues to work on. + +## Conventions and processes + +* ["`CodingGuidelines`"](https://github.com/git/git/blob/master/Documentation/CodingGuidelines) + +* ["`SubmittingPatches`"](https://git-scm.com/docs/SubmittingPatches/) + +* [Git for Windows' "Good commits"](https://gitforwindows.org/good-commits) + +## Process related tools and sites + +* [GitGitGadget](https://gitgitgadget.github.io/) makes it easy to send patches to the mailing list. + +* [Sending patches by email with git](https://flusp.ime.usp.br/git/sending-patches-by-email-with-git/) is Matheus' git send-email tutorial. + +* [lore.kernel.org/git](https://lore.kernel.org/git/) is our preferred mailing list archive. + +* [public-inbox](https://public-inbox.org/README.html) is the software behind lore.kernel.org. + +* [lore+lei](https://people.kernel.org/monsieuricon/lore-lei-part-1-getting-started) helps take advantage of lore/public-inbox. + +* [b4](https://people.kernel.org/monsieuricon/introducing-b4-and-patch-attestation) helps work with patches posted on lore/public-inbox. + +* [git-series](https://github.com/git-series/git-series) helps manage patch series. + +* [git-publish](https://github.com/stefanha/git-publish) helps manage patch series. + +* [git-related](https://github.com/felipec/git-related) finds people who might be interested in a patch. + +## Development status, news and events + +* [Junio's "What's cooking in git.git" emails](https://lore.kernel.org/git/?q=s%3A%22What%27s+cooking+in+git.git%22) list the status of various development topics. + +* [Git's release calendar](https://tinyurl.com/gitCal) shows the planned release cycles, the maintainer's planned offline time, and possibly other events. + +* [Git Rev News](https://git.github.io/rev_news/archive/) newsletter. + +* [Git Merge conference](https://git-merge.com/). + +* [Discussions about Contributor(s) Summits on the list](https://lore.kernel.org/git/?q=s%3AContributor*+Summit) + +## Branching workflow + +* ["A note from the maintainer"](https://github.com/git/git/blob/todo/MaintNotes) + +* ["Large-Merging Workflows"](https://git-scm.com/book/en/v2/Distributed-Git-Maintaining-a-Project#_large_merging_workflows) in the Pro Git book + +* [`gitworkflows`](https://git-scm.com/docs/gitworkflows) manual page + +* ["How to maintain Git"](https://github.com/git/git/blob/master/Documentation/howto/maintain-git.adoc) + +* ["How the Creators of Git do Branching"](https://hackernoon.com/how-the-creators-of-git-do-branches-e6fcc57270fb), and the associated [gitworkflow](https://github.com/rocketraman/gitworkflow) repository + +## Debugging + +* [Git for Windows' Debugging Git](https://gitforwindows.org/debugging-git) + +* [Launching GDB explanations in CodingGuidelines](https://github.com/git/git/blob/v2.27.0/Documentation/CodingGuidelines#L441-L445) + +* [Philippe Blain's "Debugging Git" Gist](https://gist.github.com/phil-blain/17c67740bd26e66f4851fe0c07230ea4) + +* [Debugging test failure using gdb example](https://public-inbox.org/git/CAP8UFD3Bd4Af1XZ00VyuHnQs=MFrdUufKeePO1tyedWoReRjwQ@mail.gmail.com/) + +## Tests + +* ["`t/README`"](https://github.com/git/git/blob/master/t/README) + +* ["`t/perf/README`"](https://github.com/git/git/blob/master/t/perf/README) + +## Community, getting help, mentoring + +* [git-scm community page](https://git-scm.com/community) + +* [web interface to #git-devel IRC channel on Libera Chat](https://web.libera.chat/#git-devel) + +* [#git-devel IRC channel archive](https://colabti.org/irclogger/irclogger_logs/git-devel) + +* [Git Community Discord Server](https://discord.gg/NKY7fFue) + +* [git-mentoring mailing list](https://groups.google.com/forum/#!forum/git-mentoring) + +* ["A note from the maintainer"](https://github.com/git/git/blob/todo/MaintNotes) + +## Mentoring programs + +* [Google Summer of Code](https://summerofcode.withgoogle.com/) + +* [Outreachy](https://www.outreachy.org/) + +* [General Application Information](https://git.github.io/General-Application-Information/) diff --git a/SoC-Historical.md b/Historical-SoC-Outreachy.md similarity index 62% rename from SoC-Historical.md rename to Historical-SoC-Outreachy.md index 17daa73616..1f84fb4d19 100644 --- a/SoC-Historical.md +++ b/Historical-SoC-Outreachy.md @@ -1,10 +1,10 @@ --- layout: default -title: Historical Summer of Code Materials +title: Historical Summer of Code and Outreachy Materials --- -These pages are historical application materials for Summer of Code and -other programs. They are for reference only! +These pages are historical materials for Summer of Code and +Outreachy. They are for reference only!
    {% for node in site.pages reversed %} diff --git a/Mentoring-Program-Guide.md b/Mentoring-Program-Guide.md new file mode 100644 index 0000000000..52d2b47960 --- /dev/null +++ b/Mentoring-Program-Guide.md @@ -0,0 +1,649 @@ +--- +layout: default +title: Mentoring Program Guide +--- + +This is the page to help people, who got accepted in a Mentoring +Program like the Google Summer of Code (GSoC) or Outreachy, during the +program. It can also help those interested in applying to such a +program get an idea about how it goes. + +First congratulations for being accepted! + +# Introduction + +The way you will be mentored depends on a lot of different things, for +example how well you are doing, who are your mentors, what your +project is about, what the mentoring program (GSoC or Outreachy) +requires or suggests (which can significantly change each year), how +the mailing list responds to your patches, what currently happens in +your country or in your mentors' countries, etc. + +This document might give you an idea about how things usually go, but +don't be surprised if your mentors ask for things that are a bit +different than what is described here. It's also possible that things +change during the mentoring program. Typically your mentors will +expect that you become more autonomous. + +# Communication + +## Blogging + +One of the first things you might want to setup (if you haven't one +already), after you have been accepted, but before the working period +actually starts, (GSoC calls this the "Community Bonding" period,) is a +blog. + +You might want to check which blogging tools previous Outreachy +interns and GSoC contributors used. Using a Git related tools is of course +a good idea. + +- [Miriam Rubio's Outreachy intership experiences](https://mirucam.gitlab.io/outreachy_blog/) +- [Matheus Tavares's Blog](https://matheustavares.gitlab.io/) [ [source](https://gitlab.com/MatheusTavares/matheustavares.gitlab.io/) ] + +Using GitHub: + +- [Charvi Mendiratta's Outreachy Internship Experiences](https://charvi-077.github.io/) [ [source](https://github.com/charvi-077/charvi-077.github.io) ] + +If you already have something setup using other tools though, even if +it's not Git based, it's perfectly OK to use what you already have, +and focus on your project right away. + +Your blog should be a tool to improve communication between you and +the Git community, including your mentors. Your blog is also something +that can help you in your career by reflecting positively on your +abilities and dedication. A good example is Matheus' GSoC blog posts: + +[Matheus Tavares' GSoC posts](https://matheustavares.gitlab.io/tags/gsoc/) + +Tip: It's better if you can decide the day for your weekly blog post +as soon as you set up you blog. Then tell your mentors about that day +right away, and try as much as possible to post every week on that +day. This will help establish a routine, that will make things easier +for both you and your mentors. + +Tip: It's also better if you can prepare the content of your weekly +blog post during the week as you are working on your project. This way +it can also serve you as a todo list, a notebook, a list of current +issues, etc. + +## Social media and blog post content + +In general posting about your GSoC on social media (like LinkedIn) is +nice too. You can put links to your blog post in your social media +posts, as they are usually shorter than blog posts. + +You can start blogging as soon as your mentors contact you after you +have been officially selected to participate in the mentoring +program. It's in fact a nice idea to start blogging right after they +have contacted you. + +In all your posts (on your blog or social media), when you mention +your mentors and when they are mentoring you as part of their job, +it's nice to mention the companies they are working for too. Some +mentors could mentor you in their free time, and might not want their +employer mentioned though. So if you are not sure that it's part of +their job, just ask them before posting. In case of Outreachy if some +company sponsors your internship, it's a very good idea to mention +them too. + +The more these companies get good mentions in the media about your +GSoC, and the more good work you deliver during it, the more likely +they are to allow their employees to mentor others, or even to sponsor +mentoring programs (like Outreachy internships for example), or maybe +to hire or help you in the future. + +## Regular updates + +Mentors should be regularly updated about your work, so they can know +if you are stuck on something, what you have done, and what you are +planning to work on and how. + +The best way to update everyone about your work is probably to post on +your blog. We understand though that you might not want to put +everything you might want to say on your blog. + +People on the Git mailing list might be interested to know that you +published something on your blog, so that they can give you some help +or feedback about your next steps or problems you are facing. So we +think that you might want to email the mailing list to notify every +one about each new blog post. If you don't feel like doing that, +we might find an alternative solution, but letting people know is +often a good idea to get help and suggestions. You can also take +advantage of the notification email to ask for help or to ask +questions related to issues you have. + +Your mentors should be notified too that you posted something. To +notify your mentors, you can either cc them when you email the +mailing list, or you can send them a separate email. In a separate +email you might add things that you might not want to post on your +blog or to the mailing list. + +We require you to update your mentors at least every week. So the best +is if you can post on your blog weekly (and send the related +notifications discussed above). If sometimes for some reason (like a +vacation or exams or family issues) you cannot post a weekly update, +then it's OK to just email your mentors, or to ask them to have a chat +one way or another. Then please make sure you post on your blog the +following week. + +In the blog post update and your emails to your mentors and the +mailing list, it is important that you cover all the following topics: + +1. what you have done since last update and how +2. what is blocking you if anything +3. what you find difficult to do or understand +4. what things you think should be easier +5. what you are planning to work on and how + +The reason we ask for 2), 3) and 4) is that often interns or +contributors don't know about things, like existing documentation, +historical discussions, debugging scripts, features, tools or +techniques, that could help them understand what's going on, or work +in a more efficient way. If a mentor doesn't know that the intern or +contributor is blocked or slowed by something or has a hard time +moving forward, it's difficult for the mentor to help. So it's +important for interns or contributors to reflect on the issues, +blocks, inefficiencies, complex things that they are facing. + +Notifying the mailing list or your mentors about a blog post, should +not prevent you from emailing or contacting the mailing list or your +mentor when you might want to do that at other times. In general don't +be afraid of posting or contacting people early and often. + +## Chat + +It can help to sometimes have a chat (by that we mean a real-time +conversation) with your mentors. This can especially help you when you +are stuck or after you have reflected a bit on the status of your work +and internship, and have doubts or feelings that things aren't going +as well as they could. + +As we think it's best that you decide on your own the best time to +update your blog and send notifications, you should then also decide +when it's best to have a chat with your mentors. So, unless you prefer +to plan regular chats, your mentors might not ask for a chat, and +might just want you to pro-actively email them when you want a chat. + +Some mentors might not be always online on a chat platform, so you +might need to schedule chat discussions, and try to find a good time +for everyone. You can also propose the tools and media that work best +for you (instant messaging, phone call, video call, WhatsApp, Zoom, or +even email ...) and your mentors will likely do their best to adapt to +your preferences. + +Mentors usually look at their emails several times per day on week +days, so you can say for example in an email that you are free during +the next 2 hours to have a chat, and that could be enough to schedule +a chat to unblock you. You can also use a notification email after a +blog post to schedule a chat. In general if you are not blocked and +you have more than one mentor, it's better to schedule a chat a few +days in advance to increase the chances that all your mentors can +participate. + +In general for everything specifically related to your project and +internship, it's better to try to involve all of your mentors (for +example by Ccing all of them in emails, and by using an instant +messaging group they all belong to), though we know it's not always +possible or practical when you are blocked. + +It could be OK to discuss personal or technical things or anything not +directly related to your project with only one of your mentors (like +with anyone else). Just ask them. + +If you prefer to have a completely fixed schedule from the start as +you know each week well in advance when you will post on your blog and +when you want to have a chat with your mentors, that can work too +and you can probably set this up with them. + +It's also OK to have such conversations completely over email if you +prefer. We know that email is not usually considered really real-time, +but we think it is, or can be, close enough compared to instant +messaging chat for example. It sometimes happen on the Git mailing +list that people debug together or discuss together +something over email in a very real-time way (at least similar as +instant messaging chat). + +Such chats can sometimes help a contributor or intern (or even long +timers on the project) move very fast in a short amount of time. So +consider taking advantage of that. + +It's also easier for mentors to help (or understand how they could +help) when discussing informally using a real time or near real time +communication medium, rather than blog posts or emails, so don't +hesitate to ask for that even if you are not sure that they could +help. And don't hesitate to ask them to use a medium you haven't +already used with them, like Zoom for example to have a video chat, as +sometimes it's just easier to understand something by sharing a +screen. + +You are also encouraged to take advantage of the whole Git community +and its communication channels (https://git-scm.com/community), like +the #git-devel IRC channel. Some or all of your mentors might not be +on this channel or on alternative community channels you might want to +use, but if you want to discuss with your mentors there, that's +something they can consider. + +## Scheduling and other communication issues + +Some mentors cannot easily let you know in advance what days and times +they will be available to answer questions. They might not have a well +planned schedule. They should be able to schedule things or give you +time periods when they are more likely to be available though. + +Anyway you should usually not wait much before asking a question. If +you haven't found an answer or don't understand something after a 20 +minute search on the mailing list archive, the code, the documentation +and Google, it's high time to ask a question or ask to have a chat. +Please try to search for 5 to 10 minutes before asking though, and +please let your mentors know how you searched, so that they can +perhaps help you be more efficient in searching for answers. + +In general being as open as possible about everything related to your +work, like what you don't know or don't understand, possible mistakes +you have made and are still making, how you are searching when there +is something you don't understand, which commands you are running, and +even how you are feeling, helps a lot in resolving issues and moving +forward. + +If you plan to have a vacation or if something might prevent you from +contacting your mentors, from updating them weekly, or from working on +your project for some time, please let them know in advance. + +# Code + +## Repository + +We require that you store and regularly update your current work in +public repos on GitLab or GitHub (or maybe Gerrit, gitolite, etc, but +please discuss it with us before choosing something other than GitHub +or GitLab). Usually a single repo forked from an official git.git repo +maintained by Junio (like https://github.com/git/git) is enough, and +you probably already have one. + +It unfortunately happens that people stop working on their in progress +project, either after the mentoring program is finished, or sometimes +during the mentoring program, and we might want to reuse their work +later. Often for example it takes a number of mentoring programs to +finish a big project and you have to continue a project from where it +was left by someone else. + +Having everything in one, or a few, public repositories makes it +easier to continue some work and also to test or contribute to it +occasionally. So making your work available this way and frequently +linking to your repo and the branches and commits in it you have +worked on (for example from your blog posts and emails to the mailing +list and your mentors), can help you get comments, code contributions, +bug reports, etc, which will move your project forward. + +## Draft patch series and branches + +It's a good idea to have your mentors review your patches or patch +series or branches on your repo before sending them to the mailing +list. It's OK though if you want to sometimes send a draft patch or +patch series directly to the mailing list to get as much as possible +everyone's feedback on something. You should mark them as [RFC] +(request for comment) or [WIP] (work in progress) though. + +A good way to have your mentors review something is to send them a +link to it on your public repo. This way they can comment there and +maybe make suggestions that you can easily apply. You could also +directly send them your patches as emails if they are OK with it. + +When you update your work after having received feedback from your +mentors or others, it's nice if instead of updating the same branch, +you could make changes, on a new branch. For example, if you are +working on `git bisect` you could make some initial changes on a +branch named bisect1, then, after receiving some comments on it, make +further changes on bisect2, and so on. This way your mentors and +others could check what you did using a diff, or a range-diff, between +the branches. + +Before you ask your mentors to review something, even if it's in the +draft or work in progress state, it's a good idea to make sure that +you have put some effort in writing a good commit message for each of +the commits you'd like them to review. Without a commit message (with +a title and a body) explaining the purpose of your patch, it can be +difficult for your mentors (or anyone actually) to tell if it makes +sense. + +If you know that something is missing in your patch, it's a good idea +to add [WIP] or [RFC] in the title and to add comments somewhere about +things that are missing, (like /* TODO: XXX */ comments in the code +for example), so that your mentors know which parts of your work are +not finished. + +A good time to send a link to a branch you are working on to your +mentors and ask them to review it, is typically when the commit +message and the code look good, and when it compiles without warnings +and passes existing tests, but when you haven't yet written the +documentation and the new tests. You can then work on the new tests +and documentation while your mentors review the code. Even then, +please say that documentation and new tests are missing. + +That said, it's OK to send something when a number of parts are +missing, including maybe some parts of the commit message and when the +code does not even compile, as long as you describe clearly what you'd +like to do, what are the issues you are facing and what is missing or +not yet finished, so that your mentors don't have to guess or tell you +that things are missing or should be improved when you already know +it. + +The goal is really to have efficient discussions for both you and your +mentors, so that your project can move forward fast with as few +misunderstandings as possible and as little frustration as possible. + +As much as possible you should work on different parts of your work in +different branches, and avoid having similar commits you are working +on in different branches. + +It's much better to work on many small branches and patch series that +can be regularly sent or resent to the mailing list, rather than on a +single big one that can be sent only at the end when everything looks +good. + +## Sending patch series to the mailing list + +It's up to you if you prefer to wait until your mentors have reviewed +everything and found nothing wrong with your patches, which could be a +good thing as it would likely decrease the reviewers' work on the +mailing list, or if you prefer to send your patches when you think +they are ready. + +You might acknowledge your mentors' help with the work you are doing +by adding a "Mentored-by: Mentor Name " trailer for each +of your mentors in the commit message of all the patches you send. We +recommend doing this systematically instead of spending time finding +which mentor helped or not on which patch. + +Basically sending patch to the mailing list is the same process as +when working on a micro-project. + +A few things that you might want to do are: + +- Make sure your mentors are Cc'ed on all of your patches. + +- Make sure everyone who commented or got involved is also Cc'ed. + +- Make sure Junio is among the recipients (in the "To:" header) if + your patches have been reviewed. + +- Consider adding the "Mentored-by:" trailers discussed above. + +- Consider adding some "Helped-by:", "Reviewed-by:" or "Acked-by:" + trailers if relevant. + +- Don't forget bumping up the version of the patch series. + +- Don't forget using [GSoC] or [Outreachy]. + +- Don't forget using [RFC] or [WIP], if it's relevant. + +# Resources, rules, documentation and links + +We encourage you to get as much help as you can from your mentors and +the Git community according to the suggestions in the "Communication" +section above. + +Nevertheless you are also welcome to get help in many different ways +that might not be mentioned above. Such help can come from the +community, its people, tools, documentation or websites, as well as +other people, tools or websites. You have to do most of the actual +work and follow some rules though. + +The following sections list some of these resources (people, tools, +documentation, websites, etc.), sometimes along with suggestions about +when they might be useful. + +Some of these resources are also important as they can help you learn +about the rules. + +## People + +When communicating with other people, we encourage you to keep your +mentors (or perhaps the whole community) in the loop though, if +possible. + + - Individual contributors + + When someone contributed to something very relevant to your work, + you might want to privately ask for help from them as they might + know more and might be able to help you better than your mentors + in some areas of your work. + + - Org Admins (people responsible for Git being involved in the + mentoring program) + + They could be useful if, for example, you, along perhaps with your + mentors, want to extend or change the duration of your mentoring + program (if it is allowed by the mentoring program). + + - Mentoring Program organizers + + If you have issues related to the mentoring program, you can + likely reach out to them. + + - Git PLC (Project Leadership Committee) members + + They are responsible for communicating with the + [Software Freedom Conservancy](https://sfconservancy.org/), + which is Git's parent nonprofit organization. They are also + responsible for enforcing Git's Code of Conduct, especially on the + Git mailing list. + +## Important community documentation and rules + +Please read, and try to keep in mind, the important documentation +below: + + - [Git's Code of Conduct](https://github.com/git/git/blob/master/CODE_OF_CONDUCT.md) + + This can be useful if others' behavior annoys you or if your + behavior might annoy other people. + + - [Git's SubmittingPatches doc](https://github.com/git/git/blob/master/Documentation/SubmittingPatches) + + This documentation contains the + [Developer's Certificate of Origin, or DCO for short](https://git-scm.com/docs/SubmittingPatches#sign-off), + which you have to know about when contributing to Git. + + - [Git's license](https://github.com/git/git/blob/master/COPYING) + + It makes sure that Git, and the contribution you make to it, are + free and open source software. You also have to know about it to + fully make sense of the DCO above. + +## Other community websites + +Please take a quick tour of those websites, if you haven't already, to +know about all the resources that they make available to you. + +Also note that you are very much encouraged to contribute to improving +these sites during your mentoring program. It's very much appreciated, +as it shows that you care about those who will come after you, even if +it's not part of your main work. + + - [Git Developer Pages](https://git.github.io/) + + This is the home of this very documentation and Git's mentoring + program related documentation. It also contains the + [Hacking-Git page](https://git.github.io/Hacking-Git/) + which has a number of helpful links. + + This website is maintained through + [its GitHub repo](https://github.com/git/git.github.io). + + - [Git Documentation website](https://git-scm.com/) + + This is the main Git website, with Git reference documentation + automatically generated from the + [Documentation folder](https://github.com/git/git/tree/master/Documentation) + of the Git repo, as well as a free book, and general information + about Git, including community information. + + This website is maintained through + [its GitHub repo](https://github.com/git/git-scm.com). + +## Other links + + - [Outreachy website](https://www.outreachy.org) + + - [GSoC website](https://summerofcode.withgoogle.com) + +# Roadblocks and Benefits + +Successfully participating in a mentoring program with Git can boost +your career in a number of different ways. Also even if it requires +working regularly and being open to mentoring, it's not very +difficult. We estimate that around 80% or more of the people we accept +succeed. + +## Roadblocks + +It's possible that you will encounter difficulties in moving forward +in your project. We try to list a few common ones here, along with +some advice to help overcome them. + +In general it's a good idea to discuss such issues with your mentor(s) +as early as possible. This way you might get some help and be able to +try different solutions before it's too late. One possible way to +alleviate some issues could be to extend the mentoring period if the +mentoring program allows it. + +### Dedicated time + +The main thing that could prevent you from succeeding is not having or +dedicating enough time to work on your project. Some people we +mentored had university classes, or found a full time job, or took +some long vacation, or spent a lot of time with their family, which +prevented them from dedicating enough time to their project. This +resulted in us having to fail them, which is sad for everyone. + +If you are planning to spend a significant amount of time doing other +things than working on your project during the mentoring program, it +might be better to not participate in it in the first place. You will +save yourself and your mentor(s) a significant amount of frustration, +and you will likely allow someone else to be successfully mentored and +gain a lot from that experience. + +Other roadblocks can more easily be overcome than not dedicating +enough time. Even if you can work a lot, you will need a bit of free +time during the mentoring program, so you may make things very +difficult for yourself if you are planning to work on both your +project and other things at the same time. Be considerate towards +yourself and do not put yourself in such a bad situation in the first +place. + +### Asking for help + +Another thing that could slow you is if it's difficult for you to +share with your mentor(s) about the technical hurdles you face. It +could be that you have trouble debugging or understanding how things +work or are supposed to work, and are afraid of asking for help. + +When we review your work, we provide technical suggestions, but when +you are starting it or in the middle of it, you are usually alone and +it can be difficult for you to ask your mentor(s) to take a look at +it. Please consider that the more transparent you are about your work, +and the more precise and specific you are in your questions, the +easier it is for us to help you, and for you to move forward. + +We only request that you spend around 10 minutes trying to find a +solution by yourself before you ask us about something. When you have +tried to find a solution, it's also a good idea to tell us what you +have tried or how you searched, as we can often help you be more +efficient in this too. + +### Personal issues + +Yet another roadblock that could sometimes prevent you from succeeding +is personal issues of different kinds. They are sometimes related to +your family or your partner. They are sometimes related to the other +potential roadblocks above. + +In general it's a good idea to talk about them early with your mentor, +as we just cannot properly handle difficult personal situations we are +not aware of. And regular communication, even using video chat, might +not be enough to suspect that your personal situation might be +difficult, if you are not explicit about it. + +## Benefits + +There are a lot of benefits in participating in mentoring programs +with the Git project, not just the fact that the programs pay the +participants a significant amount of money. + +And it's not limited to the first time you participate. The more you +participate, the more benefits you will reap. Participating as a +mentor or a co-mentor after you have been mentored, or becoming a +regular contributor, will also reflect very well on you and increase a +number of benefits you get. It's also relatively easy, as you have +already overcome the most difficult parts. + +### Career boost + +A number of former participants in a mentoring program with us have +reported that it significantly boost their career, as they much more +easily got job interviews, and then job offers with more well known +companies. + +### Improved technical skills + +Former participants also reported that they felt their software +engineering skills improved significantly. + +This is not just that they became more proficient with Git and source +code management in general. It's a also at least about improved +programming, testing, reviewing and collaborating skills. + +### Improved self confidence + +We believe that being able to contribute significantly to a well known +project like Git, also helps improve participants' self-confidence. +They are likely to be less afraid to participate in and contribute to +more complex software projects. + +### Improved Internet credibility + +We strongly encourage the participants we mentor to create a blog +about their work and regularly post on their blog, as we believe that +it helps them in many ways. We encourage them to post on social media +too. + +We also mention participants in our Git Rev News newsletter both after +they have been selected into a mentoring program, and after they +successfully finished it. + +Sometimes they get mentioned, or interviewed, in the blog posts of +some well known Git related companies too, like for example: + + - [this GitLab blog post about Outreachy](https://about.gitlab.com/blog/2021/04/15/outreachy-sponsorship-winter-2020/), or + - [this GitHub blog post about the Git 2.43 release](https://github.blog/2023-11-20-highlights-from-git-2-43/), + where Kousik's GSoC 2023 work is mentioned. + +### Meeting us at some conferences + +We try to help successful participants come to the +[Git Merge conference](https://git-merge.com/) +and meet the community, often including their mentor(s), there. For +that the Git project offers to reimburse the participants' travel +expenses. + +This is sometimes not possible due to visa issues, or the fact that +the Git Merge unfortunately doesn't happen every year, though. + +# Conclusion + +We hope you got an idea about how you will likely work with your +mentor(s) and how things usually go during the mentoring period of a +program such as GSoC or Outreachy. We hope you are also aware of the +people, communication means and resources available to help you, as +well as the rules you have to follow, the roadblocks you might +encounter and the benefits you may reap. + +As a reminder, don't be surprised if your mentors ask for things that +are a bit different than what is described here. Typically your +mentors will expect that you become more autonomous over time and will +adjust things depending on how autonomous you already are. + +Wishing you luck during your mentoring period! diff --git a/Outreachy-2016-May.md b/Outreachy-12.md similarity index 90% rename from Outreachy-2016-May.md rename to Outreachy-12.md index da1f77d681..427e610ce2 100644 --- a/Outreachy-2016-May.md +++ b/Outreachy-12.md @@ -1,6 +1,6 @@ --- layout: default -title: Outreachy May 2016 +title: Outreachy Round 12 (May 2016) navbar: false --- @@ -25,14 +25,14 @@ Before then, you should fill out an and complete a small [coding project](https://wiki.gnome.org/action/show/Outreachy?action=show&redirect=OutreachProgramForWomen#Make_a_Small_Contribution). We have a list of -[microprojects](../SoC-2016-Microprojects), but +[microprojects](https://git.github.io/SoC-2016-Microprojects), but you may also work with a potential mentor to come up with a contribution related to your proposed project. ## Project Ideas You can find a list of project ideas on our [ideas -page](../SoC-2016-Ideas). Note that this just a list of suggested +page](https://git.github.io/SoC-2016-Ideas). Note that this just a list of suggested projects; we are happy to hear proposals for new projects. If you would like to propose an idea, please make sure to solicit feedback from the mailing list (see below) and find someone willing to be a mentor for it. diff --git a/Outreachy-15.md b/Outreachy-15.md index 89903c8d44..9c75f46abe 100644 --- a/Outreachy-15.md +++ b/Outreachy-15.md @@ -1,6 +1,6 @@ --- layout: default -title: Outreachy Round 15: September 2017 +title: Outreachy Round 15 (September 2017) navbar: false --- diff --git a/Outreachy-17.md b/Outreachy-17.md index 87274459dc..09575b60aa 100644 --- a/Outreachy-17.md +++ b/Outreachy-17.md @@ -1,6 +1,6 @@ --- layout: default -title: Outreachy Round 17: September 2018 +title: Outreachy Round 17 (September 2018) navbar: false --- diff --git a/Outreachy-21-Microprojects.md b/Outreachy-21-Microprojects.md new file mode 100644 index 0000000000..cffa96590f --- /dev/null +++ b/Outreachy-21-Microprojects.md @@ -0,0 +1,94 @@ +--- +layout: default +title: Outreachy Winter 2020-2021 Applicant Microprojects +navbar: false +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid pipes in git related commands in test scripts + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +The git command should be on the left side of the pipe. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Modernize a test script + +A number of our test scripts have been written a long time ago in a +style that is now outdated. + +In the following email it is explained in details how to modernize and +clean up the t7001 test script: + + + +t7001 is not the only test script where similar changes could be made +though. + +Find one test script that needs some of the same changes and make +them. Please make sure that the test script is not already being +worked on by asking on the mailing list before starting to work on it. + +There should be only one kind of change per commit. For example if one +of your commits indents test bodies with TABs, instead of spaces, then +this should be the only kind of change in this commit. + +### Unify the meaning of `-dirty` between `diff` and `describe` + +`git diff` reports a submodule directory, whose tracked contents match +the commit at the `HEAD` in the submodule, as `-dirty` when there is an +untracked file in the submodule directory. This is inconsistent with +what `git describe --dirty` says when run in the submodule directory in +that state. + +Fix `git diff` to use the same definition of dirtiness for such a +submodule directory (or the other way around). +[[cf](https://lore.kernel.org/git/xmqqo8m1k542.fsf@gitster.c.googlers.com)] diff --git a/Outreachy-23-Microprojects.md b/Outreachy-23-Microprojects.md new file mode 100644 index 0000000000..353f179b6d --- /dev/null +++ b/Outreachy-23-Microprojects.md @@ -0,0 +1,113 @@ +--- +layout: default +title: Outreachy Winter 2021-2022 Applicant Microprojects +navbar: false +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Replace a run_command*() call by direct calls to C functions + +See for example what Junio did in +[ffcb4e94d3](https://github.com/git/git/commit/ffcb4e94d3) (bisect: do +not run show-branch just to show the current commit, 2021-07-27). + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid pipes in git related commands in test scripts + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +The git command should be on the left side of the pipe. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Modernize a test script + +A number of our test scripts have been written a long time ago in a +style that is now outdated. + +In the following email it is explained in details how to modernize and +clean up the t7001 test script: + + + +t7001 is not the only test script where similar changes could be made +though. + +Find one test script that needs some of the same changes and make +them. Please make sure that the test script is not already being +worked on by asking on the mailing list before starting to work on it. + +There should be only one kind of change per commit. For example if one +of your commits indents test bodies with TABs, instead of spaces, then +this should be the only kind of change in this commit. + +### Add --no-sort option for git-for-each-ref + +In "git for-each-ref", `ref_array_sort()` is used to sort ref_array with +sorting options. Even if the user does not provide any `--sort` option, +`ref_default_sorting()` will also provide the default sorting options with +the sort key "refname". + +But it turns out that the ref_array we get through `filter_refs()` is +already sorted by "refname". So providing a `--no-sort` option may +improve the performance of git for-each-ref when we don't provide any +sorting options on the command line. [thread](https://lore.kernel.org/git/YTNpeH+jO0zQgAVT@coredump.intra.peff.net/), +[thread](https://lore.kernel.org/git/YTTARcEvpXWSDfYW@coredump.intra.peff.net/) + +But the `--no-sort` option seems to be disabled in "git for-each-ref", +see "NEEDWORK" hint in `parse_opt_ref_sorting()`. You may need a new +list api to replace the original linked list implementation for ref_sorting. +You can refer to the implementation of this patch: +[thread](https://lore.kernel.org/git/e68635cda515a9cd504c1d7366e9c353ab2adb2e.1629882532.git.gitgitgadget@gmail.com/) + +You can use t/perf for performance testing between upstream and your patches. +[t/perf/README](https://github.com/git/git/blob/master/t/perf/README) diff --git a/Outreachy-Participants.md b/Outreachy-Participants.md new file mode 100644 index 0000000000..53c7fed07e --- /dev/null +++ b/Outreachy-Participants.md @@ -0,0 +1,60 @@ +--- +layout: default +title: Outreachy participants +--- + +This document collects the list of contributors who've contributed +to Git via Outreachy. + +### Winter 2024-2025 + +1. Seyi Kuforiji [ [blog](https://seyi-kuforiji-902b48.gitlab.io/) ] +2. Usman Akinyemi [ [blog](https://uniqueusman.hashnode.dev/tag/outreachy) ] + +#### References + +- [Rev News - Dec 2024](https://git.github.io/rev_news/2024/12/31/edition-118/) + +### Winter 2023-2024 + +1. Achu Luma [ [blog](https://lumap.gitlab.io/posts/) ] + +#### References + +- [Rev News - Dec 2023](https://git.github.io/rev_news/2023/11/30/edition-105/) + +### Winter 2020-2021 + +1. Sangeeta [ [blog](https://sangu09.github.io) ] +2. Joey Salazar [ [blog](https://jsal.home.blog/) ] +3. Charvi Mendiratta [ [blog](https://charvi-077.github.io/blog/) ] + +#### References + +- [Rev News - Dec 2020](https://git.github.io/rev_news/2020/12/26/edition-70/) + +### Winter 2019-2020 + +1. Heba W. [ [blog](https://medium.com/@heba.waly) ] +2. Miriam Rubio [ [blog](https://mirucam.gitlab.io/outreachy_blog/) ] + +#### References + +- [Rev News - Dec 2019](https://git.github.io/rev_news/2019/12/25/edition-58/) + +### Winter 2018-2019 + +1. Slavica Đukić [ [blog](https://slavicadj.github.io/blog/) ] +2. Tanushree Tumane [ [blog](https://tanu1596.blogspot.com/) ] + +#### References + +- [Rev News - Nov 2018](https://git.github.io/rev_news/2018/11/21/edition-45/) + +### Winter 2017-2018 + +1. Olga Telezhnaia [ [blog](https://medium.com/@olyatelezhnaya) ] + +#### References + +- [Rev News - Nov 2017](https://git.github.io/rev_news/2017/11/22/edition-33/) diff --git a/README.md b/README.md deleted file mode 120000 index 555cdc1cb5..0000000000 --- a/README.md +++ /dev/null @@ -1 +0,0 @@ -_includes/README.md \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000000..99d8801805 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +## Git Developer Pages + +- This is a website for information on Git development. If you stumbled into this by mistake, you may want: + - Information on running Git and links to download the latest version from [HERE](https://git-scm.com/) + - Wiki that has historically contained developer information from [HERE](https://git.wiki.kernel.org/index.php/Main_Page) + +- These pages are intended to collect information useful to Git developers. This is also the web home of: + - the [Hacking Git](https://git.github.io/Hacking-Git/) page, + - the [Git Rev News newsletter](https://git.github.io/rev_news/), + - the [involvement of the Git project in mentoring programs](https://git.github.io/General-Application-Information/) like [Outreachy](https://www.outreachy.org/) and the [GSoC (Google Summer of Code)](https://summerofcode.withgoogle.com/) + +- These pages are intended to be edited collaboratively (i.e., it is an alternative to us having a wiki, but one that is edited entirely via Git pushes). + + You could also send your changes as patches by email to Christian Couder < > / Kaartic Sivaraam < > (and feel free to cc git@vger.kernel.org if appropriate). + + +### Development + +If you wish to spin up the site locally, you could follow the steps below. + +* Make sure you've got ruby2 with dev-packages installed +* `sudo gem install bundler` +* Clone this repo +* `sudo apt-get install zlib1g-dev` # [ + [ref](http://www.nokogiri.org/tutorials/installing_nokogiri.html#ubuntu___debian) + ] +* `bundle install` +* `bundle exec jekyll serve` +* browse the site on http://localhost:4000 + +Based on https://help.github.com/articles/using-jekyll-with-pages/ + + +
    + +![Github Repo Size](https://img.shields.io/github/repo-size/git/git.github.io?style=for-the-badge&color=yellow) + +
    + +

    See our Contributors 😄

    + + + + + +
    diff --git a/SoC-2014-Microprojects.md b/SoC-2014-Microprojects.md index dceeccf260..f735a8a307 100644 --- a/SoC-2014-Microprojects.md +++ b/SoC-2014-Microprojects.md @@ -28,7 +28,7 @@ and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get -familar with the flow, need for clarity on both sides (i.e. you need +familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the diff --git a/SoC-2014-Org-Application.md b/SoC-2014-Org-Application.md index a3ea432de6..7f5fa5704b 100644 --- a/SoC-2014-Org-Application.md +++ b/SoC-2014-Org-Application.md @@ -31,7 +31,7 @@ GPLv2 ## Logo URL -![Git Logo](/images/logo.png) +![Git Logo](https://git.github.io/images/logo.png) ## Ideas list diff --git a/SoC-2015-Ideas.md b/SoC-2015-Ideas.md index 8d558eca09..2248169e81 100644 --- a/SoC-2015-Ideas.md +++ b/SoC-2015-Ideas.md @@ -77,7 +77,7 @@ look for the commit which fixed a bug. It is already possible using "git bisect", but the user has to type "good" to mean "the bug is there" and "bad" to mean "the bug is fixed", which isn't convenient. -It would be nice to allow the user to explicitely say "git bisect +It would be nice to allow the user to explicitly say "git bisect fixed" and "git bisect unfixed" instead. It is actually much harder than defining "fixed"/"unfixed" as aliases for "bad"/"good". diff --git a/SoC-2015-Microprojects.md b/SoC-2015-Microprojects.md index b8df3a6ede..de0a0a7293 100644 --- a/SoC-2015-Microprojects.md +++ b/SoC-2015-Microprojects.md @@ -28,7 +28,7 @@ and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get -familar with the flow, need for clarity on both sides (i.e. you need +familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the diff --git a/SoC-2015-Org-Application.md b/SoC-2015-Org-Application.md index 1f4e70714d..15793a97f7 100644 --- a/SoC-2015-Org-Application.md +++ b/SoC-2015-Org-Application.md @@ -31,7 +31,7 @@ GPLv2 ## Logo URL -![Git Logo](/images/logo.png) +![Git Logo](https://git.github.io/images/logo.png) ## Ideas list diff --git a/SoC-2016-Ideas.md b/SoC-2016-Ideas.md index 9d66a0c6d2..c5044c32c6 100644 --- a/SoC-2016-Ideas.md +++ b/SoC-2016-Ideas.md @@ -267,7 +267,7 @@ compressed data from one packfile to another. This would involve looking at the code in git to copy over optimisations as well as figuring out what parts of libgit2 should be -changed to accomodate these new capabilities. +changed to accommodate these new capabilities. - Language: C - Difficulty: medium diff --git a/SoC-2016-Microprojects.md b/SoC-2016-Microprojects.md index 3d3bebda50..54c5184b1b 100644 --- a/SoC-2016-Microprojects.md +++ b/SoC-2016-Microprojects.md @@ -40,7 +40,7 @@ and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get -familar with the flow, need for clarity on both sides (i.e. you need +familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the @@ -272,7 +272,7 @@ When you find something you are interested to work on, please ask first on the mailing list if it's worth doing and if it's appropriate for a microproject before starting to work on what you find. Even if it looks straitforward, there could be hidden reasons why it is too -difficult or just innappropriate. +difficult or just inappropriate. ### Searching the code base itself diff --git a/SoC-2016-Org-Application.md b/SoC-2016-Org-Application.md index ce4e27a1d4..1fbd9b975f 100644 --- a/SoC-2016-Org-Application.md +++ b/SoC-2016-Org-Application.md @@ -18,7 +18,7 @@ fast, scalable, distributed revision control system ## Logo -![Git Logo](/images/Git-Logo-1788C.png) +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) ## Primary Open Source License diff --git a/SoC-2017-Ideas.md b/SoC-2017-Ideas.md index e58e76e42f..8aaaa56aa5 100644 --- a/SoC-2017-Ideas.md +++ b/SoC-2017-Ideas.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2017 Ideas +navbar: false --- This is the idea page for Summer of Code 2017 for Git. diff --git a/SoC-2017-Microprojects.md b/SoC-2017-Microprojects.md index d74e628c04..ef4a09b3e0 100644 --- a/SoC-2017-Microprojects.md +++ b/SoC-2017-Microprojects.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2017 Applicant Microprojects +navbar: false --- ## Introduction @@ -32,7 +33,7 @@ and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get -familar with the flow, need for clarity on both sides (i.e. you need +familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the @@ -261,7 +262,7 @@ When you find something you are interested to work on, please ask first on the mailing list if it's worth doing and if it's appropriate for a microproject before starting to work on what you find. Even if it looks straitforward, there could be hidden reasons why it is too -difficult or just innappropriate. +difficult or just inappropriate. ### Searching the code base itself diff --git a/SoC-2017-Org-Application.md b/SoC-2017-Org-Application.md index 7837a2de16..580872b40e 100644 --- a/SoC-2017-Org-Application.md +++ b/SoC-2017-Org-Application.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2017 Organization Application +navbar: false --- This is a draft of git's application to Google's Summer of Code 2017. @@ -17,7 +18,7 @@ fast, scalable, distributed revision control system ## Logo -![Git Logo](/images/Git-Logo-1788C.png) +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) ## Primary Open Source License diff --git a/SoC-2018-Ideas.md b/SoC-2018-Ideas.md index ba1047068a..44a80233e4 100644 --- a/SoC-2018-Ideas.md +++ b/SoC-2018-Ideas.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2018 Ideas +navbar: false --- This is the idea page for Summer of Code 2018 for Git. diff --git a/SoC-2018-Microprojects.md b/SoC-2018-Microprojects.md index 2febfeb0d2..8a33938ff8 100644 --- a/SoC-2018-Microprojects.md +++ b/SoC-2018-Microprojects.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2018 Applicant Microprojects +navbar: false --- ## Introduction @@ -32,7 +33,7 @@ and the implementation of that design were all reviewed and discussed, and after several iterations an improved version of the patch was accepted into our codebase. As a GSoC student, you will be playing the role of the developer and engaging in a similar discussion. Get -familar with the flow, need for clarity on both sides (i.e. you need +familiar with the flow, need for clarity on both sides (i.e. you need to clearly defend your design, and need to ask clarifications when questions/suggestions you are offered are not clear enough), the pace at which the discussion takes place, and the general tone of the diff --git a/SoC-2018-Org-Application.md b/SoC-2018-Org-Application.md index d78ad47ffe..3b39c6d112 100644 --- a/SoC-2018-Org-Application.md +++ b/SoC-2018-Org-Application.md @@ -1,6 +1,7 @@ --- layout: default title: SoC 2018 Organization Application +navbar: false --- This is a draft of git's application to Google's Summer of Code 2018. @@ -17,7 +18,7 @@ fast, scalable, distributed revision control system ## Logo -![Git Logo](/images/Git-Logo-1788C.png) +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) ## Primary Open Source License diff --git a/SoC-2019-Ideas.md b/SoC-2019-Ideas.md new file mode 100644 index 0000000000..da3b6c8f36 --- /dev/null +++ b/SoC-2019-Ideas.md @@ -0,0 +1,309 @@ +--- +layout: default +title: SoC 2019 Ideas +navbar: false +--- + +This is the idea page for Summer of Code 2019 for Git. + +## About applying for SoC with the Git project + +*Please read this section completely before reading the idea list + below.* + +It is required that students who want to apply to the Git +project for the Summer of Code 2019 complete a tiny, code-related +"microproject" as part of their application. Please refer to our +[guidelines and suggestions for microprojects](https://git.github.io/SoC-2019-Microprojects) +for more information. Completing a microproject is not only an important +way for us to get experience with applicants, but it will also help +applicants become familiar with Git's development and submission +process. + +A complete GSoC application should include a presentation of yourself +(include any argument that may convince mentors that you are able to +complete the project) and detailed explanations about your project. +Ideas below are just ... ideas! The list is not exhaustive, and more +importantly each idea only includes a summary of what is to be done. +An application must include detailed plans on the design, timeline ... +A typical application takes several pages. You should already have read +[the GSoC Student Guide](http://write.flossmanuals.net/gsocstudentguide/writing-a-proposal/) +by now, but re-read it if needed. + +Also, working in Git project is not only about writing your own +patches. Constructively critiquing design and implementation of +patches by other people is also an important skill you need to learn +in order to effectively collaborate with others. So, if you have time +and inclination, it would be beneficial to read and understand other +applicants' patches (or any other patch submitted to the mailing-list), +think if you agree that the problem they are trying to solve is worth +solving, the approach they are taking is the best way (or if you think +of a better way to solve it), etc., and respond to their patches with +the result of your thinking as a review. + +Please, include link(s) to the mailing-list discussion(s) related to +your microproject in your application (e.g. linking to +[public-inbox](https://public-inbox.org/git/)). If you +participate in the review of other patches, then you may also include +links to discussions that would support your application. + +Students must send drafts of their proposal on the mailing-list before +submitting it officially to GSoC to get feedback from the +community. They are strongly encouraged to publish a draft on the +official GSoC website *and* post it to the mailing list for +discussion. + +Getting your proposal right can follow the same process as usual patch +submission for Git, as described in the +[microprojects](https://git.github.io/SoC-2019-Microprojects) page and +in `Documentation/SubmittingPatches` in Git's source code. It is also +expected that you will send several versions of your draft, responding +to comments on the list. Please plan to send the first draft early +enough so that a number of reviews and improvements cycles can happen. + +If you are not sure about your proposal, you can discuss that in the +same email where you introduce yourself or in separate emails. Please +use "[GSoC]" at the beginning of such emails. + +In summary, all applicants must (not necessarily in this order): + +* Complete a [microproject](https://git.github.io/SoC-2019-Microprojects). + +* Write a detailed application explaining their project. + +* Discuss their project by posting drafts of their application on the + mailing-list long before the deadline. + +In your application, and in the discussions related to projects you +are interested in, it is a good idea to: + +* Include link(s) to the mailing-list discussion(s) related to the + project you chose in your application or you are interested in, for + example previous discussions or patch series about the topic. There + might be interesting discussions about the topics that are several + year old. It is also a good idea to summarize them. + +* Include link(s) to the mailing-list discussion(s) related to the + previous drafts of your application itself. + +* Include link(s) to the mailing-list discussion(s) related to your + microproject. If your microproject patches have been merged, please + give the merge commits. Otherwise give their branch names and + current status in the last "What's cooking in git.git" email from + Junio. + +* Include what is suggested in + [the GSoC Student Guide](http://write.flossmanuals.net/gsocstudentguide/writing-a-proposal/) + +([public-inbox](https://public-inbox.org/git/) can be +used for searching the mailing list and linking to previous +discussions.) + +## Note about the number of slots + +In 2019, the Git organization has very limited mentoring capacity. +These days we usually accept between 0 and 3 students per year. + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Read the note below about refactoring +projects versus projects that implement new features though. + +### Unify ref-filter formats with other `--pretty` formats + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Christian Couder, Olga Telezhnaya, Thomas Gummerer + +Git has an old problem of duplicated implementations of some +logic. For example, Git had at least 4 different implementations to +format command output for different commands. Our previous GSoC +students and Outreachy interns unified some of the formatting logic +into [ref-filter](https://github.com/git/git/blob/master/ref-filter.h) +and got rid of similar logic in some command specific files. Current +task is to continue this work and reuse ref-filter formatting logic in +[pretty](https://github.com/git/git/blob/master/pretty.h). + +See discussion in: + + + +### `git log --oneline` improvements + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Christian Couder, Thomas Gummerer + +A number of Git commands, like `git log`, can show commit information +in a configurable way using ["pretty" formats](https://github.com/git/git/blob/master/Documentation/pretty-formats.adoc). +Such formats though don't yet support some features that users would +like, for example to display a log like the following: + +``` + b9df16a4c (HEAD -> master) + pathspec: don't error out on all-exclusionary pathspec patterns + 91a491f05 pathspec magic: add '^' as alias for '!' + c8e05fd6d ls-remote: add "--diff" option to show only refs that differ + 20769079d (tag: v2.12.0-rc2, origin/master, origin/HEAD) + Git 2.12-rc2 + 076c05393 Hopefully the final batch of mini-topics before the final +``` + +See discussions in: + + + + +### Convert scripts to builtins + + - Language: C, shell (bash), possibly Perl + - Difficulty: medium + - Possible mentors: Christian Couder, Thomas Gummerer + +A few components of Git are still in the form of shell and sometimes +Perl scripts. This causes problems in production code – in particular +on multiple platforms, e.g. Windows (think: POSIX-to-Windows path +conversion issues). + +The idea of this project is to dive into the Git source code and +convert a couple of shell and/or Perl scripts into portable and +performant C code, making it a so-called "built-in". + +(Un)fortunately, the important and easy to port scripts like +`git-pull.sh` are already ported by now. It should still be possible +to start with something small by porting portions of existing +shell-scripts to C using a C helper inside the existing shell-script. + +It will be an important part of the project to discuss and find the +most interesting scripts or parts of scripts to be ported. + +### Improve consistency of sequencer commands + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Elijah Newren, Christian Couder, Thomas Gummerer + +This would consist in taking care of the following issues: + +* The suggestion to fix an interrupted rebase-i or cherry-pick due to + a commit that became empty via `git reset HEAD` (in + builtin/commit.c) instead of `git rebase --skip` or + `git cherry-pick --skip` ranges from annoying to confusing. + (Especially since other interrupted am's and rebases both point to + am/rebase --skip.). Note that `git cherry-pick --skip` is not yet + implemented, so that would have to be added first. + +* There are a handful of flags that am-based rebases support that are + not available to interactive/merge-based rebases; it'd be nice to + implement them for the interactive machinery. (There are also + numerous flags that only the interactive machinery supports that are + unavailable to am-based rebases, but we don't care; we want to + deprecate am-based rebases.) + + * `--ignore-whitespace` (transliterate to `-Xignore-space-change`?) + * `--whitespace=...` + * `--committer-date-is-author-date`/`--ignore-date` + * `-C4` + +* [There's also some empty handling (from "Behavioral Differences" in + Documentation/git-rebase.txt) that would be nice to address, though + that might be contentious and we might try to tackle that piece + before GSoC gets rolling...] + +* Bonus: Make a flag to allow rebase to rewrite commit messages that + refer to older commits that were also rebased. (i.e. if rebasing + commits A and B, and commit B says `This reverts commit `, + then rewritten B's commit message should say + `This reverts commit `.) + Do this for both sha1sums and sha1sum abbreviations in commit messages. + +### `git revert --drop` and `git commit --reword` + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Thomas Gummerer + +The interactive rebase already supports the special oneline prefixes +`fixup!` and `squash!` in the `--autosquash` mode; these commits will +be reordered in the todo list and their `pick` commands adjusted +accordingly. + +These commits can be crafted conveniently via the `--fixup` and +`--squash` options of `git commit`. + +The idea of this project is to add two more actions, `drop!` and +`reword!`: + +* The `drop!` action (for convenience, `git revert --drop `) + would not only revert the commit, but a subsequent `git rebase -i + --autosquash` would reorder the `drop!` commit directly after the + matching commit, then change the matching commit's `pick` to `drop` + and comment out the `drop!` one. + +* The `reword!` action (for convenience, `git commit --reword `) + would let the user edit the commit message of the referenced commit, + and add an "empty" commit (i.e. a commit that does not modify any + files) with that commit message, prefixed with the `reword!` oneline. + The next `git rebase -i --autosquash` would then not only reorder + that commit after verifying that it is indeed an empty commit, it + would then also replace the `pick` command with an appropriate new + command (say, by extending the `squash` command to accept a `--reword` + option). + +This project will need to begin by implementing test cases to define +the expected outcome, and then implement the actual functionality. + +### Teach `git stash` to handle unmerged index entries + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Thomas Gummerer + +When the index is unmerged, `git stash` refuses to do anything. That is +unnecessary, though, as it could easily craft e.g. an octopus merge +of the various stages. A subsequent `git stash apply` can detect that +octopus and re-generate the unmerged index. + +See also the discussion in [this Git mailing list +thread](https://public-inbox.org/git/nycvar.QRO.7.76.6.1902072023250.41@tvgsbejvaqbjf.bet/). + +## Note about refactoring projects versus projects that implement new features + +Over the years we have been favoring refactoring projects over +possibly more interesting projects that implement new features. +Refactoring projects are usually easier to do step by step, and to get +code merged step by step which is encouraging. + +In general refactoring projects are worthwhile to do even if the +project is not finished at the end of the GSoC and even if the student +stops contributing after that. In those cases it is often a good idea +to later finish the refactoring either by ourselves or by proposing it +to another GSoC student or Outreachy intern. This way the work of both +students and mentors is not likely to be wasted. + +With a project that implements a feature, there is a risk, if it's too +complex or too difficult, that the feature will not be finished and +that nothing, or nearly nothing, will have been merged during the +GSoC. There is also the risk that another way to implement the feature +will appear later in the GSoC and all, or nearly all, the work of the +student and mentors will have been mostly wasted. It could also appear +that the use cases the feature was envisioned to be used in, are +better addressed by other improvements or a different workflow. + +Another potential issue is that a new feature might be prone to naming +or user interface discussions which could last for a long time or +could not result in clear decisions. + +Therefore we think that we should be very careful before proposing to +a student, or accepting, a project that implements a new feature. +People suggesting such a project should at least carefully consider +the above potential issues and see if they can be mitigated before the +project is submitted. + +As [suggested by Google](https://google.github.io/gsocguides/mentor/defining-a-project-ideas-list) +we emphasize that a student proposing something original must engage +with the community strongly before and during the application period +to get feedback and guidance to improve the proposal and avoid the +above potential issues. diff --git a/SoC-2019-Microprojects.md b/SoC-2019-Microprojects.md new file mode 100644 index 0000000000..9bec90f907 --- /dev/null +++ b/SoC-2019-Microprojects.md @@ -0,0 +1,284 @@ +--- +layout: default +title: SoC 2019 Applicant Microprojects +navbar: false +--- + +## Introduction + +It is strongly recommended that students who want to apply to the Git +project for the Summer of Code 2019 submit a small code-related patch +to the Git project as part of their application. Think of these +microprojects as the "Hello, world" of getting involved with the Git +project; the coding aspect of the change can be almost trivial, but to +make the change the student has to become familiar with many of the +practical aspects of working on the Git project. + +Git development is based on sending successive versions of patches or +patch series to the mailing list until they are considered good and +correct by the reviewers and Junio Hamano, the maintainer, who will +merge them. This process usually takes quite some time. By sending +drafts of your microproject patches to the +mailing list long before the deadline, you can show us that you are +willing and able to work well using the Git development process. + +It is *expected* that what you send will need several rounds of +reviews and discussions. If you are not sure at all about a patch you +can put "[GSoC][RFC/PATCH]" at the beginning of its subject. + +Consider [a sample email thread](http://public-inbox.org/git/1386590745-4412-1-git-send-email-t.gummerer@gmail.com/T/#u), +which shows how a developer proposed a change and a patch to implement +it. The problem being solved, the design of the proposed solution, +and the implementation of that design were all reviewed and discussed, +and after several iterations an improved version of the patch was +accepted into our codebase. As a GSoC student, you will be playing +the role of the developer and engaging in a similar discussion. Get +familiar with the flow, need for clarity on both sides (i.e. you need +to clearly defend your design, and need to ask clarifications when +questions/suggestions you are offered are not clear enough), the pace +at which the discussion takes place, and the general tone of the +discussion, to learn what is expected of you. + +To complete a microproject, you will have to go through approximately +the following steps: + +* Download the source code: clone the repository using the + [Git via Git](http://git-scm.com/downloads) instructions and read + the `README` file. + +* Build the source code: this is described in the file `INSTALL`. + +* Glance over our coding guidelines in the file + `Documentation/CodingGuidelines`. We take things like proper code + formatting very seriously. + +* Read about the process for submitting patches to Git: this is + described in `Documentation/SubmittingPatches`. + +* Select a microproject and check that it has not yet been taken or + discussed by searching the mailing list. + [Public Inbox](http://public-inbox.org/git/) is your friend. + +* Send an email to the mailing list where you describe the + microproject you want to work on, the way you want to do it, and + maybe talk a bit about yourself. Make sure the email you send has a + subject that starts with "[GSoC]". + +* **Make the actual change.** (Funny, this is the only part they teach + you about in college.) + +* Run the test suite and make sure it passes 100%: this is described + in the file `t/README`. (If you have added new functionality, you + should also add new tests, but most microprojects will not add new + functionality.) + +* Commit your change. Surprise: we use Git for that, so you will need + to gain at least + [a basic familiarity](http://git-scm.com/documentation) with using + Git. Make sure to write a good commit message that explains the + reason for the change and any ramifications. Remember to make sure + that you agree with our "Developer's Certificate of Origin" (whose + text is contained in `Documentation/SubmittingPatches`), and to + signify your agreement by adding a `Signed-off-by` line. + +* *Optional, but recommended:* + Create a fork of [Git](https://github.com/git/git) on github.com, + [sign in to Travis CI](https://travis-ci.org/auth) with your GitHub + account, accepting the GitHub + [access permissions confirmation](https://docs.travis-ci.com/user/github-oauth-scopes), + and enable builds of your Git fork in your Travis CI profile + (you only have to do these steps once). Afterwards you can push + your changes to your fork and on https://travis-ci.org/your-github-name/git/builds + (example [here](https://travis-ci.org/git/git/builds)) you can see + if your changes pass the Git test suite on Ubuntu Linux and on Mac OS X. + +* Submit your change to the Git mailing list. For this step you + probably want to use the commands `git format-patch` and `git + send-email`. Make sure that your email is formatted correctly: send + a test version of the email to yourself and see if you can apply it + to your repository using `git am`. Alternatively you may use + [GitGitGadget](https://gitgitgadget.github.io/) or + [submitGit](https://submitgit.herokuapp.com/). + + When you submit your patch, please mention that you plan to apply + for the GSoC. You can use "[GSoC][PATCH ...]" in the subject of the + emails you send for that purpose. This will ensure that we take + special care not to overlook your application among the large pile + of others. + +* Expect feedback, criticism, suggestions, etc. from the mailing list. + + *Respond to it!* and follow up with improved versions of your + change. Even for a trivial patch you shouldn't be surprised if it + takes two or more iterations before your patch is accepted. *This + is the best part of participating in the Git community; it is your + chance to get personalized instruction from very experienced peers!* + +The coding part of the microproject should be very small (say, 10-30 +minutes). We don't require that your patch be accepted into master by +the time of your formal application; we mostly want to see that you +have a basic level of competence and especially the ability to +interact with the other Git developers. + +## Only ONE quality focused microproject per student + +Students, please attempt only **ONE** microproject. We want quality, +not quantity! (Also, it takes work to collect the ideas, and it would +be nice to have enough microprojects for everybody.) + +This means that for a microproject that consist in refactoring or +rewriting a small amount of code, your patch should change only +**ONE** file, or perhaps 2 files if they are closely related, like +"foo.c" and "foo.h". + +If you change a test file, the title of your patch should start with +"tXXXX: " where tXXXX is the start of the filename of the test script +you change. If you change "foo.c" or "foo.h", the title of your patch +should probably start with "foo: ". + +In general it's a good idea to check on the mailing list archive what +other GSoC students attempting a microproject have already been told +this year or any previous year, as hopefully it will help you avoid +some mistakes. As some microproject ideas haven't changed for years, +some microprojects might have been attempted many times already and +you can learn a lot from these attempts. + +The more you research your microproject and take advantage of that, +the more confident we can be that you will be able to solve many +problems when working on your real GSoC project. So it's a very good +thing to show that you have researched your microproject and taken +into account what you have found. + +If you've already done a microproject and are itching to do more, then +get involved in other ways, like finding and fixing other problems in +the code, or improving the documentation or code comments, or helping +to review other people's patches on the mailing list, or answering +questions on the mailing list or in IRC, or writing new tests, etc., +etc. In short, start doing things that other Git developers do! +Alternatively you can of course focus on your +[project proposal](https://git.github.io/SoC-2019-Ideas). + +## Ideas for microprojects + +The following are just ideas. Any small code-related change would be +suitable. Just remember to keep the change small! It is much better +for you to finish a small but complete change than to try something +too ambitious and not get it done. + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. + +### Avoid pipes in git related commands in test scripts + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Add configuration options for some commonly used command-line options + +Many have already been added (e.g. "git am -3" in e97a5e7). + +Some people always run the command with these options, and would +prefer to be able to activate them by default in ~/.gitconfig. + +### Use dir-iterator to avoid explicit recursive directory traversal + +Some places in git use raw API opendir/readdir/closedir to traverse a +directory recursively, which usually involves function recursion. Now +that we have `struct dir_iterator` (see dir-iterator.h), convert these +to use the dir-iterator to simplify the code. Do only one conversion +per microproject. + +## How to find other ideas for microprojects + +If you don't like for some reason the above microprojects or if you +just want more choice, you may find other ideas for microprojects by +searching the mailing list (https://public-inbox.org/git/) or the +code base itself. In the code base you could search the code itself or +the tests (in the "t" directory). + +When you find something you are interested to work on, please ask +first on the mailing list if it's worth doing and if it's appropriate +for a microproject before starting to work on what you find. Even if +it looks straightforward, there could be hidden reasons why it is too +difficult or just inappropriate. + +### Searching for #leftoverbits in the mailing list + +People have recently started to add "#leftoverbits" to their emails +when they think further small work on the topic could be useful. + +You can easily search that using: + +https://public-inbox.org/git/?q=leftoverbits + +But don't forget to search to check if what you find has already been +addressed. If it has not been addressed, please ask first on the +mailing list if it's a good idea to work on that. + +### Searching the code base itself + +Your best bet is probably to search for strings like "FIXME", "TODO", +"NEEDSWORK", or maybe "NEED-WORK", and "BUG" (though not the "BUG()" +macro). + +You can also search for common patterns in the code and try to find or +create a function to refactor them. + +### Searching the tests + +Tests are in the "t" directory and can be run by launching "make" in +this directory. Doing that you will see that there are a number of +tests that are marked with "# TODO known breakage", like for example: + +"not ok 28 - git checkout -f: replace submodule with a directory must fail # TODO known breakage + +These tests start with "test_expect_failure" instead of +"test_expect_success". They document that something is not working as +it should perhaps be working. And it might be an interesting +microproject to fix that. + +Note that it is especially wise to first search the mailing list and +then ask on the list before working on one of these +"test_expect_failure", because if we bothered to document a failure +but not fix it, that is often because the fix is non-trivial. + +You could also check if some commands have no test for some of their +options and it could be an interesting microproject to add a test for +one of those options. + +### Searching the mailing list for other ideas + +You can search the mailing list for words like "low hanging fruit", or +"low-hanging fruits", "hint, hint", "later", "we should", "I plan +to"... diff --git a/SoC-2019-Org-Application.md b/SoC-2019-Org-Application.md new file mode 100644 index 0000000000..e03fec155e --- /dev/null +++ b/SoC-2019-Org-Application.md @@ -0,0 +1,290 @@ +--- +layout: default +title: SoC 2019 Organization Application +navbar: false +--- + +This is a draft of git's application to Google's Summer of Code 2019. + +# Git Profile + +## Website URL + + + +## Tagline + +fast, scalable, distributed revision control system + +## Logo + +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) + +## Primary Open Source License + +GPLv2 + +## Organization Category + +Programming Languages and Development Tools + +## Technology Tags + +c, shell script, git + +## Topic Tags + +version control, dvcs + +## Ideas List + + + +## Short Description (180 chars max) + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for many workflows. + +## Long Description + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for distributed, non-linear workflows. + +Many large and successful projects use Git, including the Linux +Kernel, Perl, Eclipse, Gnome, KDE, Qt, Ruby on Rails, Android, +PostgreSQL, Debian, and X.org. + +This organization covers projects for +[Git](https://github.com/git/git) itself. Other git-based software or +services are not covered by this organization. + +## Application Instructions + +``` +Guidance for students on how to apply to your organization. Should +include any prerequisites or requirements. You may wish to include a +template or tips for their proposals. May include limited Markdown. +``` + +Please read the "About applying for SoC with the Git project" section +in the ideas page: https://git.github.io/SoC-2019-Ideas/ + +The primary way to contact the Git community is through the Git +mailing list git@vger.kernel.org. Please discuss your application on +this list. + +## Proposal Tags + +``` +Enter tags that students can select (one) from and apply to their own +proposals to help organize them. Examples: New Feature, Optimization. +You can also use these to designate "sub-organizations" if you are an +umbrella organization. +``` + +new feature, refactoring, bug fix + +## Contact Methods + +``` +You must complete at least one of the following three contact options. +``` + +Chat: http://git-scm.com/community + +Mailing List: http://git-scm.com/community + +General Email: git@vger.kernel.org + +# 2019 Application Form + +## Why does your org want to participate in Google Summer of Code? + +With the exception of 2013, Git has participated in GSoC every year +since 2007. We have appreciated not only the code contributions (both +new features and internal refactoring to reduce the maintenance effort), but +also the increased project visibility and the addition of new long-term +contributors. We also believe strongly in helping students become +comfortable contributing to open source in general, even if they do not +remain involved with Git itself. + +## How many potential mentors have agreed to mentor this year? + +dropdown list => 1-5. + +Text below unused: + +``` +We have 3 potential co-mentors this year. This is a small number, and +we expect to take a correspondingly smaller number of projects +(probably only 1). + +All mentors are volunteers for the specific projects that they can +contribute the most to (i.e., ones that meet their interests and +abilities). All mentors are active contributors within the Git +development community, and well-known to the project leadership. + +Active contributors are defined to be those who have submitted and have +had accepted into a shipped release a substantial amount of code, where +substantial is defined to be equal to or larger than what might be +expected of a student working on a Google Summer of Code project. +``` + +## How will you keep mentors engaged with their students? + +``` +1000 characters. +``` + +We think that the most important part of GSoC is integrating the +student into the normal communication channels used by other project +members. The first step in dealing with disappearing students is to +make sure they are engaging with the community on design and code +issues, and reaching small milestones on the way to the project. Then +if they do disappear, we know quickly and can react, rather than being +surprised at the end. + +If they do disappear, we'll obviously contact them and find out +what's going on. But ultimately, non-communication is grounds for a +failing evaluation, regardless of any code produced. + +We plan to take fewer projects than we have as mentors. We usually +have two co-mentors per students, so that one mentor being unavailable +would have a limited impact on the project. Most of our projects can +be mentored by any of the mentors, and by keeping student progress +public and reviewed on-list, another mentor (or the community at +large) can pick up the slack if needed. + +## How will you help your students stay on schedule to complete their projects? + +``` +1000 characters. +``` + +There are several ways to do this, and they have been successful in +the past: + +* Prepare students to submit patches before they started. We use a + microproject system prior to the student application where students + must submit at least a patch, and respond to reviews. This means + that on day 1 of their project, students already know how long + review cycles are, and how important it is to work with the + mailing-list. + +* Split the work into small patch series. We don't expect regular + developers to go silent for 3 months and then dump 10,000 lines of + code on us to review, and we don't want students to do that to us + either. Even if the first patch series are only preparatory steps + that do not bring a real added value to Git, it is important to get + them merged as early as possible. Even if the project is not + "completed", useful pieces of code are validated all along the + project. + +## How will you get your students involved in your community during GSoC? + +``` +1000 characters. +``` + +Students will be required to join the main development mailing list +and post their patches for discussion (in addition to posting their +work as a Git repository on a publicly available server). All current +contributors already do this, so students will be able to see +experienced hands performing the same tasks and learn by example. We +also feel that the list-based discussions will help the student to +become and stay a member of the community. + +Mentors will also exchange direct email with students on at least a +weekly basis. Students will be required to provide weekly progress +reports back to their mentors, so that mentors are aware of the +current difficulties. Progress reports give the mentors a chance to +provide suggestions for problem resolution back to the student. + +Frequent email and IRC interaction with mentors and other developers +will be strongly encouraged by suggesting students post their questions +and ideas to the mailing list, and to discuss them on #git. + +``` +Unused text (did not fit the characters limit): + + +The traffic on the list is focused around Git development. We +expect the students to stay current by at least skimming the messages, +and participating in discussions that are close to their area of work. + +Many developers either already hold "office-hours" on IRC, or have +agreed to do so during the GSoC period. +``` + +## How will you keep students involved with your community after GSoC? + +Ultimately we have no leverage over the students after they leave, so +the best we can do is to help them form habits of interaction that they +might find rewarding and want to continue with. We specifically don't +want to give the student a "half project" that needs more work after the +GSoC period is done. That's not fair to the student, nor to the project. + +Instead, we'd prefer to get the student involved in the day-to-day of +interacting on the mailing list, reviewing code, and commenting on other +people's ideas and problems. Those are things they can continue to do +after GSoC ends, and those discussions can often spur more coding. + +## Has your org been accepted as a mentoring org in Google Summer of Code before? + +### Has your org been accepted as a mentoring org in Google Summer of Code before? + +Yes + +### Which years did your org participate in GSoC? + +Every year since 2007 except 2013. + +### What is your success/fail rate per year? + +``` +500 characters +``` + +Here are the numbers of passed (p), failed (f) and retained (r) students (where "retained" means "still participating on the mailing list a year or more after their GSoC") for each year: + + - 2007: 2 p, 1 f, 1 r + - 2008: 4 p, 2 f, 3 r + - 2009: 1 p, 1 f, 0 r + - 2010: 3 p, 1 f, 3 r + - 2011: 5 p, 0 f, 4 r + - 2012: 3 p, 0 f, 2 r + - 2014: 2 p, 1 f, 0 r + - 2015: 2 p, 0 f, 2 r + - 2016: 1 p, 0 f, 1 r + - 2017: 1 p, 0 f, 1 r + - 2018: 3 p, 0 f, 2 r + +### If your org has applied for GSoC before but not been accepted, select the years: + +None. + +## Provide a reference (optional) + + + +## What year was your project started? + +2005 + +## Where does your code live: + +http://github.com/git/git + +## Anything else we should know (optional)? + +We sometimes write about the GSoC in our Git Rev News newsletter +(https://git.github.io/rev_news/archive/). + +# Remarks on the current state of the application + +The 2015 application had a question "If you chose "veteran" in the +organization profile dropdown, please summarize your involvement and +the successes and challenges of your participation. Please also list +your pass/fail rate for each year." with a very detailed answer. diff --git a/SoC-2020-Ideas.md b/SoC-2020-Ideas.md new file mode 100644 index 0000000000..ce6d43cd62 --- /dev/null +++ b/SoC-2020-Ideas.md @@ -0,0 +1,241 @@ +--- +layout: default +title: SoC 2020 Ideas +navbar: false +--- + +This is the idea page for Summer of Code 2020 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### Unify ref-filter formats with other `--pretty` formats + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Christian Couder + +Git has an old problem of duplicated implementations of some +logic. For example, Git had at least 4 different implementations to +format command output for different commands. Our previous GSoC +students and Outreachy interns unified some of the formatting logic +into [ref-filter](https://github.com/git/git/blob/master/ref-filter.h) +and got rid of similar logic in some command specific files. Current +task is to continue this work and reuse ref-filter formatting logic in +[pretty](https://github.com/git/git/blob/master/pretty.h). + +See discussion in: + + + +### `git log --oneline` improvements + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Christian Couder + +A number of Git commands, like `git log`, can show commit information +in a configurable way using +["pretty" formats](https://github.com/git/git/blob/master/Documentation/pretty-formats.adoc). +Such formats though don't yet support some features that users would +like, for example to display a log like the following: + +``` + b9df16a4c (HEAD -> master) + pathspec: don't error out on all-exclusionary pathspec patterns + 91a491f05 pathspec magic: add '^' as alias for '!' + c8e05fd6d ls-remote: add "--diff" option to show only refs that differ + 20769079d (tag: v2.12.0-rc2, origin/master, origin/HEAD) + Git 2.12-rc2 + 076c05393 Hopefully the final batch of mini-topics before the final +``` + +See discussions in: + + + + +### Convert scripts to builtins + + - Language: C, shell (bash), possibly Perl + - Difficulty: medium + - Possible mentors: Christian Couder + +A few components of Git are still in the form of shell and sometimes +Perl scripts. This causes problems in production code – in particular +on multiple platforms, e.g. Windows (think: POSIX-to-Windows path +conversion issues). + +The idea of this project is to dive into the Git source code and +convert a couple of shell and/or Perl scripts into portable and +performant C code, making it a so-called "built-in". + +It will be an important part of the project to discuss and find the +most interesting scripts or parts of scripts to be ported. + +See discussion in: + + + +### Commit graph labeling for speeding up git commands + + - Language: C + - Difficulty: hard + - Possible mentors: Jakub Narębski + - Possible co-mentors: Heba Waly, Derrick Stolee + +Git uses various clever methods for making operations on very large +repositories faster, from bitmap indices for `git fetch`[[1][]], to generation +numbers (also known as topological levels) in the commit-graph file for +commit graph traversal operations like `git log --graph`[[2][]]. + +Unfortunately it turned out that we can get worse performance when +using those generation numbers than without them, with using +committerdate as a heuristics[[8][],[3][]] (and for selecting which +commits to walk first). It can lead to a large increase in number of +commits walked. The example we saw in the Linux kernel repository was +a bug fix created on top of a very old commit, so there was a commit +of low generation with very high commit-date that caused extra +walking. (See [[9][]] for a detailed description of the data shape in +this case.) + +Therefore the need for **generation number v2** was born. Various +candidates were examined (see e.g. +for initial list). New generation number needed to provide good +performance, incremental updates, and (due to unfortunate +problem[[10][],[3][]]) also backward compatibility. + +The generation number v2 that fulfills those requirements is 'backward +compatible date ceiling' or 'corrected commit date with monotonically +increasing offsets[[11][],[3][]]. What is stored in the commit-graph +in place of generation number is value of date offset; it is chosen to +be at least 1 more than maximum offsets of the parents of the commit, +while committerdate+offset (corrected commit date) also meets this +condition. + +The task would be then to update the generation number to "v2" based +on the referenced definition. A part of this task would be moving the +`generation` member of `struct commit` into a slab before making it a +64-bit value. (To learn how to store data on a slab one can see +ongoing work on adding Bloom filter for changed files to the commit +graph [[12][]].) This part could be done with help of [Coccinelle][] +scripts, like the ones in [`contrib/coccinelle`](https://github.com/git/git/tree/master/contrib/coccinelle). + +Another part of this task could be examining performance +improvements, like in +(perhaps extending it with `--contains`/`--merged` test). + +An _alternative_ would be examining other possible improvements that +can make Git even faster than just using generation numbers, like +using min-post **intervals labeling**[[3][]]. The basis of this +labeling is post-visit order of a depth-first search (DFS) traversal +tree of a commit graph, let's call it 'post(v)'. + +If for each commit 'v' we would compute and store in the commit-graph +file two numbers: 'post(v)' and the minimum of 'post(u)' for all commits +reachable from 'v', let's call the latter 'min_graph(v)', then the +following condition is true: + +> if 'v' can reach 'u', then min_graph(v) <= post(u) <= post(v) + +This labeling can be used to quickly find which commits are +unreachable (it is so called negative-cut filter). + +If for each commit 'v' we would compute and store in the commit-graph +file two numbers: 'post(v)' and the minimum of 'post(u)' for commits +that were visited during the part of depth-first search that started +from 'v' (which is the minimum of post-order number for subtree of a +spanning tree that starts at 'v'), let's call the later 'min_tree(v)', +then the following condition is true: + +> if min_tree(v) <= post(u) <= post(v), then 'v' can reach 'u' + +This labeling can be used to quickly find which commits are +reachable, because if they are reachable in the spanning tree for +commit graph, then they are reachable in commit graph itself. (Such +labeling is called positive-cut filter). + +The task would be to implement computing such labeling (or a more +involved variant of it, for example as described in [[4][],[5][],[6][]]), store it +in the commit-graph file, and then use it for speeding up git +commands, such as[[3][]]: + + - `git merge-base --is-ancestor` + - `git branch --contains` + - `git tag --contains` + - `git branch --merged` + - `git tag --merged` + - `git merge-base --all` + - `git log --topo-sort` + +Before starting on this task, at the beginning of the GSoC, it might +be good idea to have an exploration period, to determine which methods +brings which performance improvements. This _could_ be done with the +help of "Reachability labels for version control graphs.ipynb" Jupyter +Notebook on Google Colaboratory[[6][]] (in Python). This notebook was +created to answer such questions, though the exploration didn't get +finished. It would be possible with this notebook to at least find +the amount of false negatives for min-post interval labeling in +git.git or Linux kernel repo. Alternatively this could be done by +creating prototypes and perhaps examining performance in portable and +repeatable way using [trace2 API][api-trace2], like it was done +for [gen-test][] (experimenting with candidates for generation number +v2, see above). + +One can start this task with using min-post interval labeling for +making selected single command faster, for example for `--contains` +queries (as it was done for generation numbers). + +Next task would be, time permitting, to make it possible to update the +labeling without recomputing it from scratch, and to make it +compatible with incremental update of the commit-graph file[[7][],[3][]]. + +References: + +1. +2. +3. + - + - +4. + section 3.3 "Pruning Based on DFS Numbering" +5. and +6. +7. +8. +9. +10. +11. +12. + +[1]: https://githubengineering.com/counting-objects/ "Counting Objects | The GitHub Blog" +[2]: https://devblogs.microsoft.com/devops/supercharging-the-git-commit-graph-iii-generations/ "Supercharging the Git Commit Graph III: Generations and Graph Algorithms | Azure DevOps Blog" +[3]: https://drive.google.com/open?id=1psMBVfcRHcZeJ7AewGpdoymrEfFVdXoK "Graph operations in Git version control system (PDF)" +[4]: https://arxiv.org/abs/1404.4465 "[arXiv:1404.4465] PReaCH: A Fast Lightweight Reachability Index using Pruning and Contraction Hierarchies" +[5]: https://arxiv.org/abs/1211.3375 "[arXiv:1211.3375] High-Performance Reachability Query Processing under Index Size Restrictions" +[6]: https://colab.research.google.com/drive/1V-U7_slu5Z3s5iEEMFKhLXtaxSu5xyzg "Reachability labels for version control graphs.ipynb | Colaboratory" +[7]: https://devblogs.microsoft.com/devops/updates-to-the-git-commit-graph-feature/ "Updates to the Git Commit Graph Feature | Azure DevOps Blog" +[8]: https://git.github.io/rev_news/2018/11/21/edition-45/#general "Git Rev News: Edition 45 (November 21st, 2018) :: [RFC] Generation Number v2" +[9]: https://lore.kernel.org/git/efa3720fb40638e5d61c6130b55e3348d8e4339e.1535633886.git.gitgitgadget@gmail.com/ "[PATCH 1/1] commit: don't use generation numbers if not needed" +[10]: https://git.github.io/rev_news/2019/06/28/edition-52/#reviews "Git Rev News: Edition 52 (June 28th, 2019) :: [PATCH 00/17] [RFC] Commit-graph: Write incremental files" +[11]: https://lore.kernel.org/git/86o8ziatb2.fsf_-_@gmail.com/ "[RFC/PATCH] commit-graph: generation v5 (backward compatible date ceiling)" +[12]: https://public-inbox.org/git/pull.497.git.1576879520.gitgitgadget@gmail.com/t/#u "[PATCH 0/9] [RFC] Changed Paths Bloom Filters" + +[Coccinelle]: http://coccinelle.lip6.fr/ "Coccinelle: A Program Matching and Transformation Tool for Systems Code" +[api-trace2]: https://git-scm.com/docs/api-trace2 "Trace2 API | Documentation/technical/api-trace2.txt" +[gen-test]: https://github.com/derrickstolee/gen-test "Generation Number Performance Test - Test scripts for testing new versions of generation numbers" + +See also discussion in: + + + + diff --git a/SoC-2020-Microprojects.md b/SoC-2020-Microprojects.md new file mode 100644 index 0000000000..5fe04cc5c0 --- /dev/null +++ b/SoC-2020-Microprojects.md @@ -0,0 +1,73 @@ +--- +layout: default +title: SoC 2020 Applicant Microprojects +navbar: false +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid pipes in git related commands in test scripts + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +The git command should be on the left side of the pipe. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Add configuration options for some commonly used command-line options + +Many have already been added (e.g. "git am -3" in e97a5e7). + +Some people always run the command with these options, and would +prefer to be able to activate them by default in ~/.gitconfig. + +For some options though, we have made a deliberate choice to not +provide a configuration option. So ask on the mailing list if it's ok +before working on this. + diff --git a/SoC-2020-Org-Application.md b/SoC-2020-Org-Application.md new file mode 100644 index 0000000000..f1f70c0804 --- /dev/null +++ b/SoC-2020-Org-Application.md @@ -0,0 +1,305 @@ +--- +layout: default +title: SoC 2020 Organization Application +navbar: false +--- + +This is a draft of git's application to Google's Summer of Code 2020. + +# Git Profile + +## Website URL + + + +## Tagline + +fast, scalable, distributed revision control system + +## Logo + +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) + +## Primary Open Source License + +GPLv2 + +## Organization Category + +Programming Languages and Development Tools + +## Technology Tags + +c, shell script, git + +## Topic Tags + +version control, dvcs + +## Ideas List + + + +## Short Description (180 chars max) + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for many workflows. + +## Long Description + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for distributed, non-linear workflows. + +Many large and successful projects use Git, including the Linux +Kernel, Perl, Eclipse, Gnome, KDE, Qt, Ruby on Rails, Android, +PostgreSQL, Debian, and X.org. + +This organization covers projects for +[Git](https://github.com/git/git) itself. Other git-based software or +services are not covered by this organization. + +## Application Instructions + +``` +Guidance for students on how to apply to your organization. Should +include any prerequisites or requirements. You may wish to include a +template or tips for their proposals. May include limited Markdown. +``` + +Please read the "General Application Information" page: +https://git.github.io/General-Application-Information/ + +The primary way to contact the Git community is through the Git +mailing list git@vger.kernel.org. Please discuss your application on +this list. + +## Proposal Tags + +``` +Enter tags that students can select (one) from and apply to their own +proposals to help organize them. Examples: New Feature, Optimization. +You can also use these to designate "sub-organizations" if you are an +umbrella organization. +``` + +new feature, refactoring, bug fix + +## Contact Methods + +``` +You must complete at least one of the following three contact options. +``` + +Chat: https://git-scm.com/community + +Mailing List: https://git-scm.com/community + +General Email: git@vger.kernel.org + +## Twitter URL (optional) + +(Left blank) + +## Blog URL (optional) + +(Left blank) + +# 2020 Application Form + +## Why does your org want to participate in Google Summer of Code? + +With the exception of 2013, Git has participated in GSoC every year +since 2007. We have appreciated not only the code contributions (both +new features and internal refactoring to reduce the maintenance effort), but +also the increased project visibility and the addition of new long-term +contributors. We also believe strongly in helping students become +comfortable contributing to open source in general, even if they do not +remain involved with Git itself. + +## How many potential mentors have agreed to mentor this year? + +dropdown list => 1-5. + +Text below unused: + +``` +We have 3 potential co-mentors this year. This is a small number, and +we expect to take a correspondingly smaller number of projects +(probably only 1). + +All mentors are volunteers for the specific projects that they can +contribute the most to (i.e., ones that meet their interests and +abilities). All mentors are active contributors within the Git +development community, and well-known to the project leadership. + +Active contributors are defined to be those who have submitted and have +had accepted into a shipped release a substantial amount of code, where +substantial is defined to be equal to or larger than what might be +expected of a student working on a Google Summer of Code project. +``` + +## How will you keep mentors engaged with their students? + +``` +1000 characters. +``` + +We think that the most important part of GSoC is integrating the +student into the normal communication channels used by other project +members. The first step in dealing with disappearing students is to +make sure they are engaging with the community on design and code +issues, and reaching small milestones on the way to the project. Then +if they do disappear, we know quickly and can react, rather than being +surprised at the end. + +If they do disappear, we'll obviously contact them and find out +what's going on. But ultimately, non-communication is grounds for a +failing evaluation, regardless of any code produced. + +We plan to take fewer projects than we have as mentors. We usually +have two co-mentors per students, so that one mentor being unavailable +would have a limited impact on the project. Most of our projects can +be mentored by any of the mentors, and by keeping student progress +public and reviewed on-list, another mentor (or the community at +large) can pick up the slack if needed. + +## How will you help your students stay on schedule to complete their projects? + +``` +1000 characters. +``` + +There are several ways to do this, and they have been successful in +the past: + +* Prepare students to submit patches before they started. We use a + microproject system prior to the student application where students + must submit at least a patch, and respond to reviews. This means + that on day 1 of their project, students already know how long + review cycles are, and how important it is to work with the + mailing-list. + +* Split the work into small patch series. We don't expect regular + developers to go silent for 3 months and then dump 10,000 lines of + code on us to review, and we don't want students to do that to us + either. Even if the first patch series are only preparatory steps + that do not bring a real added value to Git, it is important to get + them merged as early as possible. Even if the project is not + "completed", useful pieces of code are validated all along the + project. + +## How will you get your students involved in your community during GSoC? + +``` +1000 characters. +``` + +Students will be required to join the main development mailing list +and post their patches for discussion (in addition to posting their +work as a Git repository on a publicly available server). All current +contributors already do this, so students will be able to see +experienced hands performing the same tasks and learn by example. We +also feel that the list-based discussions will help the student to +become and stay a member of the community. + +Mentors will also exchange direct email with students on at least a +weekly basis. Students will be required to provide weekly progress +reports back to their mentors, so that mentors are aware of the +current difficulties. Progress reports give the mentors a chance to +provide suggestions for problem resolution back to the student. + +Frequent email and IRC interaction with mentors and other developers +will be strongly encouraged by suggesting students post their questions +and ideas to the mailing list, and to discuss them on #git. + +``` +Unused text (did not fit the characters limit): + + +The traffic on the list is focused around Git development. We +expect the students to stay current by at least skimming the messages, +and participating in discussions that are close to their area of work. + +Many developers either already hold "office-hours" on IRC, or have +agreed to do so during the GSoC period. +``` + +## How will you keep students involved with your community after GSoC? + +Ultimately we have no leverage over the students after they leave, so +the best we can do is to help them form habits of interaction that they +might find rewarding and want to continue with. We specifically don't +want to give the student a "half project" that needs more work after the +GSoC period is done. That's not fair to the student, nor to the project. + +Instead, we'd prefer to get the student involved in the day-to-day of +interacting on the mailing list, reviewing code, and commenting on other +people's ideas and problems. Those are things they can continue to do +after GSoC ends, and those discussions can often spur more coding. + +## Has your org been accepted as a mentoring org in Google Summer of Code before? + +### Has your org been accepted as a mentoring org in Google Summer of Code before? + +Yes + +### Which years did your org participate in GSoC? + +Every year since 2007 except 2013. + +### For each year your organization has participated, provide the counts of successful and total students. (e.g. 2016: 3/4) + +``` +500 characters +``` +2007: 2/3 +2008: 4/6 +2009: 1/2 +2010: 3/4 +2011: 5/5 +2012: 3/3 +2014: 2/3 +2015: 2/2 +2016: 1/1 +2017: 1/1 +2018: 3/3 +2019: 2/2 + +### Refer an organization (optional) + +(Left blank) + + +### If your org has applied for GSoC before but not been accepted, select the years: + +None. + +## Provide a reference (optional) + +(Left blank) + +## What year was your project started? + +2005 + +## Where does your code live: + +http://github.com/git/git + +## Is your organization part of any government? + +No + +## Anything else we should know (optional)? + +We sometimes write about the GSoC in our Git Rev News newsletter +(https://git.github.io/rev_news/archive/). + +# Remarks on the current state of the application + +The 2015 application had a question "If you chose "veteran" in the +organization profile dropdown, please summarize your involvement and +the successes and challenges of your participation. Please also list +your pass/fail rate for each year." with a very detailed answer. diff --git a/SoC-2021-Ideas.md b/SoC-2021-Ideas.md new file mode 100644 index 0000000000..9a69ccb007 --- /dev/null +++ b/SoC-2021-Ideas.md @@ -0,0 +1,64 @@ +--- +layout: default +title: SoC 2021 Ideas +navbar: false +--- + +This is the idea page for Summer of Code 2021 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### Use ref-filter formats in `git cat-file` + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Hariom Verma, Christian Couder + +`git cat-file` has options `--batch[=]` and +`--batch-check[=]` that can take a ``. It would be nice +if the implementation of this `` would use the as much as +possible the same code and syntax as the ref-filter formats. + +Git used to have an old problem of duplicated implementations of some +logic. For example, Git had at least 4 different implementations to +format command output for different commands. Our previous GSoC +students and Outreachy interns unified some of the formatting logic +into [ref-filter](https://github.com/git/git/blob/master/ref-filter.h) +and got rid of similar logic in some command specific files. + +Current task is to continue this work, especially Olga's work (see +) and reuse ref-filter formatting +logic in `git cat-file`. + +### Finish convert `git submodule` script to builtin + + - Language: C, shell (bash) + - Difficulty: medium + - Possible mentors: Christian Couder, Shourya Shukla + +A few components of Git, like `git-submodule.sh`, are still in the +form of shell scripts. This causes problems in production code – in +particular on multiple platforms, e.g. Windows (think: +POSIX-to-Windows path conversion issues). + +The idea of this project is to dive into the Git source code and +finish converting `git-submodule.sh` into portable and performant C +code, making it a so-called "built-in". + +Shourya Shukla is the latest GSoC student to have been working on +this. + +See: + + + diff --git a/SoC-2021-Org-Application.md b/SoC-2021-Org-Application.md new file mode 100644 index 0000000000..74d87e31d1 --- /dev/null +++ b/SoC-2021-Org-Application.md @@ -0,0 +1,291 @@ +--- +layout: default +title: SoC 2021 Organization Application +navbar: false +--- + +This is a draft of git's application to Google's Summer of Code 2021. + + +# Organization Application + +## Why does your org want to participate in Google Summer of Code? + +With the exception of 2013, Git has participated in GSoC every year +since 2007. We have appreciated not only the code contributions (both +new features and internal refactoring to reduce the maintenance +effort), but also the increased project visibility and the addition of +new long-term contributors. We also believe strongly in helping +students become comfortable contributing to open source in general, +even if they do not remain involved with Git itself. + +## What would your org consider to be a successful summer? + +Students enjoying contributing improvements, learning and +participating in the community. It would be even better if they +continue to contribute and are willing to mentor other people after +the Summer. + +## How many potential mentors have agreed to mentor this year? + +dropdown list => 1-5. + +Text below unused: + +``` +We have 3 potential co-mentors this year. This is a small number, and +we expect to take a correspondingly smaller number of projects +(probably only 1). + +All mentors are volunteers for the specific projects that they can +contribute the most to (i.e., ones that meet their interests and +abilities). All mentors are active contributors within the Git +development community, and well-known to the project leadership. + +Active contributors are defined to be those who have submitted and have +had accepted into a shipped release a substantial amount of code, where +substantial is defined to be equal to or larger than what might be +expected of a student working on a Google Summer of Code project. +``` + +## How will you keep mentors engaged with their students? + +We think that the most important part of GSoC is integrating the +students into the normal communication channels used by other project +members. The first step in dealing with disappearing students is to +make sure they are engaging with the community on design and code +issues, and reaching small milestones on the way to the project. Then +if they do disappear, we know quickly and can react, rather than being +surprised at the end. + +If they do disappear, we'll obviously contact them and find out +what's going on. But ultimately, non-communication is grounds for a +failing evaluation, regardless of any code produced. + +We plan to take fewer projects than we have as mentors. We usually +have two co-mentors per students, so that one mentor being unavailable +would have a limited impact on the project. Most of our projects can +be mentored by any of the mentors, and by keeping student progress +public and reviewed on-list, another mentor (or the community at +large) can pick up the slack if needed. + +## How will you help your students stay on schedule to complete their projects? + +There are several ways to do this, and they have been successful in +the past: + +* Prepare students to submit patches before they started. We use a + microproject system prior to the student application where students + must submit at least a patch, and respond to reviews. This means + that on day 1 of their project, students already know how long + review cycles are, and how important it is to work with the + mailing-list. + +* Split the work into small patch series. We don't expect regular + developers to go silent for 3 months and then dump 10,000 lines of + code on us to review, and we don't want students to do that to us + either. Even if the first patch series are only preparatory steps + that do not bring a real added value to Git, it is important to get + them merged as early as possible. Even if the project is not + "completed", useful pieces of code are validated all along the + project. + +## How will you get your students involved in your community during GSoC? + +Students will be required to join the main development mailing list +and post their patches for discussion (in addition to posting their +work as a Git repository on a publicly available server). All current +contributors already do this, so students will be able to see +experienced hands performing the same tasks and learn by example. We +also feel that the list-based discussions will help the student to +become and stay a member of the community. + +Mentors will also exchange direct email with students on at least a +weekly basis. Students will be required to provide weekly progress +reports back to their mentors, so that mentors are aware of the +current difficulties. Progress reports give the mentors a chance to +provide suggestions for problem resolution back to the student. + +Frequent email and IRC interaction with mentors and other developers +will be strongly encouraged by suggesting students post their questions +and ideas to the mailing list, and to discuss them on #git. + +## How will you keep students involved with your community after GSoC? + +Ultimately we have no leverage over the students after they leave, so +the best we can do is to help them form habits of interaction that they +might find rewarding and want to continue with. We specifically don't +want to give the student a "half project" that needs more work after the +GSoC period is done. That's not fair to the student, nor to the project. + +Instead, we'd prefer to get the student involved in the day-to-day of +interacting on the mailing list, reviewing code, and commenting on other +people's ideas and problems. Those are things they can continue to do +after GSoC ends, and those discussions can often spur more coding. + +## Has your org been accepted as a mentor org in Google Summer of Code before? + +### Has your org been accepted as a mentor org in Google Summer of Code before? + +Yes + +### Which years did your org participate in GSoC? + +Every year since 2007 except 2013. + +### How many students did your org accept for 2020? + +3 + +### How many of your org's 2020 students have been active in your community in the past 60 days? + +3 + +### For each year your organization has participated, provide the counts of successful and total students. (e.g. 2016: 3/4) + +2007: 2/3 +2008: 4/6 +2009: 1/2 +2010: 3/4 +2011: 5/5 +2012: 3/3 +2014: 2/3 +2015: 2/2 +2016: 1/1 +2017: 1/1 +2018: 3/3 +2019: 2/2 +2020: 3/3 + +### Is there an organization new to GSoC that you would like to refer to the program for 2021? Feel free to add a few words about why they'd be a good fit. + +(Left blank) + +### If your org has applied for GSoC before but not been accepted, select the years: + +None. + + +### If you are a new organization to GSoC, is there a Google employee or previously participating organization who will vouch for you? If so, please enter their name, contact email, and relationship to your organization. + +(Left blank) + +## What year was your project started? + +2005 + +## Where does your source code live? + +http://github.com/git/git + +## Is your organization part of any government? + +No + +## Anything else we should know (optional)? + +We sometimes write about the GSoC in our Git Rev News newsletter +(https://git.github.io/rev_news/archive/). + + +# Organization Profile + +## Website URL + + + +## Tagline + +fast, scalable, distributed revision control system + +## Logo + +![Git Logo](https://git.github.io/images/Git-Logo-1788C.png) + +## Primary Open Source License + +GNU General Public License version 2.0 (GPL-2.0) + +## Organization Category + +Programming Languages and Development Tools + +## Technology Tags + +c language, shell script, git + +## Topic Tags + +version control, dvcs + +## Ideas List + + + +## Short Description (180 chars max) + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for many workflows. + +## Long Description + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for distributed, non-linear workflows. + +Many large and successful projects use Git, including the Linux +Kernel, Perl, Eclipse, Gnome, KDE, Qt, Ruby on Rails, Android, +PostgreSQL, Debian, and X.org. + +This organization covers projects for +[Git](https://github.com/git/git) itself. Other git-based software or +services are not covered by this organization. + +## Application Instructions + +``` +Guidance for students on how to apply to your organization. Should +include any prerequisites or requirements. You may wish to include a +template or tips for their proposals. May include limited Markdown. +``` + +Please read the "General Application Information" page: +https://git.github.io/General-Application-Information/ + +The primary way to contact the Git community is through the Git +mailing list git@vger.kernel.org. Please discuss your application on +this list. + +## Proposal Tags + +``` + +Enter tags that students can select (one) from and apply to their own +proposals to help organize them. Examples: New Feature, +Optimization. You can also use these to designate "sub-organizations" +if you are an umbrella organization. +``` + +new feature, refactoring, bug fix + +## Contact Methods + +``` +You must complete at least one of the following three contact options. +``` + +Chat: https://git-scm.com/community + +Mailing List: https://git-scm.com/community + +General Email: git@vger.kernel.org + +## Twitter URL (optional) + +(Left blank) + +## Blog URL (optional) + +(Left blank) + diff --git a/SoC-2022-Ideas.md b/SoC-2022-Ideas.md new file mode 100644 index 0000000000..90a0ab1cb6 --- /dev/null +++ b/SoC-2022-Ideas.md @@ -0,0 +1,191 @@ +--- +layout: default +title: SoC 2022 Ideas +navbar: false +--- + +This is the idea page for Summer of Code 2022 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### More Sparse Index Integrations + +The [spare index feature](https://github.blog/2021-11-10-make-your-monorepo-feel-small-with-gits-sparse-index/) +accelerates Git commands when using +[sparse-checkout in cone mode](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/). +This works by modifying the on-disk index file in a way that includes +"sparse directory" entries instead of only file entries. This requires +care when enabling the sparse index for different commands, as custom +logic might be necessary. At minimum, interaction with the sparse index +needs to be carefully tested in the Git test suite when enabling it. + +The most-used commands have already been integrated with the sparse +index feature. This process usually takes a few steps: + +1. Add tests to [`t1092-sparse-checkout-compatibility.sh`](https://github.com/git/git/blob/master/t/t1092-sparse-checkout-compatibility.sh) + for the builtin, with a focus on what happens for paths outside of the + sparse-checkout cone. +2. Disable [the `command_requires_full_index` setting](https://github.com/git/git/blob/master/repository.h#L35) + in the builtin and ensure the tests pass. +3. If the tests do not pass, then alter the logic to work with the sparse index. +4. Add tests to [check that a sparse index stays sparse](https://github.com/git/git/blob/38062e73e009f27ea192d50481fcb5e7b0e9d6eb/t/t1092-sparse-checkout-compatibility.sh#L873-L939). +5. Add [performance tests](https://github.com/git/git/blob/master/t/perf/p2000-sparse-operations.sh) + to demonstrate speedup. + +Here is a list of builtins that could be integrated with the sparse index. +They are generally organized in order of least-difficult to most-difficult. +This allows the student to gain partial success early in the project and +the student can complete as many as possible in the timeframe (without +expectation that _all_ will be completed during the project). + +* `git mv` +* `git rm` +* `git grep` +* `git rev-parse` +* `git fsck` +* `git check-attr` +* `git describe` +* `git diff-files` +* `git diff-index` +* `git diff-tree` +* `git worktree` +* `git write-tree` +* `git apply` +* `git am` +* `git checkout--worker` (for parallel checkout) +* `git merge-index` +* `git rerere` + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Derrick Stolee < > +* Victoria Dye < > + +### Unify ref-filter formats with other pretty formats + +Git has an old problem of duplicated implementations of some +logic. For example, Git had at least 4 different implementations to +format command output for different commands. + +Our previous GSoC students and Outreachy interns unified some of the +formatting logic into +[ref-filter](https://github.com/git/git/blob/master/ref-filter.h) and +got rid of similar logic in some command specific files. Current task +is to continue this work and reuse ref-filter formatting logic in +[pretty](https://github.com/git/git/blob/master/pretty.h). + +See: + + - this discussion + - Hariom Verma's GSoC 2020 final report + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Christian Couder < > +* Hariom Verma < > + +### Reachability bitmap improvements + +[Reachability bitmaps][vmg-bitmaps] allow Git to quickly answer queries about +which objects are reachable from a given commit. Instead of a commits parents +and its root tree recursively, we can use a precomputed set of objects encoded +as a bit-string and stored in a `.bitmap` file to answer the query near +instantaneously. + +There are a couple of areas where bitmap performance itself could be improved: + + - Individual bitmaps are stored compressed (with [EWAH][ewah]), but we have + some sense that it can be slow to decompress individual bitmaps (which we + have to do in order to read them, but also to do things like negate them, OR + and AND them together, etc). + + One possible project could be to explore using an alternative compression + scheme (like the more modern [Roaring+Run][roaring-run] technique) to see if + we can improve overall bitmap performance by reducing the amount of time it + takes to read an individual bitmap. + + This project would entail designing a suite of performance tests, along with + any necessary changes to the `.bitmap` format necessary to accommodate the + new compression scheme, making those changes, and then running the + performance tests to measure the resulting speed-up. + + - Loading a `.bitmap` file can be slow for large bitmaps. This is because we + have to read the file sequentially in order to discover the offset of each + bitmap within the file. + + It should be possible to shave off some time from this step by including a + small "table of contents" that indicates which commits have bitmaps, and + where to find them in the `.bitmap` file. In the past [some efforts have + been made][ttaylorr-commit-table] to do this. But we should undertake more + performance testing to prove whether this is or isn't a good idea before + submitting a patch series in this area. + + - [Recent changes][ttaylorr-bitmaps] have made it possible to repack a + repository's objects into a sequence of packs whose object count forms a + geometric progression (e.g., if the first pack has `N` objects, the next + pack will have at least `2N` objects, then `4N` objects and so on). + + But even when repacking a repository in this way, regenerating its bitmaps + can still take a long time. One possible approach to this would be a new + mode of generating bitmaps that is more "incremental" in nature. In other + words, a mode which only adds new bitmaps for commits introduced between + successive bitmap generations. + + Because of how individual bitmaps are generated, this will result in only + having to traverse objects between the new bitmap tips and old ones, + resulting in overall faster bitmap generation. + + Like the above, this project would involve designing a set of performance + tests, implementing the changes required to introduce this new type of + bitmap generation, and then running those tests against your new code. + + - Other (larger, longer-term) ideas include: rethinking how we select which + commits receive bitmaps (and/or having bitmaps represent multiple commits + instead of just one to "summarize" small sets of commits), or improving how + we handle queries that use a bitmap but do not have complete coverage. + GSoC students should consider these projects more advanced, and thus they + are not explained in as much detail here. Instead, this point serves to + illustrate that there are opportunities to explore larger projects should we + decide they are more interesting than the above or we have time to take them + on. + +This project will give GSoC students a broad overview of reachability bitmaps, +with the goal of improving their performance in some way or another. Students +can expect hands-on mentorship, but will have the agency to pick one or more of +the above sub-projects (or create their own!) that interests them most. + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell + +Possible mentors: +* Taylor Blau < > +* Kaartic Sivaraam < > + +[vmg-bitmaps]: https://github.blog/2015-09-22-counting-objects/ +[ewah]: https://arxiv.org/abs/0901.3751 +[roaring-run]: https://roaringbitmap.org/about/ +[ttaylorr-commit-table]: https://lore.kernel.org/git/YNuiM8TR5evSeNsN@nand.local/ +[ttaylorr-bitmaps]: https://github.blog/2021-04-29-scaling-monorepo-maintenance/ diff --git a/SoC-2022-Microprojects.md b/SoC-2022-Microprojects.md new file mode 100644 index 0000000000..6def7c11d8 --- /dev/null +++ b/SoC-2022-Microprojects.md @@ -0,0 +1,139 @@ +--- +layout: default +title: SoC 2022 Applicant Microprojects +navbar: false +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Replace a run_command*() call by direct calls to C functions + +See for example what Junio did in +[ffcb4e94d3](https://github.com/git/git/commit/ffcb4e94d3) (bisect: do +not run show-branch just to show the current commit, 2021-07-27). + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid suppressing `git`'s exit code in test scripts + +The Git project uses a large collection of integration tests written in +Shell to guard against regressions when adding new features or fixing +bugs. The scripts in question can be found in the `t` directory +[here][git-t]. + +While it is perfectly OK to use [pipes][wikipedia-pipes] when writing +integration tests, we must be careful to avoid writing a pipeline that +suppresses the exit code of a Git process, like so: + +``` +git | +``` + +...since the exit code of `git ` would be suppressed by the +pipe. If `git ` crashed, we would not catch it in the above +example when running the integration suite. + +Other examples to avoid include: + +``` +# bad: + $(git ) + +# also bad: + <) +EOF +``` + +...since the exit code of `git ` is hidden behind the +subshell in both instances. + +On the other hand, both of the following examples are OK, since neither +hides the exit code of running `git `: + +``` +# good: +var=$(git ) + +# also good: + | | git +``` + +(provided that neither `` or `` are +`git`). + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +[git-t]: https://github.com/git/git/tree/master/t +[wikipedia-pipes]: https://en.wikipedia.org/wiki/Pipeline_(Unix) + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Modernize a test script + +A number of our test scripts have been written a long time ago in a +style that is now outdated. + +In the following email it is explained in details how to modernize and +clean up the t7001 test script: + + + +t7001 is not the only test script where similar changes could be made +though. + +Find one test script that needs some of the same changes and make +them. Please make sure that the test script is not already being +worked on by asking on the mailing list before starting to work on it. + +There should be only one kind of change per commit. For example if one +of your commits indents test bodies with TABs, instead of spaces, then +this should be the only kind of change in this commit. diff --git a/SoC-2022-Org-Application.md b/SoC-2022-Org-Application.md new file mode 100644 index 0000000000..ed563e7aab --- /dev/null +++ b/SoC-2022-Org-Application.md @@ -0,0 +1,228 @@ +--- +layout: default +title: SoC 2022 Organization Application +--- + +This is a draft of git's application to Google's Summer of Code 2022. + +# Initial form + +## Organization Name + +Git + +## Is this organization an established Open Source project or organization that releases code under an OSI approved license ? An OSI License is required for program participation. + +Yes + +## Has your organization participated in Google Summer of Code before? + +Yes + +## Please select all years in which your organization participated prior to 2022. + +Every year since 2007 except 2013. + +## [Agreement](https://summerofcode.withgoogle.com/terms/org) + +Accepted + + +# Organization Profile + +## Website URL for Organization + +https://git-scm.com/ + + +## Logo + +![Git Logo](/images/Git-Logo-1788C.png) + + +## Tagline + +fast,scalable,distributed revision control system + + +## Primary Open Source License + +GNU General Public License version 2.0 (GPL-2.0) + + +## When year was your project started? + +2005 + + +## Link to your source code location + +http://github.com/git/git + + +## Organization Categories + +Programming Languages and Development Tools + + +## Technology tags + +c language, shell script, git + + +## Topic Tags + +version control, dvcs + + +## Organization Description + +Git is the most widely-used revision control system in Open Source. It +is a distributed system with an emphasis on speed, data integrity, and +support for distributed, non-linear workflows. + +Many large and successful projects use Git, including the Linux +Kernel, Perl, Eclipse, Gnome, KDE, Qt, Ruby on Rails, Android, +PostgreSQL, Debian, and X.org. + +This organization covers projects for +[Git](https://github.com/git/git) itself. Other git-based software or +services are not covered by this organization. + + +## Contributor Guidance + +https://git.github.io/General-Application-Information/ + + +## Communication Methods + +Chat: https://git-scm.com/community + +Mailing List / Forum: https://git-scm.com/community + +General Email: git@vger.kernel.org + + +# Organization Questionnaire + +## Why does your org want to participate in Google Summer of Code? + +With the exception of 2013, Git has participated in GSoC every year +since 2007. We have appreciated not only the code contributions (both +new features and internal refactoring to reduce the maintenance +effort), but also the increased project visibility and the addition of +new long-term contributors. We also believe strongly in helping +students become comfortable contributing to open source in general, +even if they do not remain involved with Git itself. + + +## What would your organization consider to be a successful GSoC program? + +Students enjoying contributing improvements, learning and +participating in the community. It would be even better if they +continue to contribute and are willing to mentor other people after +the Summer. + + +## How will you keep mentors engaged with their students? + +We think that the most important part of GSoC is integrating the +students into the normal communication channels used by other project +members. The first step in dealing with disappearing students is to +make sure they are engaging with the community on design and code +issues, and reaching small milestones on the way to the project. Then +if they do disappear, we know quickly and can react, rather than being +surprised at the end. + +If they do disappear, we'll obviously contact them and find out +what's going on. But ultimately, non-communication is grounds for a +failing evaluation, regardless of any code produced. + +We plan to take fewer projects than we have as mentors. We usually +have two co-mentors per students, so that one mentor being unavailable +would have a limited impact on the project. Most of our projects can +be mentored by any of the mentors, and by keeping student progress +public and reviewed on-list, another mentor (or the community at +large) can pick up the slack if needed. + + +## How will you help your students stay on schedule to complete their projects? + +There are several ways to do this, and they have been successful in +the past: + +* Prepare students to submit patches before they started. We use a + microproject system prior to the student application where students + must submit at least a patch, and respond to reviews. This means + that on day 1 of their project, students already know how long + review cycles are, and how important it is to work with the + mailing-list. + +* Split the work into small patch series. We don't expect regular + developers to go silent for 3 months and then dump 10,000 lines of + code on us to review, and we don't want students to do that to us + either. Even if the first patch series are only preparatory steps + that do not bring a real added value to Git, it is important to get + them merged as early as possible. Even if the project is not + "completed", useful pieces of code are validated all along the + project. + + +## How will you get your students involved in your community during GSoC? + +Students will be required to join the main development mailing list +and post their patches for discussion (in addition to posting their +work as a Git repository on a publicly available server). All current +contributors already do this, so students will be able to see +experienced hands performing the same tasks and learn by example. We +also feel that the list-based discussions will help the student to +become and stay a member of the community. + +Mentors will also exchange direct email with students on at least a +weekly basis. Students will be required to provide weekly progress +reports back to their mentors, so that mentors are aware of the +current difficulties. Progress reports give the mentors a chance to +provide suggestions for problem resolution back to the student. + +Frequent email and IRC interaction with mentors and other developers +will be strongly encouraged by suggesting students post their questions +and ideas to the mailing list, and to discuss them on #git. + + +## Anything else we should know (optional)? + +We sometimes write about the GSoC in our Git Rev News newsletter +(https://git.github.io/rev_news/archive/). + + +## Is your organization part of any government? + +No + + +# Program Application + +## Ideas List URL + + + + +## Mentors + +``` +How many Mentors does your Organization have available to participate in this program? +``` + +5 + + +### How many students did your org accept for 2021? + +2 + + +### How many of your org's 2021 students are active today? + +1 + diff --git a/SoC-2023-Ideas.md b/SoC-2023-Ideas.md new file mode 100644 index 0000000000..582cfcd75c --- /dev/null +++ b/SoC-2023-Ideas.md @@ -0,0 +1,101 @@ +--- +layout: default +title: SoC 2023 Ideas +navbar: false +--- + +This is the idea page for Summer of Code 2023 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### More Sparse Index Integrations + +The [spare index feature](https://github.blog/2021-11-10-make-your-monorepo-feel-small-with-gits-sparse-index/) +accelerates Git commands when using +[sparse-checkout in cone mode](https://github.blog/2020-01-17-bring-your-monorepo-down-to-size-with-sparse-checkout/). +This works by modifying the on-disk index file in a way that includes +"sparse directory" entries instead of only file entries. This requires +care when enabling the sparse index for different commands, as custom +logic might be necessary. At minimum, interaction with the sparse index +needs to be carefully tested in the Git test suite when enabling it. + +The most-used commands have already been integrated with the sparse +index feature. This process usually takes a few steps: + +1. Add tests to [`t1092-sparse-checkout-compatibility.sh`](https://github.com/git/git/blob/master/t/t1092-sparse-checkout-compatibility.sh) + for the builtin, with a focus on what happens for paths outside of the + sparse-checkout cone. +2. Disable [the `command_requires_full_index` setting](https://github.com/git/git/blob/master/repository.h#L35) + in the builtin and ensure the tests pass. +3. If the tests do not pass, then alter the logic to work with the sparse index. +4. Add tests to [check that a sparse index stays sparse](https://github.com/git/git/blob/38062e73e009f27ea192d50481fcb5e7b0e9d6eb/t/t1092-sparse-checkout-compatibility.sh#L873-L939). +5. Add [performance tests](https://github.com/git/git/blob/master/t/perf/p2000-sparse-operations.sh) + to demonstrate speedup. + +Here is a list of builtins that could be integrated with the sparse index. +They are generally organized in order of least-difficult to most-difficult. +This allows the student to gain partial success early in the project and +the student can complete as many as possible in the timeframe (without +expectation that _all_ will be completed during the project). + +* `git describe` +* `git write-tree` +* `git diff-files` +* `git diff-index` +* `git diff-tree` +* `git worktree` +* `git check-attr` +* `git checkout--worker` (for parallel checkout) +* `git apply` +* `git am` +* `git fsck` +* `git merge-index` +* `git rerere` + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentor: Victoria Dye < > + +### Unify ref-filter formats with other pretty formats + +Git has an old problem of duplicated implementations of some +logic. For example, Git had at least 4 different implementations to +format command output for different commands. + +Our previous GSoC students and Outreachy interns unified some of the +formatting logic into +[ref-filter](https://github.com/git/git/blob/master/ref-filter.h) and +got rid of similar logic in some command specific files. Current task +is to continue this work and reuse ref-filter formatting logic in +[pretty](https://github.com/git/git/blob/master/pretty.h). + +See: + + - this discussion + - Hariom Verma's GSoC 2020 final report + - Nsengiyumva Wilberforce's recent work on this + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Christian Couder < > +* Hariom Verma < > + diff --git a/SoC-2024-Ideas.md b/SoC-2024-Ideas.md new file mode 100644 index 0000000000..041eba592c --- /dev/null +++ b/SoC-2024-Ideas.md @@ -0,0 +1,207 @@ +--- +layout: default +title: SoC 2024 Ideas +navbar: false +--- + +![git logo >](https://git-scm.com/images/logos/downloads/Git-Logo-2Color.svg) + +This is the idea page for Summer of Code 2024 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### Note about limit of project selection + +Kindly note that considering the bandwidth of available mentors, the +Git project would only mentor up to 3 contributors this year. + +This is not a hard and fast rule. It may change if more community members are +willing to mentor in the coming days. For instance, this may happen when +a new project is proposed and some community member volunteers to mentor +the same. + +### Move existing tests to a unit testing framework + +Git has a lot of test cases that need to be migrated to use a new unit +testing framework. This typically involves moving code from both: + + - a "t/helper/test-*.c" test helper in C, and + - a "t/*.sh" test script in shell that invokes the test helper + +over to a single "t/unit-tests/t-*.c" in C using the unit testing +framework. + +Our Outreachy intern ported some of the unit tests. + +**Note**: Owing to additional care needed to convert +reftable unit tests in `t0032-reftable-unittest.sh`, +it is covered as a separate project below. +So, this project solely focuses on unit tests _other than_ +the reftable ones. + +- See: + + - this discussion + - + - + - + - + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Christian Couder < > +* Kaartic Sivaraam < > + +### Convert reftable unit tests to use the unit testing framework + +The "reftable" unit tests in `t0032-reftable-unittest.sh` +predate the unit testing framework that was recently +introduced into Git. These tests should be converted to use +the new framework. + +See: + + - this discussion + - + - + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Low + +Languages: C, shell(bash) + +Possible mentors: +* Patrick Steinhardt < > +* Karthik Nayak < > +* Christian Couder < > + +### Implement consistency checks for refs + +The git-fsck(1) command is used to check various data +structures for consistency. Notably missing though are +consistency checks for the refdb. While git-fsck(1) +implicitly checks some of the properties of the refdb +because it uses its refs for a connectivity check, these +checks aren't sufficient to properly ensure that all refs +are properly consistent. + +The goal of this project would be to introduce consistency +checks that can be implemented by the ref backend. Initially +these checks may only apply to the "files" backend. With the +ongoing efforts to upstream a new "reftable" backend the +effort may be extended. + +See: + + - + - + - + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Patrick Steinhardt < > +* Karthik Nayak < > + +### Refactor git-bisect(1) to make its state self-contained + +The git-bisect(1) command is used to find a commit in a +range of commits that introduced a specific bug. Starting a +bisection run creates a set of state files into the Git +repository which record various different parameters like +".git/BISECT_START". These files look almost like refs +due to their names being all-uppercase. This has led to +confusion with the new "reftable" backend because it wasn't +quite clear whether those files are in fact refs or not. + +As it turns out they are not refs and should never be +treated like one. Overall, it has been concluded that the +way those files are currently stored is not ideal. Instead +of having a proliferation of files in the Git directory, it +was discussed whether the bisect state should be moved into +its own "bisect-state" subdirectory. This would make it more +self-contained and thereby avoid future confusion. It is +also aligned with the sequencer state used by rebases, which +is neatly contained in the "rebase-apply" and "rebase-merge" +directories. + +The goal of this project would be to realize this change. +While rearchitecting the layout should be comparatively easy +to do, the harder part will be to hash out how to handle +backwards compatibility. + +See: + + - + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Patrick Steinhardt < > +* Karthik Nayak < > +* Christian Couder < > + +### Implement support for reftables in "dumb" HTTP transport + +Fetching Git repositories uses one of two major protocols: + + - The "dumb" protocol works without requiring any kind of + interactive negotiation like a CGI module. It can thus + be served by a static web server. + + - The "smart" protocol works by having the client and + server exchange multiple messages with each other. It is + more efficient, but requires support for Git in the + server. + +While almost all servers nowadays use the "smart" protocol, +there are still some that use the "dumb" protocol. + +The "dumb" protocol cannot serve repositories which use the +"reftable" backend though. While there exists a "info/refs" +file that is supposed to be backend-agnostic, this file does +not contain information about the default branch. Instead, +clients are expected to download the "HEAD" file and derive +the default branch like that. This file is a mere stub in +the "reftable" backend though, which breaks this protocol. + +The goal of this project is to implement "reftable" support +for "dumb" fetches. + +See: + + - + +Expected Project Size: 175 hours or 350 hours + +Difficulty: Medium + +Languages: C, shell(bash) + +Possible mentors: +* Patrick Steinhardt < > +* Karthik Nayak < > diff --git a/SoC-2024-Microprojects.md b/SoC-2024-Microprojects.md new file mode 100644 index 0000000000..c832f49f30 --- /dev/null +++ b/SoC-2024-Microprojects.md @@ -0,0 +1,144 @@ +--- +layout: default +title: SoC 2024 Applicant Microprojects +navbar: false +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Replace a run_command*() call by direct calls to C functions + +See for example what Junio did in +[ffcb4e94d3](https://github.com/git/git/commit/ffcb4e94d3) (bisect: do +not run show-branch just to show the current commit, 2021-07-27). + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Use `test_path_is_*` functions in test scripts + +Find one test script that verifies the presence/absence of +files/directories with 'test -(e|f|d|...)' and replace them with the +appropriate `test_path_is_file`, `test_path_is_dir`, etc. helper +functions. Note that this conversion does not directly apply to control +flow constructs like `if test -e ./path; then ...; fi` because the +replacements are intended to assert the condition instead of merely +testing for it. Check [this link](https://public-inbox.org/git/CAPig+cRfO8t1tdCL6MB4b9XopF3HkZ==hU83AFZ38b-2zsXDjQ@mail.gmail.com/) +for an elaborate clarification on identifying `test -e` +instances that should / should not be replaced. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid suppressing `git`'s exit code in test scripts + +The Git project uses a large collection of integration tests written in +Shell to guard against regressions when adding new features or fixing +bugs. The scripts in question can be found in the `t` directory +[here][git-t]. + +While it is perfectly OK to use [pipes][wikipedia-pipes] when writing +integration tests, we must be careful to avoid writing a pipeline that +suppresses the exit code of a Git process, like so: + +``` +git | +``` + +...since the exit code of `git ` would be suppressed by the +pipe. If `git ` crashed, we would not catch it in the above +example when running the integration suite. + +Other examples to avoid include: + +``` +# bad: + $(git ) + +# also bad: + <) +EOF +``` + +...since the exit code of `git ` is hidden behind the +subshell in both instances. + +On the other hand, both of the following examples are OK, since neither +hides the exit code of running `git `: + +``` +# good: +var=$(git ) + +# also good: + | | git +``` + +(provided that neither `` or `` are +`git`). + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +[git-t]: https://github.com/git/git/tree/master/t +[wikipedia-pipes]: https://en.wikipedia.org/wiki/Pipeline_(Unix) + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Modernize a test script + +A number of our test scripts have been written a long time ago in a +style that is now outdated. + +In the following email it is explained in details how to modernize and +clean up the t7001 test script: + + + +t7001 is not the only test script where similar changes could be made +though. + +Find one test script that needs some of the same changes and make +them. Please make sure that the test script is not already being +worked on by asking on the mailing list before starting to work on it. + +There should be only one kind of change per commit. For example if one +of your commits indents test bodies with TABs, instead of spaces, then +this should be the only kind of change in this commit. diff --git a/SoC-2025-Ideas.md b/SoC-2025-Ideas.md new file mode 100644 index 0000000000..fac121ab43 --- /dev/null +++ b/SoC-2025-Ideas.md @@ -0,0 +1,172 @@ +--- +layout: default +title: SoC 2025 Ideas +--- + +![git logo >](https://git-scm.com/images/logos/downloads/Git-Logo-2Color.svg) + +This is the idea page for Summer of Code 2025 for Git. + +*Please completely read the [general application information](https://git.github.io/General-Application-Information) +page before reading the idea list below.* + +## Summer of code main project ideas + +**Students**: Please consider these ideas as starting points for +generating proposals. We are also more than happy to receive proposals +for other ideas related to Git. Make sure you have read the "Note +about refactoring projects versus projects that implement new +features" in the [general application information](https://git.github.io/General-Application-Information) +page though. + +### Note about limit of project selection + +Kindly note that considering the bandwidth of available mentors, the +Git project would only mentor up to 3 contributors this year. + +This is not a hard and fast rule. It may change if more community members are +willing to mentor in the coming days. For instance, this may happen when +a new project is proposed and some community member volunteers to mentor +the same. + + +### Consolidate ref-related functionality into git-refs + +This project aims to streamline Git's reference management into the existing +`git-refs` command by consolidating functionality currently spread +across multiple commands. The new command will provide subcommands for listing, +getting, checking existence, writing, and optimizing references, replacing the +functionality currently handled by git-update-ref(1), git-for-each-ref(1), +git-show-ref(1), and git-pack-refs(1). + +The consolidation work should ensure backward compatibility with existing +commands. The work involves C programming in Git's codebase, creating +comprehensive tests, and updating documentation. + +Required skills include C programming, familiarity with Git's codebase, and experience with command-line tool development. The project is expected to take 12 weeks, with existing commands being maintained for backward compatibility while development focuses on the new unified interface. + +Getting started: Build Git from source, study the existing ref-related commands, and submit a micro-patch to demonstrate familiarity with the codebase. + +_Expected Project Size_: 175 hours or 350 hours + +_Difficulty_: Medium + +_Languages_: C, shell(bash) + +_Possible mentors_: + +* Patrick Steinhardt < > +* Jialuo She < > +* Christian Couder < > +* Ghanshyam Thakkar < > + + +### Refactoring in order to reduce Git's global state + +This project focuses on modernizing Git's environment handling by refactoring +the `environment.c` code to reduce global state. The goal is to move environment +variables and configuration from global scope into more appropriate local +contexts, primarily into the `struct repository` / `struct repository_settings` +structure. This architectural improvement will make the codebase more +maintainable and potentially enable better multi-repository handling in the +future. The project involves careful refactoring of Git's core environment +handling code, requiring strong C programming skills and attention to detail. + +The student will identify global variables that can be moved to local scope, +implement the necessary structural changes, and ensure all affected code paths +continue to work correctly. This includes updating tests, fixing any +regressions, and documenting the architectural changes. + +_Expected Project Size_: 90 or 175 hours or 350 hours + +_Difficulty_: Medium + +_Languages_: C, shell(bash) + +_Possible mentors_: + +* Patrick Steinhardt < > +* Karthik Nayak < > +* Jialuo She < > +* Christian Couder < > +* Ghanshyam Thakkar < > + + +### Machine-Readable Repository Information Query Tool + +This project aims to create a new Git command dedicated to querying repository +metadata and configuration in a structured, machine-readable format. Currently, +much of this functionality exists within git-rev-parse(1), which has evolved +beyond its original purpose. The new command will provide a cleaner, more +focused interface for programmatically accessing repository information using +JSON output. + +The student will design and implement this new command, focusing on identifying +what repository information should be exposed, designing a consistent JSON +schema, and implementing the necessary interfaces to Git's internal APIs. Key +challenges include determining which subset of information from git-rev-parse to +expose via this new command, ensuring backward compatibility, and creating a +clean, well-documented command interface that's useful for scripts and tools. + +While this is an exploratory project that hasn't been extensively discussed in +the Git community, it addresses a real need for better programmatic access to +repository information. + +_Expected Project Size_: 175 hours or 350 hours + +_Difficulty_: Medium + +_Languages_: C, shell(bash) + +_Possible mentors_: + +* Patrick Steinhardt < > +* Karthik Nayak < > +* Ghanshyam Thakkar < > + + +### Implement support for reftables in "dumb" HTTP transport + +Fetching Git repositories uses one of two major protocols: + + - The "dumb" protocol works without requiring any kind of + interactive negotiation like a CGI module. It can thus + be served by a static web server. + + - The "smart" protocol works by having the client and + server exchange multiple messages with each other. It is + more efficient, but requires support for Git in the + server. + +While almost all servers nowadays use the "smart" protocol, +there are still some that use the "dumb" protocol. + +The "dumb" protocol cannot serve repositories which use the +"reftable" backend though. While there exists a "info/refs" +file that is supposed to be backend-agnostic, this file does +not contain information about the default branch. Instead, +clients are expected to download the "HEAD" file and derive +the default branch like that. This file is a mere stub in +the "reftable" backend though, which breaks this protocol. + +The goal of this project is to implement "reftable" support +for "dumb" fetches. + +See: + + - + +**Note**: While both ideas are valuable, we prioritize the 'Consolidate ref-related +functionality into git-refs' proposal over support for reftables in "dumb" HTTP transport. If we receive applications for both +projects, preference will be given to applications focusing on the git-refs +consolidation work. + +_Expected Project Size_: 175 hours or 350 hours + +_Difficulty_: Medium + +_Languages_: C, shell(bash) + +_Possible mentors_: +* Patrick Steinhardt < > +* Karthik Nayak < > diff --git a/SoC-2025-Microprojects.md b/SoC-2025-Microprojects.md new file mode 100644 index 0000000000..5a5db49eae --- /dev/null +++ b/SoC-2025-Microprojects.md @@ -0,0 +1,181 @@ +--- +layout: default +title: SoC 2025 Applicant Microprojects +--- + +## Introduction + +First make sure you read and understand +[our general guidelines and suggestions for microprojects](https://git.github.io/General-Microproject-Information). + +There are some suggestions on how you can find some microprojects on your own in the document. + +## Ideas for microprojects + +### Modernize Test Path Checking in Git's Test Suite + +Help improve Git's test suite by converting old-style path checks to use modern +helper functions. We'll be replacing basic shell test commands like `test -f` +with Git's dedicated test helpers like `test_path_is_file`. + +#### Steps to Complete +1. Find a test script using old-style path checks: + ```sh + git grep "test -[efd]" t/ + ``` + +2. Look for patterns like: + ```sh + test -f path/to/file # old way + test_path_is_file path/to/file # new way + + test -d some/directory # old way + test_path_is_dir some/directory # new way + ``` + +3. Important: Only replace checks that are actually testing for conditions, not + those used in flow control. For example: + ```sh + # DON'T change this - it's flow control + if test -e "file.txt"; then + do_something + fi + + # DO change this - it's a test assertion + test -e "file.txt" || error "file.txt should exist" + ``` + +#### Notes +- Start small: Pick a test file with just a few instances to convert +- Run the test suite after your changes to ensure nothing breaks +- Follow Git's commit message style +- Include which command you used to find the instances in your commit message + +#### Need Help? +- Reference [this discussion](https://public-inbox.org/git/CAPig+cRfO8t1tdCL6MB4b9XopF3HkZ==hU83AFZ38b-2zsXDjQ@mail.gmail.com/) + for detailed examples. +- If you can't find any instances to fix, let us know what search command you + used + + +### Add more builtin patterns for userdiff + +"git diff" shows the function name corresponding to each hunk after +the @@ ... @@ line. For common languages (C, HTML, Ada, Matlab, ...), +the way to find the function name is built-in Git's source code as +regular expressions (see userdiff.c). A few languages are common +enough to deserve a built-in driver, but are not yet recognized. For +example, shell. + +This project requires a very good knowledge of regular expressions. + +It is easy though to find examples of how this can be done by +searching the code base and the mailing list archive, as this has +already been done for a number of languages. + +### Replace a run_command*() call by direct calls to C functions + +See for example what Junio did in +[ffcb4e94d3](https://github.com/git/git/commit/ffcb4e94d3) (bisect: do +not run show-branch just to show the current commit, 2021-07-27). + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +### Avoid suppressing `git`'s exit code in test scripts + +The Git project uses a large collection of integration tests written in +Shell to guard against regressions when adding new features or fixing +bugs. The scripts in question can be found in the `t` directory +[here][git-t]. + +While it is perfectly OK to use [pipes][wikipedia-pipes] when writing +integration tests, we must be careful to avoid writing a pipeline that +suppresses the exit code of a Git process, like so: + +``` +git | +``` + +...since the exit code of `git ` would be suppressed by the +pipe. If `git ` crashed, we would not catch it in the above +example when running the integration suite. + +Other examples to avoid include: + +``` +# bad: + $(git ) + +# also bad: + <) +EOF +``` + +...since the exit code of `git ` is hidden behind the +subshell in both instances. + +On the other hand, both of the following examples are OK, since neither +hides the exit code of running `git `: + +``` +# good: +var=$(git ) + +# also good: + | | git +``` + +(provided that neither `` or `` are +`git`). + +See the commit +[c6f44e1da5](https://github.com/git/git/commit/c6f44e1da5e88e34) +for example, and then do the same thing in one other test script. + +If you can't find one please tell us, along with the command you used +to search, so that we can remove this microproject idea. + +[git-t]: https://github.com/git/git/tree/master/t +[wikipedia-pipes]: https://en.wikipedia.org/wiki/Pipeline_(Unix) + +### Use unsigned integral type for collection of bits. + +Pick one field of a structure that (1) is of signed integral type and (2) is +used as a collection of multiple bits. Discuss if there is a good reason +why it has to be a signed integral field and change it to an unsigned +type otherwise. [[thread](https://public-inbox.org/git/xmqqsiebrlez.fsf@gitster.dls.corp.google.com)] + +Even though the amount of code to write is small, these projects +involve a lot of prior work to understand the specification and deal +with all potential corner-cases. + +### Modernize a test script + +A number of our test scripts have been written a long time ago in a +style that is now outdated. + +In the following email it is explained in details how to modernize and +clean up the t7001 test script: + + + +t7001 is not the only test script where similar changes could be made +though. + +Find one test script that needs some of the same changes and make +them. Please make sure that the test script is not already being +worked on by asking on the mailing list before starting to work on it. + +There should be only one kind of change per commit. For example if one +of your commits indents test bodies with TABs, instead of spaces, then +this should be the only kind of change in this commit. + +#### Notes +- only work on `t/t????-*.sh` scripts. +- pick just one script (so as to avoid exhausting the pool for other candidates). +- When converting `test -[def]` to use `test_path_exists()` and cousins + only convert instances which semantically are assertions (i.e. used as part + of a &&-chain). diff --git a/_config.yml b/_config.yml index 7633f45e70..f3e563f9aa 100644 --- a/_config.yml +++ b/_config.yml @@ -1,2 +1,4 @@ name: Git Developer Pages permalink: /rev_news/:year/:month/:day/:title/ +plugins: + - jekyll-redirect-from \ No newline at end of file diff --git a/_includes/README.md b/_includes/README.md index d7ab46aeb0..d70f2c116c 100644 --- a/_includes/README.md +++ b/_includes/README.md @@ -1,29 +1,22 @@ -# About - -This homepage is maintained by editing files in the -[git/git.github.io](https://github.com/git/git.github.io) repository on -GitHub. - -It is meant to be edited collaboratively like a wiki, except that -instead of a web form, you get to use a text editor and git. What could -be better? - -If you want push access, contact peff@peff.net and provide your GitHub -username. You may also send patches by mail (and feel free to cc -git@vger.kernel.org if appropriate). - - -# Development - -* Make sure you've got ruby2 with dev-packages installed -* `sudo gem install bundler` -* Clone this repo -* `sudo apt-get install zlib1g-dev` # ref [1] -* `bundle install` -* `bundle exec jekyll serve` -* browse the site on http://localhost:4000 - -Based on https://help.github.com/articles/using-jekyll-with-pages/ - -[1] http://www.nokogiri.org/tutorials/installing_nokogiri.html#ubuntu___debian - +This is a website for information on Git development. If you stumbled into this +by mistake, you may want: + - Information on running Git and links to download the latest version from + [HERE](https://git-scm.com/) + - Wiki that has historically contained developer information from + [HERE](https://git.wiki.kernel.org/index.php/Main_Page) + +These pages are intended to collect information useful to Git developers. This +is also the web home of: + - the [Hacking Git](https://git.github.io/Hacking-Git/) page, + - the [Git Rev News newsletter](https://git.github.io/rev_news/), + - the [involvement of the Git project in mentoring + programs](https://git.github.io/General-Application-Information/) like + [Outreachy](https://www.outreachy.org/) and the [GSoC (Google Summer of + Code)](https://summerofcode.withgoogle.com/) + +These pages are intended to be edited collaboratively (i.e., it is an +alternative to us having a wiki, but one that is edited entirely via Git pushes. +The [repository](https://github.com/git/git.github.io) could be found on GitHub. +You could also send your changes as patches by email to Christian Couder < + > / Kaartic Sivaraam < > +(and feel free to cc git@vger.kernel.org if appropriate). diff --git a/_includes/navbar.html b/_includes/navbar.html index 6d52b36c9f..d4dfe25bda 100644 --- a/_includes/navbar.html +++ b/_includes/navbar.html @@ -1,7 +1,6 @@