Opensource X October - an ongoing theme to make people familiar with OSS across the world. I had my first experience last year. It was very exciting and explorative in nature.
This year 2021, I wasn't sure I would be doing it again. But then I came across
and started digging into what all it's about.
Amazingly, I approached the things in a more structured fashion than the last year and I would like to take you through the first 4 contributions that qualified me for Hacktoberfest 2021 .
1. Numero Uno
Operational Transformation ?....sounds like a very sci-fi concept...doesn't it ?
A quick google search and I landed on the classic Wikipedia page describing what it was.
Operational transformation (OT) is a technology for supporting a range of collaboration functionalities in advanced collaborative software systems. OT was originally invented for consistency maintenance and concurrency control in collaborative editing of plain text documents. Its capabilities have been extended and its applications expanded to include group undo, locking, conflict resolution, operation notification and compression, group-awareness, HTML/XML and tree-structured document editing, collaborative office productivity tools, application-sharing, and collaborative computer-aided media design tools. In 2009 OT was adopted as a core technique behind the collaboration features in Apache Wave and Google Docs.
Well, the above paragraph and a bit about it in the same article gave me a high level picture of the scope of this repository. It's collaborative editing and not limited to one Database or Editor implementation. Rather, this aims to allow multiple combinations of the either of Database/Editor as a part of otjs package. So you can have a firebase database with monaco editor or a firebase database with ace editor and this is just the beginning of possibilities.
As someone who hasn't really tinkered with either of used Database ,Editor or Operational Transformation tech jargons used here, this was very new and kind of exciting.
I randomly opened a couple of code files to see what's happening to only be clueless.
So I took another approach here. This approach has been talked a lot by folks all over dev communities when looking forward to contribute to a new OSS. It's reading the docs and figuring out the stuff. So naturally the README was the entry point for this which got me familiar with opening issues here (via discussions and not directly for this repo) and lead me to the CONTRIBUTING markdown file with the guidelines to make a contribution.
This is where I found my first way to contribute. Improving the existing docs, CONTRIBUTING markdown to be specific with some linguistic nuances and correct links. Does this make me understand the code better in any way ?
So why bother ?
It's the ice-breaker to start working on this repository. I ended up opening the following for this :-
The maintainer opened up a new issue
for me to fix and as per the CONTRIBUTING markdown guidelines, I made my first PR to this repository which got merged by the maintainer.
The PR 👇
2. Double Trouble
Well we have officially entered Hacktoberfest 2021 even though I didn't register until I got my 3 PR's merged I believe.
So I made a very small contribution to start with and the next one should at least give me more insight into running some examples using the packages in this repository.
And there was already a provision for examples here
But there was no README for the same which tells the user how to run this example. And this ultimately turned into another opportunity for a contribution.
This is the second discussion which took place
The maintainer opened up a new issue
and told me that I can pick it up if I want to. I gave it a try in my local setup and got the example running. After this, I created a README with instructions and few images that can give a new user enough information to run and validate the working of these examples. There goes my second PR to this repository.
The PR 👇
3. Third time's the charm
Till now, I actually didn't pick up any of the existing issues which were already up for grabs since most of them required technical know how. So it was time to try a small one to get my hands dirty with code.
I found the following issue fulfilling the criteria
what is happening
I basically had to add support for remote selection of text to be visible in Ace editor. Let's see what this means by example. Suppose two users are contributing to a Doc powered my Ace editor, now, when one of them highlights some text or places a cursor somewhere in the same DOC, the other should know where the cursor is and what's the highlighted/selected text.
And first I thought to myself that how is this task labelled small ? Wouldn't that need more lines of code ?
My question got answered when I compared the existing code for Monaco with Ace and saw that both have almost the same implementation with code for remote cursor/selection present as well. The only thing missing from Ace was a bit of CSS implementation and that was all that needed to be figured out. The good thing is that an existing implementation helped me compare and arrive at the solution quickly.
I submitted my PR and the maintainer appreciated the catch and fix.
The PR 👇
He also asked me if I can give a try to add support for a remote tooltip for Ace Editor. I did a quick comparison between Monaco and Ace implementation again and found that this would require implementing a new Class itself and should be addressed in a separate issue. The maintainer agreed and opened a new issue for the same.
4. May the Fourth be with you
The last issue helped me get familiar with a bit of code and resulted in creation of the above issue (labelled medium) which needed me to go deeper into Ace editor APIs. But I will be honest here, the editor doesn't have good docs (as far as I explored).
It was now required to implement a tooltip that lets the current user know the username of the remote user when typing. On paper, this sounds not too different from what might have gone into implementing a remote cursor/selection.
But when I looked at the existing code for tooltip implementation in Monaco editor, I saw that it has a concept of ContentWidget which allows for such UI widgets to be built and maintained easily and the developer used the same to create a new CursorWidget class which takes care of adding, updating and removing the tooltip. Here comes the interesting part that Ace itself doesn't have the concept of widget in the same sense.
There are two types of markers though which can be added by using
addDynamicMarker API. Initially I thought maybe the first one would be enough to help us achieve the tooltip functionality but since it's meant for static markers, which are added and removed each time using
removeMarker combo, it didn't fit the tooltip use-case. The second one i.e
addDynamicMarker's didn't have good docs and I felt less confident in using it until I found the following tooltip implementation in another OSS
After reading the code and trying to implement the same kind of functionality a couple of times while ensuring to follow the CursorWidget template, I finally got around getting the tooltip implementation to work with Ace and proposed adding debouncing as well to the tooltip announcements for a better UX. Figuring out all of this took at least 2 full days and I was happy with the end result.
The PR 👇
If you notice the order of issues, you would see that this approach was progressive going from no-code to code contributions within 4 PRs. I know the maintainer from Linkedin and have interacted with him in DMs and comments a couple of times. So when I came across his post that he is looking for contributors to his new repo, I thought let's give it a shot !
While contributing this time, besides the problem solving and technical learning, I got to know about Semantic Commit Messages, --fixup flag, a gist of Github Discussions and creating issues from the same.
Besides the above 4 PRs, I contributed 3 more to the same repo with minor test updates, code refactoring etc. Also I came across the following to contribute JS interview questions and submitted 3 PRs for the same.
Overall I enjoyed the structured approach this time.