Outreachy Summer 2024: An accessible diff viewer

[panglesd]

Outreachy Summer 2024: An accessible diff viewer

This issue is point of introduction to the project for Outreachy applicants.

First of all: welcome! We are happy to have you interested in the project.

In this issue, we gather many information that is relevant before contributing: more explanation on the project, but also resources worth reading, some instructions to set up the project, and a list of issues with some hint on the difficulty.

So, make sure to read this issue till the end! And do not hesitate to reply on it to ask any question that is related to the project! (For questions that are non-specific to the project, such as issues in setting up OCaml, please prefer other channel, such as the OCaml discord server).

The project

Looking at the difference between two files is one of the most common activity in open source work.
It happens when reviewing a pull request, inspecting a commit and in many other situation.

The differences are usually displayed following a specific format, added lines being prefixed with a +, removed ones by a - and common one without prefix. Such format is called a "diff". Here is a simple one:

  common words
- removed line
+ added line

However, in complex situation, reading such diff is not always easy. Many tools have been to made to improve the situation and make the diff reviewing easier: as shown above, the use of colours to distinguish between added and removed lines (traditionally green and red), use of a bold face to get the attention on the modified part of the line at the word level, the display of the two files side-by-side, ...

However, most of the improvements mentioned above:

• Are made for "generic" diffing of files. Some files may have very long lines and be unsuitable for the current diff output.
• Are restricted to sighted people.

The goal of this project is to develop a visualization tool on top of Git diff. The visualization tool is a terminal UI, and the main task of the internship is to make it highly accessible to screen readers.

The current state of the project

This repository contains a minimal TUI to visualize diffs, as a starting point for the internship.

It uses several libraries:

• The patch library to parse and print diffs,
• The notty library to "declare" terminal layout,
• The lwd library to make the UI reactive,
• The nottui library to bind lwd and notty,
• The cmdliner library to generate a command line.

It is built using the dune build system.

The project is still quite small. The bin/ directory contains the code for the command line, relying mostly on the cmdliner library.
The lib/ directory contains the code for the UI, using lwd and nottui.
The vendor/ directory contains the vendored libraries: dependencies that needed to be slightly modified, and as such were included in the source. Unless for specific reasons, you won't need to modify the code in this directory. It can be useful to read though.
The rest of the files are configuration or documentation files (dune files, README.md, LICENSE, ...).

How to understand the code

Although the number of lines of code in this project is fairly small, it is very dense and can be quite hard to understand at first. But with time, work and experience it will become clear! So don't despair if at first, it seems obscure.

The first requirements to understand the code is to have the basics of OCaml: its syntax, but also the functional and declarative idioms it uses. The ocaml.org website provides some tutorials and guides, and there is also the book Real World OCaml which is available online.

Then, it is important to have a good idea on how the libraries used in this project work. Cmdliner has some documentation, that should be understood for any task that requires modifying the command line.

The Text User Interface is made using a concept called "Functional Reactive Programming". There is some explanation on that in the Lwd homepage. Basically, the UI layout is built from basic mutable variables, created with Lwd.var. Similarly to the React framework, any change in the value of a basic variable will trigger a recomputation of the UI, which will be updated where needed.

Setting up the project

First, you need to have OCaml up and running on your local machine. See the tutorial Installing OCaml.

Then, you need to clone this repository. Once you have that, go to the directory and install the dependencies with the following command:

$ opam install . --deps-only --with-test

Once the dependencies have been installed, try to build the project.

$ dune build

If dune is still complaining about missing dependencies, maybe your environment is not in sync with opam. In this case, on Linux and Mac eval $(opam env) should fix it.

You can now run the binary created by the project:

$ dune exec diffcessible diff.example
$ # Or to see the man page of the tool:
$ dune exec -- diffcessible  --help

Claiming an issue

Once you get a reasonable understanding of the code and have the project set up, you can consider contribute to the project. In order to do so, you have at the end of this section a list of good first issues.
As to avoid duplicated work, when you decide to work on an issue, you need to be assigned on it: this way, you can work on it without the pressure to finish before someone else opens a PR fixing the issue! However, in order to be assigned an issue, you need to be able to build the project first.
To be assigned an issue, comment on the issue thread with a screenshot of your computer with the --help page, and ask to be assigned to the issue! When you are assigned an issue, we can provide more guidance on it if needed.

Good first issues:

• Allow to read the patch from a file #3
• Improve the n and p shortcuts #4
• Add colors to output #5
• Create a help panel #11
• Display current operation in status bar #12
• Use keyboard arrows for scrolling #14
• Compute and display number of added and removed lines in status bar #17
• Compute and display number of hunks in the status bar. #18
• Navigation between hunks #19
• Add colors to output #5
• Colorize addition and removal summary #44
• Add keybinding to scroll to the top #46

Medium issues:

• Add a side-by-side display of the diff #8
• Test for the interface #9
• Bind j and k to scrolling #15
• Horizontal scrolling #45

Asking for help

Please do ask for help if you are blocked on something!

There are two different kind of help that you might require: general help with OCaml, the tooling ; and help specific to this project.

To get general help on OCaml, the discord server might be the best option. It contains a "#outreachy" channel as well as a #beginner channel. The OCaml discuss is also a place where you can get help, it looks more like a forum compared to discord.

Contributing and AI

We want to stress that during the contribution period, AIs should be used with a lot of care. While they are a great tool both to learn and work, they can be very inadequate without mentor or critical sense, moreover they don't know OCaml very well. As mentors, we don't want to review code copy-pasted from an AI.

Conclusion

We are glad to have you here!

[ademolaomosanya]

Hello,
I am Ademola Omosanya, a passionate coder eager to dive into the realm of open source collaboration. Having recently forked and cloned this project, I am thrilled to contribute to its growth and success.

Currently residing on my local machine is a version of diffcessble project, running smoothly and ready for enhancements. I've already begun exploring the project's architecture, understanding its goals, and identifying potential areas for improvement. The prospect of contributing to a project that aligns with my interests is not just exciting but also a valuable learning experience.

i would like this task to be assigned to me #5
Thank you.

[Shedrack-Sunday]

Hello @panglesd , I'm trying to make a contribution, but there seems to be no first issues. Please how can I get assigned tasks?

[panglesd]

Hello @Shedrack-Sunday,

Yes, I'm very sorry about the situation. We were not expecting that many contributors and contributions!

We are going to add new good first issues today. Please come back in a few hours...

Thanks for your interest in the project and sorry again!

[Shedrack-Sunday]

Thank you. I made a request for a medium issue, please check It out. Thank you

[panglesd]

We are currently lacking new good first issues. We will be adding new one soon, but in the meantime, if you want to contribute and have an idea, feel free to open an issue suggesting an improvement, or a new feature! We will review the difficulty and usefulness of the issue, and assign you if that is a good first issue!

[Shedrack-Sunday]

Thank you. I've installed OCaml already. I'll send a screenshot and challenge myself with the unassigned medium before the first issues are available

[panglesd]

@Shedrack-Sunday Sorry for the delay. I've opened #44 as a good first issue, if you want to have a look.

[panglesd]

Since half of the contribution period has passed and we are short of good first issues, we've added some "rules" to contribute!

• Good first issues can only be requested by first-time contributors
• Once a good first issue is assigned, the assigned contributor should open a draft PR showing some progress in at least 4 days. If the delay is reached, we might unassign the issue.

We've had very strong contributors to this project! We encourage everyone to contribute to several projects, to maximize their chances, as each project can unfortunately only take one applicant as intern...

[yokurang]

Applications closed