Merge branch 'master' into 'master'

report anne-marie

See merge request !398

projects/projects_2024-25/Report-Kourieh-Anne-Marie-35152301.md

+# Open Source Project Contributions: ImageMagick
+
+| **Author**              | _Kourieh Anne-Marie_                                                 |
+|-------------------------|----------------------------------------------------------------------|
+| **NOMA**                | 35152301                                                             |
+| **Academic Year**       | 2024-2025                                                            |
+| **Date**                | 18/01/2025                                                           |
+| **Open Source Project** | [ImageMagick](https://github.com/ImageMagick/ImageMagick)            |
+| **Discussion**          | [#7772](https://github.com/ImageMagick/ImageMagick/discussions/7772) |
+| **Main issue**          | [#6704](https://github.com/ImageMagick/ImageMagick/discussions/6704) |
+| **PR**                  | [#7906](https://github.com/ImageMagick/ImageMagick/pull/7906)        |
+| **Licenses**            | [ImageMagick License](https://imagemagick.org/script/license.php)    |
+
+
+## Choice of the project
+When picking this course, I wanted to make sure I would be able to contribute to something I really appreciate and not just any random project.
+I had been searching since October. However, unlike most students, I don't have much knowledge in open source projects. 
+So, I was advised to go on main open source repository websites or just search randomly on GitHub.
+However, none of these projects inspired me, I really wanted to help for a project which I like. After reading some of the previous years reports,
+I found out many students were using libraries or projects they had used previously during their studies.
+So, I browsed through my previous university projects and found this one I had made in BAC2 which was using ImageMagick.
+
+[ImageMagick](https://imagemagick.org) is an open-source software that helps to manipulate all kinds of image files on the command line.
+It is very convenient to use rather than having to pay some software like Adobe Photoshop. It is also handy to reformat image files also.
+It is quite an old project actually, it started in [1987 by John Cristy](https://en.wikipedia.org/wiki/ImageMagick). It is now maintained by a group of volunteers, and the one I had contact with is one of the current main
+maintainer, Dirk Lemstra.
+
+## License
+The ImageMagick license is a free software license but with its own specific terms and conditions. It allows for reuse as long as all copies of this software include a copy of their license terms.
+
+`Copyright © 1999 ImageMagick Studio LLC, a non-profit organization dedicated to making software imaging solutions freely available.`
+
+## Timeline
+- **13/11/2024**: First contact with the community. I added a discussion topic on their GitHub to ask for a first contribution to make.
+- **23/11/2024**: After agreeing on the issue, I was told to learn about GitHub Workflows/Actions to help for this problem.
+- **16/01/2025**: After a month of learning partially and mainly trying to understand what they wanted me to do, I finally made what I thought would suit best their need and made my PR.
+
+Sadly, by the time I will be taking my exam, the PR will probably not be reviewed yet (as I was told).
+
+## My contribution
+The original issue was about the documentation for Magick++ which is a C++ API for the ImageMagick library. The problem is that there were some inconsistencies with the return types of a certain method in the Image++ class and the actual return type of this method.
+The maintainers said they updated most of them, however it is not a viable solution for them to update HTML files by hand each time there is an update to the source code. In fact, the orginal issue dates back to 2017 and there were no solutions proposed for it ever since.
+
+When I opened my discussion topic, they asked me to make a GitHub Action that would check for inconsistencies in the API included in the website documentation and the actual code.
+They also said it could be good to do automatic updates of the documentation. To be honest, it took me awhile to find a way to do these checks because here's the problem;
+the documentation HTML files of their website are all written manually... Gladly, I was able to find an approach when I saw that they all included the same sort of table for the function signatures.
+I also saw that there are Doxygen files to generate the documentation, though it is only local, not on the website (`make html-local`). I decided to use these local Doxygen-generated HTML files to check the function's signatures in the website's documentation HTML files where
+the tables are all defined the same way. Still, there was a second issue I was facing, I realized almost every script they have is either in C or bash... In my opinion, I find that it is not really efficient to use these languages for this kind of task. Plus, it would only be run inside a GitHub Workflow.
+In fact, in Python there are already two libraries I could use: 
+* `BeautifulSoup` to parse the HTML file
+* `Pandas` to store the data in a well-structured way (DataFrame)
+
+By the way, in November, I was trying to find a contribution to make for Pandas, but it didn't really feel like I would have been useful anyway since they have tons of contributors already...
+
+The reason why it took me awhile to finish this is because I felt quite alone with the issues I was facing.
+I like to help for projects where there isn't a ton of people working on it because I find that I am actually being useful. Although in this case, I didn't have much indication on what to do, so I kept
+pushing this task away, I thought I wouldn't be able to do it because I thought the task was too hard and that I would never find any idea on how to solve this or even 
+understand what they really wanted from me. Fortunately for me, I found a solution when seeing the uniformity of the tables in the HTML files,
+which was the key for me to finish this contribution. 
+I finished my yml workflow and Python script and made my PR. You can see in the link above to my PR that I explained how the solution I implemented works and I included proofs of the current inconsistencies found when running the workflow on my forked repository.
+
+