What I Learned From My Contribution to Angular
ANGULAR 9 has come, and you might notice my name in the commit history. This was the first time I contributed to such a big and widely-used project. The journey appeared to be easy enough and very exciting! Was it so? Let me tell you the story.
In our company, we went through a bunch of technologies and approaches on how to develop frontend code. Initially, our service was written using the Grails framework — Java-based MVC server-side rendering engine. JQuery used to add some interactions with customers on the page which was quite common those days, but you definitely don’t want to see this in 2020.
A few years later, AngularJS showed up and it was like fresh air in frontend development. Services, components, template rendering engine, etc. We were happy to implement AngularJS on our platform and wrote over 700k lines of code.
Time flew and one day Angular (which was expected to be AngularJS v2) was released. The problem was that these two things are not compatible with each other, so our codebase became legacy at one moment. I pushed hard to update the version of the AngularJS and gave up on v1.5.11. What was the solution? We decided to keep existing applications as it is and to select a new way to write frontend inside the company. The thing is that our platform consists of independent applications each of them loads unrelatedly of others. Thus, every application can be written using any library or framework team decided to use.
First of all, we switched to build js code with Webpack and removed Browserify for goods. This brought us a lot of opportunities like how we split bundles, what JS features are supported and so forth. Then the time has come and we added Typescript. After all, we implemented React on the platform. Currently, engineers develop new applications using React. But fair to say that our vision remains the same: each team decided what to use on their own. Some teams still use AngularJS because it is too difficult to re-implement existing logic. Others still fix Grails applications (yes, we still have few of them in production at the moment!).
The idea to tune up the infrastructure for Angular was flying in the air, but it was quite tricky until we started to use Webpack. With Webpack it seemed to be an easy deal: load CSS modules with raw-loader, fix Jest HTML templates loader and we good. Good enough? I thought so until we started to write an application based on the Angular framework…
Something Went Wrong
The problem appeared from the place we did not expect. Let’s make some introduction: we use UI component package which renders beautiful and strict UI experience for our clients. This library is framework-agnostic and acts quite similar to Material UI components for Angular i.e. developer forms specific HTML layout to bring particular component into action, populate and style components by applying pre-defined element classes and tags. Also, one can access any element in the JS code and play with it dynamically.
So it was my colleague Irina, who found an interesting issue. She was the first person to try Angular on our platform. Historically, the UI components we use rely on the HTML element attributes. These attributes have the form of data-ts or data-ts.something. For instance, if we want to implement a modal window, we should add the title by setting data-ts.title attribute:
Pretty straightforward, right? But what if we want to apply the title dynamically? Let’s say we want the title to contain a user name or something like this. What should we do? Yes, Angular provides a standard way to interpolate the attribute value from the controller property:
Here we go! But wait… what?! This does not look good in the browser:
You may notice here that the Angular compiler went through the HTML template and parsed attributes in the wrong way. For attr.data-ts.title symbol it generates data-ts attribute instead of data-ts.title. This completely breaks the layout and the modal window does not work. UI components even don’t know that I defined a modal window because the attribute was overridden with the result of interpolation. It sounds like a real blocker that prevents us from using Angular.
Trying to Find a Solution
I tried to google the solution but had no luck. I felt like it is meant to be a very specific case nobody noticed really. Fair enough. On the other hand, if HTML standard supports this type of element attributes and browsers render them correctly, so should Angular compiler do. Taking this into account, I decided to ask Angular team directly. I went to Angular GitHub repository and opened an issue. The beginning was promising, they marked my issue with tags that highlight that the bug exists in the Angular compiler and the issue has low priority. What happened next? I started waiting…
…After 2 months nothing really happened. I figured out that since my problem is not something major, then there are low chances to see it fixed any time soon. The team is busy making the Ivy engine into a stable version. Nonetheless, they confirmed the bug exists, so they would not be against me fixing the issue by myself. Okay then, I am doing a fork of the Angular repository.
I am Going to Fix the Bug
First of all, I drew my attention to the CONTRIBUTING.md file and read it carefully (consider making a project fork to be my zero step). This file describes all the rules I should follow so Angular team will proceed with my Pull Request. It explains the responsibility of the parties, code ownership, agreement on the commit message format, test coverage requirements and many other questions.
Next, you need to sign the Contributor License Agreement with Google company which confirms you are okay with all contributing rules and restrictions. The CLA link is located at the end of the CONTRIBUTING.md file so read the whole text until the end. Finally, paperwork comes to an end, let’s dive into the project itself.
Angular is a typical yarn project, just big enough. You can simply run yarn install and it will setup all the environment. Well, okay, simply run yarn install and simply wait for 5–7 more minutes — I told you this is a big one!
I stopped for a second at this point, because I was looking forward to an exciting journey — to go through the source code. It was scary in the beginning to figure out what is going on in such a huge project, tons of modules, different pieces of code interact with each other. But after spending some time I came to the conclusion that big projects mean to be a big advantage.
When your project becomes huge, you focus on absolutely different things that might sound meaningless when you have just a few files. Different things, different approaches show up to be the priority. In the Angular, I saw that the project structure is a super important thing. Every module has a meaningful name, every variable document itself, every method shows what it does exactly. It is quite easy to navigate through the framework parts and the understanding of what this or that module is for comes to your mind instantly.
I already knew that my issue lays somewhere in the Angular compiler and it was quite easy to find the exact line:
Well, what is this? We receive an HTML element attribute (stored in the boundProp). Then we split the attribute name by some delimiter to figure out if it contains “attr” prefix. If the first part is the prefix, we consider the attribute name to be equal to the second part. Obviously, this is not correct, we should concatenate all the parts except the prefix instead. Let’s fix it:
Perfect! Now we need to make sure other changes would never break our functionality. I am going to write a test. It is quite easy to do in such huge projects like Angular. There is a requirement to cover any code change by unit tests so you definitely will find a spec file along with each module in the repository.
So I opened that spec file and saw a bunch of tests that cover the module I have changed. I went through the 2000 lines of test cases and found the test which checks the name of the attribute after compiler parsed some HTML element. Made a copy and changed attribute name, so now it contains a dot delimiter and fixed the output expectation. That’s it. Now my changes are covered! I thought it would be tough, but turn out it was super easy:
Well, I fixed the code. Writing a commit message keeping in mind the format team asked to follow and… going to the kitchen to make some tea as the pre-commit hook launches all unit tests in the project. Can you imagine having 37000+ tests in the project? The first launch will take a while, but then test results will be cached and next runs will take much less time. I made a commit, opened a Pull Request, started waiting…
Resolution
…After 2 months I decided waiting is enough for me. The code was the smaller problem, the bigger one was how to proceed with my changes? It was clear to me that I need to find a person who is somehow related to the Angular team and discuss what options I have right now. I applied the social engineering approach and went through the latest contributors to the Angular compiler module. Andrew Kushnir was the first on my mind. I found his Facebook account and wrote him a message. Unfortunately, a week after I did not get a follow back and decided not to be annoying for the person who doesn’t know me. I decided to have another try and found Pete Bacon Darwin. I noticed that his profile has an email address so it might be useful even in 2019. And it actually did work!
I wrote a long email describing all the little things we struggle with. Described our UI library, attached links on the issue and pull-request. I told about myself and my company. And most important I was really thankful as expecting Pete to spend his own time on my problem.
The next day I found a message from Pete. He told me that he is okay to contact via email about my pull-request and that he never saw people define attributes with dot notation. He also gave me a piece of advice on how to write an accurate commit message. And then, he approved my code changes. After this, all happened with the speed of light… while I was sleeping. (guess why? 12 hours difference between the US and Novosibirsk — the place where I live)
While I was sleeping, the Angular team moved my pull-request into a release state. They ran another set of tests (I guess they were integration tests this time) and figured out that in one test there was an SVG-block with some interesting attribute [attr.height.px]=”16". It used to be rendered as height=”16", but with my changes, it became height.px=”16". After a small discussion, they decided to fix that SVG-block and to merge my changes into Angular. This meant that my fix will show up in the upcoming major version of the framework!
My commit was merged, my pull-request was closed. I just got up in the morning and saw all these comments, was scared, upset and glad at the same time.
In the evening I got an email from Pete. He confirmed that my fix will be released with Angular v9 and thanked me for contributing to the project.
From my side, I paid appreciation for the time he spent on me and for all the help. I said that it was quite an important step for me to make things right and to make a success.
You may ask me what’s next?
Next few months I was waiting for the release. I noticed that my changes came with Angular 9.0.0-rc.2. And now, literally, a month ago they have released the stable version of the Angular 9.
The outcome
For me, it was a success story. We finally got Angular based applications working on the platform. But the most important thing here is that I did my best to gain the result. So, go all the way and never give up. Try different ways to achieve what you want. Push the stuff you think is right. Look for people who can help you to find a way to deliver.
If you see a big popular project in front of you, it does not mean you can’t influence it. If you have an idea or you believe something works not as expected — just try. Even if the cost of your changes is a one-line fix. In most cases, the team is open to external contributions and any help from other developers. They might have no time to fix this or that issue. So you are welcome to offer your help.
I have this article posted in Russian as well, so if you want you can read the translated version here.
