On Fri, Oct 25, 2024 at 6:56 PM Samuel Abraham <abrahamadekunle50@xxxxxxxxx> wrote: > > On Fri, Oct 25, 2024 at 2:22 PM Samuel Abraham > <abrahamadekunle50@xxxxxxxxx> wrote: > > > > On Fri, Oct 25, 2024 at 11:04 AM Patrick Steinhardt <ps@xxxxxx> wrote: > > > > > > On Wed, Oct 23, 2024 at 10:45:52PM +0100, Samuel Abraham wrote: > > > > > > Thanks for your application! > > > > > > > ## Project Overview - Convert unit test to use the Clar testing framework: > > > > > > > > I understand that the Git project is in the process of converting its > > > > unit tests to the Clar testing framework to improve test readability, > > > > consistency and maintainability, a move away from homegrown unit test > > > > frameworks such as t/helper/test-tool.h and t/unit-test/test-lib.h. > > > > > > Nit: we've basically moved away from test-tool for unit tests already, > > > to the best of my knowledge. So this is more about the second part, > > > moving away from our own test framework. > > > > Thank you very much for the clarity. > > > > > > > Clar provides a structured and efficient way to write and execute > > > > tests and is well-suited for a project like Git where robust testing > > > > is essential to maintain quality and stability. > > > > > > It would be nice to provide some pointers _why_ we think that clar is > > > better suited ;) Hint: you may have a look at the patch series that > > > introduced the clar for some ideas there. > > > > Okay I will do that. > > > > > > > > [snip] > > > > ## Project Plan: > > > > > > Formatting of this section is a bit funky, which makes it harder than > > > necessary to figure out which parts belong together. I'd propose to > > > first provide a high-level list of the steps you want to do with a > > > bulleted list and then maybe put more detailed explanations into > > > separate "### subsections". You may also want to convert links to use > > > [Markdown syntax](https://www.markdownguide.org/basic-syntax/#links), > > > which provides some structure aronud them. > > > > Okay thank you for this. > > > > > > > The first steps to migrating existing tests to Clar would be studying > > > > existing tests in the t/helper and t/unit-tests directory which will > > > > enable me to determine those appropriate for conversion. > > > > > > > > Liaise with mentors and community members to determine the viability > > > > of converting the selected test for conversion. > > > > > > > > Convert the selected test to Clar while in constant effective > > > > communication with the mentors and Git community, implementing > > > > feedback and review suggestions. > > > > > > > > Properly test converted scripts to ensure validity and correctness. > > > > > > > > Steps to converting the existing unit tests to the Clar Testing Framework > > > > > > > > From the project description in the Outreachy Project Description page, > > > > > > > > > > > > https://www.outreachy.org/outreachy-dec-2024-internship-cohort/communities/git/#convert-unit-tests-to-use-the-clar-testing-framewo, > > > > the goal is to convert all Git’s existing unit tests to use the Clar > > > > testing framework exclusively. > > > > > > It might also make sense to plan some time to add missing features to > > > the clar if we hit anything during the conversion. > > > > Okay noted. > > > > > > > The existing unit tests which would need to be converted to Clar are; > > > > > > > > .c test files present in t/unit-tests: Tests in this directory use the > > > > t/unit-tests/test-lib testing framework and are “.c” scripts, > > > > converted from the shell-based testing which used the tests in > > > > t/helper/ and corresponding t<number>-<name>.sh test files. Examples > > > > of this conversion can be seen in the link below which references Achu > > > > Luma’s work > > > > > > > > https://lore.kernel.org/git/20240226143350.3596-1-ach.lumap@xxxxxxxxx/. > > > > > > > > > > > > The link shows the work done in converting the test from > > > > t/helper/test-sha1.c and test/helper/test-sha256.c to use > > > > t/unit-tests/t-hash.c which uses the t/unit-tests/test-lib.h framework > > > > > > > > > > > > The steps to convert files located in this directory include; > > > > > > > > - Identify the test files to be converted. > > > > > > > > Examples of such files are the t/unit-tests/t-hash.c, t/unit-tests/t-strbuf.c > > > > > > > > - Rename the test file from t-<name>.c to <name>.c. This pattern > > > > follows the style used by Patrick Steinhardt in his conversion of the > > > > t-strvec.c and t-ctype.c files to use the clar framework. > > > > > > > > https://lore.kernel.org/git/604303e31aad3a9e74f7bdddc84f11d4d137c864.1725459142.git.ps@xxxxxx/ > > > > and > > > > > > > > https://lore.kernel.org/git/ba05b9f1eef8136e087846ee54a076558097a240.1725459142.git.ps@xxxxxx/ > > > > > > > > As a sample demonstration, we will convert the t/unit-tests/t-hash.c > > > > to use Clar. > > > > > > I think the previous explanations are sufficient -- going into the > > > technical details like you do below is appreciated, but ultimately not > > > necessary in my opinion. What I'm after here is that you have a rough > > > understanding of what needs to be done for each of the tests, and that > > > is sufficiently demonstrated by a high-level explanation. > > > > Okay noted. > > > > > > > The test scripts in the t/helper directory: > > > > > > > > The tests in this directory are invoked by the corresponding shell > > > > scripts which spawn processes to test the different unit tests in the > > > > t/helper directory. > > > > > > > > The process involved in converting these shell scripts to Clar > > > > framework will typically follow the same steps as illustrated above > > > > bar the following differences. > > > > > > > > Identifying the tests to be converted to Clar > > > > > > > > Create a new .c file name which should be named appropriately to > > > > illustrate what the file is testing. > > > > > > > > However, the shell-based script which tests the functions in t/helper > > > > will be studied for in-depth understanding and then refactored into a > > > > .c file which follows the steps above in converting to use Clar. > > > > > > As mentioned above, I thought we didn't have any such tests anymore. If > > > we do, it might make sense to provide an example of such a thing that > > > needs to be converted. > > > > Thank you Patrick > > Okay from my understanding, such tests have a .c file in t/helper and > > a corresponding t/t-<number>-<name>.sh file. > > From my master branch which I study, I can see for example > > - test-env-helper.c in t/helper and t0017-env-helper.sh > > - test-find-pack.c in t/helper and t0081-find-pack.sh. > > I concluded since the shell script used to compare the output against > > the expected still exists > > and no such file names exist in t/unit-tests, I assumed they have not > > been ported which is why I listed files > > in t/helper will be converted to clear. > > Please I will be happy if I can get more clarity, thanks. > > > > > > > > > Project Timeline: > > > > > > > > Community Bonding (Present - November 26): > > > > > > > > Continue making contributions to the Git codebase working on different > > > > things within my capacity and getting more familiar with the codebase, > > > > participating in patches review. > > > > > > > > Conversion of tests begins (December 9 - December 23): Familiarize me > > > > with the conversion process to further enhance my understanding, > > > > identify files for conversion and start the conversion process, and > > > > set up a blog for weekly updates on my conversion process. > > > > > > Makes sense. > > > > > > > Implementation of community and mentor reviews (December 27 - January 31): > > > > > > > > Continue with conversions while testing converted tests, communicating > > > > with reviewers and implementing reviews. > > > > > > > > Testing (February 1 - March 1): Continuously determine the correctness > > > > of the converted tests by continuously testing and also liaising with > > > > mentors constantly. > > > > > > For this one here'd I'd recommend to start more iteratively. What you > > > have here sounds a bit like a waterfall model, where you first convert > > > all tests and then eventually test and send things over to the mailing > > > list. > > > > > > In the Git community you will likely have more success if you work in > > > smaller patches. E.g. pick a small set of tests to convert, convert > > > them, polish the series and then send it to the mailing list. That cycle > > > would then repeat several times until you have converted all of the > > > tests. > > > > Yes, my contributions have made me understand this process. > > I will make appropriate adjustments. Thank you > > > > > > > Availability: > > > > > > > > I am not currently enrolled in any academic program or have any jobs, > > > > and will be available to work on the project for a minimum of 45 hours > > > > per week. > > > > > > You really shouldn't be working more than 40 hours per week ;) The > > > [Outreachy Internship Guide](https://www.outreachy.org/docs/internship/) > > > recommends 30 hours per week, and I don't expect any more of you, > > > either. > > > > > > > > Other than that this document looks good to me, thanks! > > > > > > Patrick > > > > Thank you very much Patrick, I appreciate your time. Please I will > > also like to know if i should send the corrected proposal > > as a mail to the list as I did with this first version. > > > > Thanks again for your time. > > Abraham Samuel > > > Hello Git Community, > > > I hope this mail finds you well. > > I am Abraham Samuel, participating in the Outreachy internship program > and I write to express my delight, enthusiasm and interest in working > on the project “Convert unit test to use the Clar testing framework”. > > My first exposure to Git started with the book “Learn Enough Git to Be > Dangerous” which taught me the basics of using Git for version control > and collaborations and I felt truly dangerous :-). > > > I am passionate about FOSS and now that I am presented with the > opportunity to contribute to Git, It is indeed a great opportunity to > understand what happens under the hood and I have never been happier. > > > ## Introduction: > > I completed my ALX Software Engineering program in 2023 and I have > been engaged in various software development projects, open source > development and various personal projects, providing me with valuable > technical and collaborative skills. > > > ## Project Overview - Convert unit test to use the Clar testing framework: > > I understand that the Git project is in the process of converting its > unit tests to the Clar testing framework to improve test readability, > consistency and maintainability, a move away from homegrown unit test > framework t/unit-test/test-lib.h. > > Part of the reasons for this > [decision](https://lore.kernel.org/git/cover.1722415748.git.ps@xxxxxx/) > includes: > > 1. Avoidance of duplication when declaring test functions which occurs > when using the t/unit-tests/test-lib.h framework > > 2. Having a proper unit testing framework instead of reinventing the wheel > > 3. Clar can be easily extended > > 4. Clar provides a structured and efficient way to write and execute > tests and is well-suited for a project like Git where robust testing > is essential to maintain quality and stability. > > > ## Contribution to the Git Community: > > I have participated in contributions to Git’s codebase after getting > accepted into the contribution phase in October 2024, working on what > I found doable and within my reach. Below is the list of my > contributions: > > - [PATCH v4] t7300-clean.sh: use test_path* helper functions for error logging. > > List thread: > https://lore.kernel.org/git/pull.1811.v4.git.1728498122419.gitgitgadget@xxxxxxxxx/ > > Status: merged into master > > Merge Commit: 77af53f56f100b49fdcf294f687b36064d16feca > > Description: The patch converted instances of “test - [def]” > in test cases to test_path_* functions to get error logs when the test > case fails when testing for the existence of a file or directory after > “git clean” or “git clean -d” is called as the case may be. > > > > - [PATCH v4] notes: teach the -e option to edit messages in the editor > > Status: integrated into next > > List thread: > https://lore.kernel.org/git/pull.1817.git.1729296853800.gitgitgadget@xxxxxxxxx/ > > Description: The patch worked on a #leftover bit which added > the “-e” option to “git notes add” and “git notes append” subcommands > when the message is supplied with the -F and/or -m options. The patch > enables fine-tuning the message by invoking the user’s default editor > prefilling the message in the editor to allow editing the message to > the required taste before adding the note to the commit > > > ## Project Plan: > > - Identify files for conversion in the t/unit-tests directory > > - Write incremental patches > > - Convert test and implement community and mentors’ feedback > > - Validate converted tests > > > ## Detailed Steps > > > ### Identify files for conversion in the t/unit-tests directory: > > From the project description in the [Outreachy Git Project Description > page](https://www.outreachy.org/outreachy-dec-2024-internship-cohort/communities/git/#convert-unit-tests-to-use-the-clar-testing-framewo), > the goal is to convert all Git’s existing unit tests to use the Clar > testing framework exclusively and also add any missing features which > might be necessary for the conversions. > > I will begin by selecting files from the t/unit-tests directory for > conversion to the Clar testing framework. This approach allows me to > start with smaller, manageable patches that the community can review > incrementally. > > The existing unit tests which would need to be converted to Clar are > .c test files present in t/unit-tests . Tests in this directory use > the t/unit-tests/test-lib testing framework and are “.c” scripts (for > example t/unit-tests/t-hash.c and t/unit-tests/t-strbuf.c), converted > from the shell-based testing which used the t/helper/test-tool > framework and corresponding t<number>-<name>.sh test files. Examples > of this conversion can be seen in [Achu Luma’s > work](https://lore.kernel.org/git/20240226143350.3596-1-ach.lumap@xxxxxxxxx/), > which shows the work done in converting the test from > t/helper/test-sha1.c and test/helper/test-sha256.c to use > t/unit-tests/t-hash.c which uses the t/unit-tests/test-lib.h framework > > > ### Write incremental patches > > Each test conversion will be submitted as an incremental patch, > following [Git’s contribution > guidelines](https://github.com/git/git/blob/master/Documentation/SubmittingPatches). > By keeping patches incremental, the community can provide focused > feedback on each test conversion, improving the outcome. > > > ### Convert test and implement feedback > > Once the files are identified, I will proceed with the conversions > while regularly communicating with the mentors and the Git community. > This communication will ensure alignment on the implementation and > allow immediate adjustments based on any feedback received. > > Each file conversion will typically have the following steps: > > - Rename the test file from t-<name>.c to <name>.c. This > pattern follows the style used by Patrick Steinhardt in his conversion > of [t-strvec.c](https://lore.kernel.org/git/604303e31aad3a9e74f7bdddc84f11d4d137c864.1725459142.git.ps@xxxxxx/) > and [t-ctype.c](https://lore.kernel.org/git/ba05b9f1eef8136e087846ee54a076558097a240.1725459142.git.ps@xxxxxx/). > > - Add the module name to CLAR_TEST_SUITE variable in the MAKE file. > CLAR_TEST_SUITE += <name> > > - The next steps will typically involve writing optional setup > and cleanup functions with the signature “void > test_<suitename>__initialize(void)” and void > test_<suite_name>__cleanup(void) and the actual tests also with the > signature > > void test_<suitname>__<testname>(void) and the Clar methods such as > cl_assert(), cl_assert_equal_s(), cl_assert_equal_i() and any other > implemented assertion methods can be used to verify the results > against the expected. > > > > ### Validate converted tests > > Finally, each converted test will be validated to ensure it behaves as > expected. Tests will undergo a thorough review to confirm that the > converted scripts accurately replicate the original test’s > functionality. > > > ## Project Timeline: > > Community Bonding (Present - November 26): > > Continue making contributions to the Git codebase working on different > things within my capacity and getting more familiar with the codebase, > participating in patches review. > Understand Git and Clar codebase (December 9 - December 22): - I will familiarize myself with the Git codebase to understand current tests - Study previous conversion processes by previous interns to the now-old unit test framework for ideas that would benefit me. - Work with Clar upstream to improve shortcomings discovered during integration with Clar. - Set up a blog for weekly updates on my conversion process > Conversion of tests begins (December 23 - March 1): > > - Identify files for conversion with mentor’s guidance > > - Start conversion process for selected > > - Send incremental patches to the mailing list for review by > mentors and community members > > - Implement review feedback and resend patches to the mailing list > until an agreed patch is agreed upon. > > - Update my blog to talk about each conversion and the > achievements, challenges and goals achieved. Final Stages (March 1 - March 7): - Update my blog on the gains and knowledge gained during the internship - Work with Git Community to ascertain level of satisfaction with converted tests > > > > ## Availability: > > I am not currently enrolled in any academic program or have any jobs, > and will be available to work on the project for a minimum of 30 hours > per week. > > > ## After the Internship: > > The Git community fosters proper and effective communication, > regardless of one’s level of experience. The patience, guidance and > explanation of technical concepts shown by community members are > wonderful and this has made me grow not just technically but also > behaviorally. Due to this, I plan to continue actively participating > the in Git community and be part next generation of those saddled with > sustaining this great project and preserving its legacy. > > > I look forward to reviews as regards my proposal. > > > A special appreciation to everyone on the mailing list for reviewing my patches. > > My mentors Patrick and Phillip, Junio, Eric, Christian, Brian, > Kristoff, Taylor, and Josh. > > I am grateful to you all. > > Thanks > > Abraham Samuel.
