Category: Open Source

Home / Category: Open Source

An OSD Contribution Update – Part 1

Tutorial Header

Getting Onboard

Documentation is a topic that often splits developers into two or more camps, those who write and those who don’t; an irony since both camps rely heavily on documentation with external libraries to utilize and understand it’s respective API. So, when is documentation considered ‘good’? When does the documentation fulfill the needs of the developers, and convey the key functionality without proposing self discovery of unknown APIs? This is what I wanted to explore while contributing to Angular Material (https://material.angular.io/), https://github.com/angular/material2. I found a great issue which was requesting for more documentation for their material stepper, https://github.com/angular/material2/issues/10381 and I thought it would be a great introduction to their community while providing a changeset which benefits more than just developers or current users of Material. Updating documentation helps everyone, and in a few examples from my task I’ll explain my thoughts on why I think so.

Current State of Stepper Documentation

As the issue suggested, the documented examples for the stepper component was lacklustre… sparse even. The API was listed in beautiful English, but no interactive examples were present which displayed the various states, attributes and data-flow which the component offered. The recommendation by mmalerba was to provide better examples between various state flags, icon matching, and expansion of the original example.

Current State of Stepper Example

One item that I had noticed was the button to ‘toggle linear’ mode for the stepper never actually toggled the state, but instead set the state to true (meaning linear is enabled) and nothing else. No toggling (enabling / disabling of linear state), just moving to a single state. This was the first item I wanted to address since as a user, I’d want 1) visual feedback and 2) the option to toggle and switch between states in the example. All the foundation was already there for such an update, and it became my first commit into what would be the Angular Material project.

Creating Examples for Edit and Optional Steps

For the documentation, I saw that there were no tangible examples of the edit and optional attribute Inputs of the Material Stepper, a need which needed to be met. This is where my Pull Request started, with implied intent that I’d add more if mmalerba or I found more appropriate examples which could be utilized for the stepper component to display even deeper functionality.

I can say that reading the documentation gave me a thorough understanding of the components API, and that creating the examples which will be used to explain said API was also a easy task, but that is because I’ve worked with Angular and UI Frameworks such as Material for almost a year now non-stop. To the beginner, to the one who’s experimenting with Angular Material for the first time, this documentation and API is daunting. Despite the well written content, proper examples help to truly establish a thorough understanding of the framework in my opinion.

For either example, the process was the exact same. Copy the foundation (Stepper Overview Example), and modify the attributes, title, and toggle logic to accommodate the specific example itself on one of the steps. This way, the examples mirror each other instead of presenting the reader with different context every time. The changes are borderline single line changes, but abstracted away to their own components for clarity:

Meeting Contribution Guidelines’ Compliance

This is the first project I have worked on Open Source wise which has a predefined commit message structure (which I totally love!) to make the development process both more uniform and accessible to those doing the review. It took a few commits to truly embed into my habits the proper structure, which looks like this (taken straight from CONTRIBUTING.md):

The documentation did not provide any Pull Request related specifications, so I did my norm and hoped for the best -making it clear that it’s possible I overlooked, disregarded, or even added too much to a specific area. Really, I gave them the putty and asked for hands to show me how to mold it to their liking.

Mold it they did, leaving comments on the code review which suggested a better practice, more uniform styling or removal of unnecessary code blocks. More on that can be found here. All of the first round of code review were stylistic changes, which I was happy to fix since it also showed a gap in my understanding of their accepted coding guidelines.

Thoughts so Far

Spinning wheel of Light

This is the first contribution I’ve worked on which primarily dwelled on documentation, my niche being more of that relating to accessibility or editor features. I like to think this is equally, if not even more, monumental because it makes the code base itself and the components which are offered to developers more accessible; enabling their work with far less friction so they can further push the technologies farther. Mmalerba has been incredibly helpful so far, and also very accommodative to a new contributor who does not know his way around the code base or expectations when testing and documenting their changes.

Furthermore, it’s awesome to pick up a technology that I feel proficient with for a change, instead of having to learn (which is great, don’t get me wrong) a new one including all the bells, whistles, errors, and painful realizations that you should have started weeks before. I’m confident that I still have hundreds if not thousands of hours to learn on Angular alone, but I also see it as a tool which I can already start giving back to in any way possible.


This is a follow up to my previous post, describing some examples and public issues which touch upon heading semantics and color contrast.

Four Individuals infront of Glacier

Headings

Admitting to Your Mistakes

South Wind Motel

As you would have guessed, even I found the issues discussed above in past work from two websites which I used to claim where the best I was capable of at that time. Even more so, now that I know of these issues (which I discovered while looking for examples), the urge to fix and improve upon is there. In the South Wind Motel Website, I improperly used a H1 for the hero component, which would be fine had I made that hero display ‘Accommodations’ instead of a tagline. This is how the page reads to screen interpreters right now (without worrying in this example of divisional area tag sementatics):

South Wind Motel Heading Fail
South Wind Motel Heading Mistake

This may look like a minor issue, but the pattern repeats on each page with different taglines, some often not granting proper title-like context such as Property or Trail, which become increasingly more vague. Still, you have to start somewhere I suppose.

Silver Maple Motel

A website done a year after South Wind’s was finished (which was a weekend project during Christmas break in my defence), Silver Maple corrected many of the layout and ‘aesthetic’ issues I had with South Wind’s. In doing so, I created a different pattern of heading misuse. Here are the obvious ones that a simple inspect element unveils:

  • I used H1s due to their styling and size as icons. Meaning every standard icon on the page is a H1, without text or proper hierarchy in the slightest.
  • The proper titles use H5, unsure why I went so low down the spectrum, but we jump from an icon of H1 to H5 titles
  • The parallax images and their respective titles are H3s, which really should be H1s since they define the separation of page contents and topics. Likewise there is inconsistent blurring in attempt to mitigate contrast issues which I’ll discuss in a later article.

Two Examples of Similar Common Mistakes in the Wild

AndroidPolice

I love this website, it has been my goto source of news for all things Android since 2011, and I have to this day always held high regard for the content and it’s writers who publish there. While inspecting the site, I only saw one major offence (in my opinion, I could be forgetting a rule since there are so many) when it came to header use. The navigation bar uses a H1 for the AndroidPolice logo, and the article titles start at H2. This means that ever page is interpreted this way:

Android Police Headings Mistake
Android Police Headings Mistake

This may be a very minor issue, perhaps not an issue at all (depending on the ruleset, I am in no mood to read through the documentation this year just to confirm the smallest, most minute of a detail with a overall non-offending site), but I found it interested in how headings were used to imply hierarchy directly from the site’s title.

PC World

Simply put from a quick inspection of an article (I imagine said patterns are throughout, since all CMS use templates to remove the grunt work): H1 for title (great!), H3 for subtitle / annotation…. not so great. Realistically, the guidelines do not imply a need for subtitles to have a heading, and I imagine this was used to leverage the H3s styling. Kudos for following expected heading semantics otherwise, every other title falls under the H2 use, making the page be interpreted in the following way:

PC World Headings Mistake
PC World Headings Mistake

Color Contrast

I decided to take a stroll through Modern Flat Web designs, and see if I could find any practice which was an instant red flag. I’m using https://speckyboy.com/flat-web-design/ which currates 50 ‘Perfect’ examples of modern web design, a perfect list to try and pick a few apart. Will I succeed? Read on!

Design Interactions without Code

Website Interactions Without Code Color Contrast Mistake
Website Interactions Without Code Color Contrast Mistake

Damn that’s a bright hero component, it’s eye catching and yet blinding at the same time. The hero’s text is very readable, until you notice the cursive text which I almost missed the first time glancing through. It’s the same #FFFFFF as the bigger text, so how did I glance it over so quickly? How did it not catch my gaze? Well because the contrast ratio of that specific background color (#3EC7C2) and the text (#FFFFFF 29px font size) is 2.07:1, which fails both WCAG AA, and WCAG AAA demands. For large text, the ratio must be 3:1 or greater, which this one still does not comply with. Not off to a great start from the first page alone, and the contrast compliance didn’t improve throughout the page either for most of the colorful elements. Sad, and we just began.

CraftsmanAvenue

Funnily enough, the design and overall approach here is much more subtle and well established. I decided to test the mission statement found at the top, which has a text color of #887771 and a background page color of #FAF7F6, together they form a contrast ratio of 4.00:1, so close. Many of the elements are basic hues off from WCAG AA Color Contrast compliance, so I moved on, feeling hopeful.

Stash Flat Icons

Blinding Image
….

Presenting, modern aesthetic. Colors so close together in the spectrum that you don’t need to test using a color ratio tool to identify compliance. I can barely read the list items, I dare you to without squinting. It was at this point that I decided we had a good assortment of color related examples which all could learn from.

Learning from These Items

While doing writing this follow-up, I found two really helpful links for headings and HTML semantics which I’ve posted below. I think that if every front-end developer went through and truly understood, it wouldn’t take long at all to reprogram our already-logic-driven minds to the true semantic structuring of headings. I cannot say how we can improve these types of color contrast issues, aside from being mindful and questioning if aesthetic such as flat demands such low contrast elements beside one another. Even in enterprise, it’s not unheard of for design to be beautiful, but inaccessible to many.

H1: Headings Are Important

Common Heading Mistakes

Part 1

Caterpillar on Human Wrist

Introduction & Screen Readers

Accessibility is one topic which not many take into account when designing and developing an application, website, or printed media even. The concept of visual and interactive accessibility relates to any medium which the user uses to discover and consume content from, and how different impairments hinder the common forms and designs useless and nonconsumable. Easiest way to explain that last statement is this example: Imagine being unable to read the standard news headline found on newsprint or websites, but still wanting to know what the world around you is doing. How might one approach this if they don’t wish to listen to a TV or Radio? How might one discover headlines around a certain topic that the locals gloss over? Screen Readers and accessible websites. This video can explain the concept and need far better than I ever could, and hopefully also provides a foundation which segues into the important attributes which screen readers utilize in more detail.

Element Hierarchy

Resource
Many developers disassociate the levels and semantics of element hierarchy when designing and developing, opting for H2’s because H1 is too big for example in article titles. Often, I’ve seen cases where the H2s were used for titles, and H4s used for subtitles. Though the overall aesthetic may look better for your needs, this does not comply with the established semantics which screen readers / interceptors read to the end user, furthermore it also messes with Search Engine bots looking for content on your website.

If it’s a more unified overall font sizing you’re looking for, use a normalizer stylesheet such as NormalizeCSS or a css framework such as Bulma.IO which dictates all text the be the same normalized size among supported browsers (implying that you will edit / extend for custom font sizing).

‘Fake’ Elements

Resource
When is a button not a button? Well, aside from the philosophical test which also has us questioning what truly is, and what isn’t, we can discuss again how different element tags provide unique attributes which are useful to screen readers and screen interpreters. Likewise, as the blog explains, these attributes are critical to proper understanding of a screen and the contents on the page. Using fake a tags styled to look like buttons, or divs with backgrounds meant to impersonate an image make interpretation of the page borderline difficult.

Contrast and Colors

Resource
It’s a good thing that most developers admit that they should never design, because in truth it’s not a skill many have in their genes. I suppose the opposite can be said for designers attempting to program, but I digress. Perhaps a different day’s story. When it comes to design, there is a ratio which many choose to ignore because modern aesthetic demands it, contrast ratio.

WCAG Level AA sets the golden standard for how the contrast ratio is defined, that is the difference between two colors (commonly background and foreground) such as text and parent element or borders and container backgrounds. AA compliance is a ratio of 4.5:1, which demotes many of the grey on gray choices of modern design. This is important because too little of a ratio makes text unreadable, and too high of the ratio is semi-literally blinding to even the common user.

Part One Conclusion & Examples

I hope to update this article later in the week with real-world examples and explanations of these details more, along with following up with the next segment which would include aria tags! If you made it this far, thank you for reading and I hope you enjoyed!

An OSD Contribution Update – Part 2

Getting up to Speed in the Late Hours

In my previous post, I went through a retelling of anguish, environmental issues and dead ends while trying to evaluate how a bug such as this was possible. Throughout the process, I kept asking myself and even the other developers, what is the scope? Where could this bug be created? The overall scope of QuickOpenController.ts is massive, since it acts as the User Interface between many mediums which all have their own set of requirements, validation rules, and user input rules to be enforced. The scope was never defined in the time that I had to work and understand the bug, so I began an old method which had proven to display results. I console.log’d, and alerted till I was blue in the face. Well, almost blue. I was a mix of 4AM hues: despair, desperation, frustration, and sleep deprivation by the time ‘results’ started to show themselves.

A couple of notes before I go on:

  • I owe a working with Git Bisect article, since this one still does not detail the process or my thoughts on said process. To remedy, I think I’m going to rename the article series from ‘Working with Git Bisect and Visual Studio Code’ to ‘The Trials of The Promise-Centric Input, a Visual Studio Code Story’.
  • The ending of this article has a rainbow, one which looks like a faded, easy to miss image which compares to tie dye shirts after they start to lose their luminance. It’s a happy, ‘look what I did hackers!’ kind of rainbow, but one that is also easily dismayed by a lack of confidence in the final fix.
  • My god have I learned how easily one can glance over the information they are looking for, unknowingly skipping the one line which has the answers to their questions. Thanks David again for finding the extension host argument for Code’s CLI.

Progress looks like a Pillow full of Sweet Nothings

Back on track, where a 4AM ‘all or nothing’ type of hacking session produced some of the most unexplainable, and yet tangible concept of how the code worked. Through the console logs and alerts, I learned how the doPick function worked against the user’s input lazily, validating only as conditions were changed instead of every keystroke being entered. It was there that I also managed to catch the scope where the cursor is moved to the back, progress! Now I could remove all breakpoints (saving me what would add up minutes of step throughs) and add them into this scope alone. Alas we are moving at lightspeed now R2.

Momento: Issue Found (Code)
A rare moment of light, where the comments reveal my inner thoughts as this little experiment produced golden results.

Following the same path of console logs and the infamous alerts, I managed to emulate a very basic A/B test where a console.log('PRE:', this) would occur prior to the cursor change, and the second console.log('POST:', this) occurring just after. I had cornered the function itself in between two statements which allowed me to check for state changes, while also establishing the direct line which changed it. I’m pleased to admit that it was from my first article’s speculation, I was very close to the money when I guessed that the value being set each time caused the cursor to move to the (default) end of line.

Break All the Things

Imagine yourself ambushing a single function, knowing that when it’s called you’re watching it’s every move, it’s every operation. What do you do to confirm that the function does indeed know where the rainbow’s located? Well, I decided to break it. Moreso, I decided that my first step (as one may do when asserting dominance), was to make it disappear.

Making it disappear broadcasted an overall UI change which was hard to miss, and also a removal of the bug itself. Still, I couldn’t just leave it commented out and helpless. I removed the comment-line restraints from the conditions found here, and left this.pickOpenWidget.setValue(...) commented out. Now, we were fishing to see which logical block led to the amazing wonders which is well-deserved sleep. It became clear after my next round of reproducing the error that the function itself being called causes the cursor jump, and from my opinion, did not need to be called in every single case.

The logic fix that I opted for which did cover the two edge cases described was to check if the validation process had started, meaning when options.valueOptions existed then the user had already begun to input into the component, and we shouldn’t be redrawing the input with the previous state -autofocusing in the process. After this corrected the initial issue, I went about testing other command palette functions to ensure that I had not tampered with other bits of functionality. When all was good, I slept.

The Rainbow at the end! Photo by Sam Kulesh

3 Hours Later: Conclusions

The final resolution that I came up with can be found here, which contains a pull request being reviewing and evaluated for the validity of the fix -a case I knew would occur since this fix affects almost all non-editor related user input such as the command palette, file opening, symbol finder, etc. Even as I’m writing this, I’m not confident that the fix itself is the most correct of all possible ones, since the scope and affected functionality rings through many other edge cases. Imagine changing how a paragraph tag works on your average website; that big of a change.

Custom Function Reproducing the Error... Fixed!
Custom Function Reproducing the Error… Fixed!
Azure Functions Error Replicated... Fixed!
Azure Functions Error Replicated… Fixed!

An OSD Contribution Update – Part 1

Header Image

While working towards implementing a fix for this bug, it was made clear to me that the bug was a regression, and not evident two months or so ago. This led David to directing me towards his (awesome btw) tutorial on how git bisect works, and how developers use it to determine where in the version history the bug was introduced. I’m glad that this concept existed, for even at work a few colleges and I attempted to replicate the similar behavior by hand, unaware that such tools already existed and was widely available.

Some background details that I had collected prior to me starting the bisect process:

  • I knew that the current master branch contained the issue. According to the comment thread, this issue had arrived around a month or two ago.
  • The Azure Functions validation logic is intact and functioning as expected, so the bug itself derives from refocusing the input after rerendering post-validation, a lifecycle which shouldn’t occur to begin with.
  • A custom extension could be created (and was provided in the bug description) which replicated the error.

First Steps – Identifying a Working ‘Good’ Commit!

In git bisect, you identify a good and bad commit range, which is used to isolate and pinpoint where the commit occurred which causes the bug. I wanted to identify a good commit prior to entering the process where the bug was not present so that the process would go along smoother. I started as early as git commit 834ba9b, and moved my way down the following commits to identify a ‘good’ commit:

  • 249a796 – November 20, 2017 – Still broken!
  • 83d8cbe – October 2, 2017 – Still broken!
  • 08d8f0f – September 25, 2017 – Still broken!
  • a87dd9c – August 21, 2017 – Still broken!

My Brain After This
Broken Down Bus

It was here that I decided there were two choices, continue going down this rabbit hole with the next commit jump being all the way to January 2017, or I admit that perhaps this edge case always existed and in consequence, needs to be addressed with the latest code base. I’ve decided that I want to go down the rabbit hole all the way to January 2016 if it produces a different edge case at least. That will be the introduction to part two, which I hope to publish in close succession to this first post.

Below are some of the issues which I encountered while working out this bug, and what caused what felt like work-week-long delays in between progress.

How far back I can go!

Trials, Errors, Showstoppers along the Way

Before I even started with the bisecting process, I knew that I had to attempt to replicate the bug in the development version of Visual Studio Code. Two hours later, here is what I learned:

  1. The Extension Gallery and it’s respective API do not exist as a part of the developer / open source Visual Studio Code. They exist similar to a feature toggle, which Microsoft activates in the production version, this being due to some licensing concepts and beliefs which is explained in much better detail here.
  2. You cannot sideload an extension easily without the Gallery API, which led me and hundreds of others who created, browsed, or cried for answers relating to this issue to a stackoverflow answer like no other. The code needed to be added to product.json:
  3. Extensions hook into a proxy-esque API (depending on their required context), meaning this process of using git bisect is entirely based on faith that the extensions themselves are not the issue. If they produce the error, your scope broadened 10x.
  4. Because all things must have versions and updates, it’s entirely possible while going forward / backward to encounter where version mismatches causes the extension or host editor to not be compatible.
    Version Mismatch with Azure Functions
  5. It is entirely possible because of the number 4, you will have to create your own extension. This is a battle of itself which I will describe below more.

Custom Extensions To Replicate Broken Edge Case

In the original bug, the reporter provided example code which when run, replicated the issue itself without an official extension. The tradeoff? Well you have to create a local temporary extension that Code will compile and attempt to integrate into its infrastructure. Issue? Well similar to the Extension Gallery being not included with the development version of visual studio code, neither is the node debugger and or compiler. These are extensions which are included by default with Microsoft’s release version. In attempt to mitigate before I get very hacky, I side-loaded the extensions gallery in the same way described above, and then installed node debug and node exec. The first allowed for successful execution of the environment (more on that), and the later is incase I could find a way to bleed / inject my custom function into the live environment.

I was able to follow the Microsoft documentation for creating and launching an extension with my standard version of Code, but that doesn’t help unless I’m debugging against the latest release (1.21.1). A few Github threads specify fixes for this issue so that you can bootstrap the production-built debug instance through your developer instance, but so far results have been less than stellar on MacOS and Linux. My worst case scenario that I think I will try if no further progress is made with the previous approach is to debug the latest (again), but this time focus on the validation handler, referencing commits which change its surrounding scope for example.

Important Update:
Thanks to David, whose eyes and searching skills proved themselves far better than mine, I was able to sideload the custom extension consisting of the following code into the development version of Code with this command: --extensionDevelopmentPath=\....

The extension which replicates the bug itself is:

Dependency Issues with Linux (Fedora 27) While Rolling Back

I encountered many dependency and build process issues on my Fedora 27 box while moving between commits, often cleaning /tmp directory to see if the issue was related to version mismatch. Later after some Googling I found that some of the issues related to NPM’s handling of file systems and permission, which was equally terrifying as I began to experiment while looking for a fix. Who wouldn’t be terrified after this lovely fiasco After about an hour or more of attempts, I moved to MacOS to see if that process would be smoother. If so, I can admit that my linux workstation probably needs a clean-up / reinstall, having served me and thousands of packages / files well for over two years without major issues. After I moved to MacOS on High Sierra 10.13.3, the issue relating to the different build systems was not apparent.

When I first started contributing what I could to Visual Studio Code, I was under the impression that it was written using React. Even while working with the custom drop down component, I was still under the impression there were React Front-end technologies which enabled for the dynamic rendering of various components and functionalities. Only in recent, while debugging and looking for high-level understanding of different scopes, did I realize that Visual Studio Code developed without the front-end JavaScript frameworks such as Angular, Vue, React or even MeteorJS. Without sounding like I just discovered Pluto being once called a planet, this was very left field.

Programmatically Generated UIs is a term I’ve heard while doing research on iOS Development practices, but I never considered a full-blown web application (including all the HTML attributes and so on) being powered in such a way. I remember using basic JavaScript to change the DOM while learning how to do front-end validation for INT222 (now WEB222) at Seneca, but never to generate entire navigation bars or full-blown text-editors; the concept and understanding of said concept is both the scariest, and most interesting discovery I’ve attempted to learn and dig deeper into in the past few weeks. Looking back at the custom drop down source code, I realize that I was so caught up in the state persistence and accessibility concern of the bug I was working on, I never realized just how genius the component’s implemented; in-house, no external frameworks or libraries.

The Flipping of Comfort and Concerns

In every project to date; be-it Enterprise for SOTI, Open Source, or even just Seneca course projects, I’ve never considered a programmatically generated and managed user interface. While looking more into Visual Studio Code’s logic, I instead of becoming familiar with it, began to become more concerned quicker and quicker as I had to search for life cycle handlers which a standard layout or framework would handle. DOM manipulation is one thing, but recreating, redrawing, and DOM-managing the entire component while all being in-house along with storing application state is very much left field compared to my experiences. While looking over the code, I did find two valid and worthwhile reason for such design practice, which I’ll explain below.

The Liberation from Framework Idioms

In the past year working with Enterprise level Angular applications, I’ve come to understand the saying ‘going against the grain’ when it comes to working with frameworks and libraries; they are amazing when you implement within their design and allowance, and an absolute nightmare when the scope goes beyond or against the framework’s design. I see with Visual Studio Code, the happiest of mediums where more time dedicated on design and development, and less on fighting the code and assets which make up your product.

Examples

Adding all event listeners to the custom drop down element

Dynamic styling of the drop down based on context

Creation of the select list HTML element

Deeper Management of Application Logic and Views

Compared to having multiple components, edge-cases and sub-component requirements, you can manage all of which (cleanly) in a single well encapsulated scope. This is only possible because of the (granted, concerning) freedom which programmatically managed interfaces offer, since scopes of the element such as data, state, and interface itself derive from the same scope: in a single language and instance (compared to Angular’s HTML, TS, and SCSS separated file structure). One video that I had discovered last year which explains the benefits and reasoning why even iOS developers going this route compared to creating storyboard layouts:https://www.youtube.com/watch?v=up-YD3rZeJA

Final Thoughts

I’m looking forward to exploring new concepts such as this as I go about Visual Studio Code, and hoping that I never stop being thrown into challenging or adventurous situations where the only way out is to learn and understand it. I’m sure I’ve only uncovered only 5% of the entire concept, still unsure of every reason behind it, and even the proper implementation paradigms in Code; going forward with the bug fixes and improvements I hope will explain more and make me a better developer in the process.

How I Approach Bug Fixes in a new Code Base

February 22, 2018 | Open Source | No Comments

The one thing that Humphrey said which really resonates with me on the topic of bug fixing is summed up as this, “[on bugs] they’re easier to understand since the code foundations have already been laid out before you, all you have to do is understand it”. Even at work, I found myself for the past 4 weeks focused on bug fixes to our product prior to the Mobile World Congress (MWC) event, so I was both sick and very well experienced in trial-error approaches towards bug fixing. Here are three concepts / thoughts which I find often result in a step in the right direction when it comes to solving the infamous issue, resolving the ticket, or adding the feature which exists in a different scope.

Is the Bugfix a result of Data Corruption and or Race Conditions?

This issue I find a lot working with ‘data-driven’ applications, the type of applications where charts, tables, and UI elements themselves are powered by JSON responses from a backend. In this case, the expected response (contract) differs from what is actually returned. In my first COOP with TechnicalitiesPlus, part of the learning experience was debugging and discovering that the front-end code itself functioned as expected, and it was the persisted data which had changed. This break of contract / agreement is often easy to overlook, assuming that the data itself is always the expected ‘source of truth’. The issue which led to this experience? The JSON array was returning objects which lacked very specific attributes which existed in the database. This caused failure to render and a very frustrated 19 year old to lose hours thinking it was Front-end logic creating the issue. The amount of hours I spent learning that scope inside-out before verifying the data response itself is a lesson that I will not forget, and it is why my primary debugging check is to verify the data.

Is The Requested Feature Already Implemented Elsewhere?

I find a lot of the bugs that I commit to are feature extensions to an already working component, so this question often comes up quickly when I start going crazy with the keyboard and terminal. Often, the feature exists in a different scope such as a dropdown, component, or platform even. If so, you then have a good base to research and understand how said base was implemented, thus granting you a giant leap ahead. For my two accessibility bugs as of last week, neither were applicable for this approach. That being said, my good friend Svitlana’s (who can be found here) recent work with Visual Studio Code followed this exact pattern with her bugfix / improvement. Her approach was very similar to this, first discover where the functionality exists and understand how it works from there. We toyed with the idea of copying the entire function over to the new scope, or importing it directly; both ideas replaced with a much more suitable IAbstractAction class implementation which would call the imported function within the required scope. Essentially, it replaced the original idea of reverse engineering and dozens of lines of code with a single, fifteen line IAbstractAction class which did not repeat code or produce a new scope riddled with potential issues.

Will Calculated Trial and Error Produce a Visual Difference and or Indicator?

This is more of a workflow paradigm that I’ve adopted from the first days at Seneca, where if you don’t understand how to fix or implement a working concept, essentially do ‘smart’ brute force attempts. What do I mean by smart? Well, don’t make the mistakes that I did at first where every single compiler error results in a different implementation. First, focus on the scope which affects your area of the bug. Try to understand its circles of scope and interaction, and from there reach out to all that the scope touches where applicable.
Once I understand the basics of the scope such as adding a button to a list of common functions, here is the ‘smart’ brute force direction I sometimes approach issues from:

  • Add a static button to the list forcefully, omit programmatic idioms for now, do you see the visual change?
  • Make the button produce an alert / visual indicator of user interaction and handling, is the event handler working?
  • Now attempt to add the button programmatically if appropriate, does it appear? Make it.
  • Make said button’s scope directly relational to the scope you’re working with, does it interact with the components data, DOM, or other functions?

If the first failed, I’d probably try as many alternatives to adding the button to the DOM as I could. Only then, would I attempt the second point. Likewise with the third and fourth. This method of attack maybe is not the most efficient, but it produces a thorough understanding of the scope and attempts made to work in said scope. I find myself following this approach less and less as experience in the project grows, but I cannot deny just how much time I wasted using said approach, and the results which were produced only being possible in such a way. Break the DOM or logic 20+ times in 30 different ways? Check!

In the End, the Direction is What Matters

I keep saying ‘step in the right direction’, because I truly believe that if you’re new to a code base, it’s easy to get lost in all the functions, methods, variables; the lights and darks. I love the reinforcing concept of taking a ‘good’ step, meaning taking the risk and or time which results in me being closing to where I need to be to achieve this bug fix or feature implementation. Nothing is more depressing than taking a step and falling that much deeper into confusion or misdirection. It’s just like finding treasure, once you find enough clues or the map itself, and take the path which leads you to the correct direction, you’ll find the chest full of gold!

Debugging Freedom
Freedom

An OSD Contribution Update

For the last three years, I’ve grown a passion for extending technologies towards a direction which makes them more accessible for a wider range of users. It took a while to realize what accessibility truly meant in the world of development, software, websites and health organizations. Through the process, I took a course on behalf of my employer at the time to learn the three levels which make up the Web Content Accessibility Guidelines (WCAG) 2.0, A, AA, and AAA. This course took me through so many spirals of knowledge and issue, all-encompassing different scenarios and acceptance criteria for web development. After taking the course, I started to see software design and accessibility very differently. Contrast between colors, element organization, font-sizing even became subject of my mental focus at first.

When looking for issues and improvement requests in Visual Studio Code, I decided for this round that I wanted to explore and help improve how we handle accessibility within the platform. This led me towards two bugs which relate directly to the newly released custom drop-down component which was apart of the February 1.20 release. I thought this would be a great outlet for contribution since it’s a brand new component to the project, enabling me to also seat myself if possible in that domain and help update and upgrade the component over time.

Monokai Drop-down Selection Theme

This bug was originally an issue directed towards how the Monokai theme handled drop-down selection indicates the currently selected item. After discussing in the issue how to handle the fix, a proposed quick solution was implemented and tested. Changing the list.focusBackground to a different color of the Monokai theme, thus ‘fixing’ the issue.

The reason why I said ‘fixing’, is because this very small, single line fix also produced evidence towards a bigger issue with the drop-down component which would span all custom themes. Essentially, there was no way to promise this improved accessibility for custom themes which set list.focusBackground to a non-common theme color, since the attributes used in many components alongside the drop-down.

Christopher Leidigh known as @cleidighon on GitHub, developer for Visual Studio Code, and also contributor to the new drop-down component provided a non-intrusive update which provided a new attribute titled dropdown.listBackground which is used by the component if it exists. With this update, switching list.focusBackground back to the previous color and using dropdown.listBackground provides the bugfix without breaking the established patterns of decade old themes, and custom editor themes. I have a feeling that this will be expanded later to accommodate APIs and contrast-awareness functions. The final PR can be found here

Escape Key Should Revert Selection to Previous State

Again approaching accessibility improvements and learning more of the drop-down component, I was introduced to this bug. Essentially, it is a request to return the common behavioral pattern of when a user hits escape during text input modification, return to the original state. A simple concept, and I had an idea which is in my work in progress PR which is found here.

Essentially, store the currently selected index when opening the drop-down component, and in onExit and onBlur restore the selected item back to the original state. Simple enough I think. There isn’t any magical React / Redux paradigms occurring here, so I feel pretty confident in my initial approach and, based on Christopher’s initial review of my attempt, we share the same mindset for this update.

Conclusion

Was this a huge contribution / release? No. That I can admit, and if I do have time I’ll try to find a bug to make up for the lack of substance. This round of open source interactions allowed me to discover a few interesting lessons, some of which I consider as valuable:

  • A single one line bug fix can produce a tentacle of other bugs and or politics.
  • Accessibility is a characteristic which can be easily overlooked, and is overlooked often times by the common developer.
  • Working remotely with developers in different time zones can create one of the most interesting plots of disconnect and resource-management that I’ve ever seen. You see their replies in the morning when perhaps they are calling it a night. This grants you HOURS before they’d see your reply, providing space and resources to plan out both your intent and knowledge base towards the issue and the reply. Likewise, it’s very easy to fall into the trap of waiting around for a reply as I did during segments of this release, which is ill-advised if one is seeking continuous progress and movement.

Going forward I really hope to discover more improvements or bugs relating to the drop-down component or various other UI elements, ones revolving around accessibility being preference. Code is so much bigger than I would have ever imagined, and seeing the following response from a well-respected Developer such as Christopher admitting that even he is only scratching the surface lifts my spirits when I find myself lost in endless lines of code and confusion. With each new experience, I look forward more and more towards the next step into Open Source.

I love Bulma, I love contributing to projects instead of spinning up my shoddy implementation of a need, and I love when the two come together in such harmony it’s as if fate meant it. I discovered BulmaPress while looking for Bulma / Non-Bootstrap WordPress themes for a CMS project I’m working on. It looked to be relatively abandoned, sporting an old version of Bulma 0.2.1 and last being updated half a year ago.

Still, this didn’t deter developers including yours truly from forking and fixing or updating; a relatively painless experience since the project was built on-top of the underscores project, providing a solid foundation which only needed the Bulma part to be updated instead of the WordPress theme functions. It took several iterations to get the modern Bulma navigation pattern to work as expected, but once that was in place (you can see the code change required here), the rest fell much quicker.

Instead of keeping the fix to myself, I decided that any updates should make it upstream to benefit other users who discover the project. These fixes included removing the outdated Bulma code (replaced with a CDN), fixing the SASS compiler, and now writing a stable override structure which provides easy modification of Bulma variables.

The SASS was priority in my mind after correcting the navigation since no one sticks with the defaults, almost ever. Writing in CSS is a pain when it’s a full website theme, and once you learn SASS, SCSS, or LESS, CSS functions like assembly in comparison. Literally! For my project, I also needed the SASS configurable since this project would involve multiple different overrides and branding elements too.

As my first contribution got merged in, I became a contributor to the project and was also promoted to maintainer (meaning I could merge, triage etc). It’s a cool experience to see yourself at the top of a contributor board on an abandoned project: https://github.com/teamscops/bulmapress/graphs/contributors. The numbers do seem off, but I’ll let the GitHub magicians assume what they will about code changes. Later on, I’d begin to have questions tweeted or emailed to me on BulmaPress, which was another cool moment because I realized this abandoned project still had love from developers who perhaps like me, needed exactly it.

This is my first time working inside-out on a WordPress theme, my only previous experience being changing the default layout of the theme to support Bootstrap headers for a client two years ago. Working with only foundation, knowing that everything else can change if needed was an opportunity that I didn’t expect from BulmaPress. I had different ‘implement this feature so you can use it’ styled expectations, not so much ‘update this because a lot has changed in recent years’. There is still a lot to update and fix, such as the navwalker used for multi-tiered navigation menus (Which I don’t believe ever worked to begin with according to comments in the code), and fixing the demo domain issue where you which expired in January.

An OSD700 Contribution Update

Interesting concept, it’s a very surreal experience to explore and work on a project while using said project as the tool for development and exploration.

For a good part of the weekend, I’ve put aside time to look into how Visual Studio Code handles and manages the Command Panel, a tool / extension which I use daily for accessing various extension actions, configurations, and accessing files. The reason for trying to undercover the goldmine which is le Command Panel can be found in my attempt to add a color picker toggle to the list, a work in progress pull request can be found here.

Fully Customized VSCode, Command Panel Displayed

Attempt #1

My first attempt towards adding a command to the command panel was based off of how the comment extension accessed the panel. Later I would be pointed to a better example which I address in Attempt #2. In this attempt, I tried to create a wrapper which would expose the ColorPickerWidget class to the command panel, similar to how it is done here.

The idea at first made sense, till I realized that the implementation of CommentLineAction was directed to manipulation of the code close to the cursor. Furthermore, I didn’t need the kbOptions related scope in this case, since the original intent is simply to toggle a Color Picker through the command panel. I should have kept the code as an example here of what Attempt #1 looked like, but I had reverted back to the branch’s version prior to writing this post.

Attempt #2

After much research and discussion over the VSCode Slack Channel, I came to the conclusion that the first attempt should be redone using a better reference: hover.ts, which compared to comment.ts, provided a much better context. Thanks to Eric Amodio (Creator GitLens) for the tip there!

Attempt 2 for Color Picker

Through this process of trial and error, I learned the basics of how the command panel worked: How commands and context are loaded into its elasticsearch-esque data-store, how said commands call different scoped functions and contexts, and how to add my own command into the mix!

Putting EditorActions (Commands) into the Command Panel

A command you see in the panel is really an extension of the abstract class EditorAction, which extends EditorCommand. This extension allows for one to program the context of how the implemented run command, contexts, editor-permissions, and keychords while providing a type inferred structure which is compatible with the original EditorCommand interface.

You can see in the snippet of code linking to my second attempt, the super call in the constructor handles creating a IActionOptions object, which is an extension of the abstract class ICommandOptions. It is this portion of the object which is placed in the Command Panel to provide context, labels, translation and scope. The Comment extension ~/src/vs/editor/contrib/comment.ts shows the alternative way of handling the IActionOptions, which you can see below. I prefer this method due to a much cleaner and easier to read since the scope does not include the functionality, but the command alone.

The final part is to call registerEditorAction which is imported from ~/src/vs/editor/browser/editorExtensions as you may have guessed. The total amount of imports from that file derives directly with the context and actions that your command will need or perform, below I’ve listed the common ones which I encountered when looking through the comment, and hover extensions.

EditorCommand

Location: Github Link
The function which extends Command, and provides the inner-architecture required to bind and remove actions to the command panel. It’s public functions are:

Command

Location: Github Link
Command is the base class which appears to be replacing (based on the commit history favoring it over ICommandOptions for updates / improvements), and is extended by EditorCommand.

ICommandKeybindingsOptions

Location: Github Link
ICommandKeybindingsOptions appears to act as another context-aware object, this one containing an optional weight (of importance / override?) variable which makes me believe that this is used for keyboard chords (ala Emacs) and priority only-after the precondition in Command has been met.

IKeybindings

Location: Github Link
This class is extended by ICommandKeyboardOptions, which provides the correct keyboard-codes for Emac style keychords.

ICommandHandlerDescription

Location: Github Link
As the name suggests, this object handles description of the Command Object, not to sure to be honest what the purpose of this object since all labels are handled at the root of the object which would be displayed.

ContextKeyExpr

Location: Github Link
The ContextKeyExpr is an abstract class which contains the following public functions for working with the cursor:

IEditorCommandMenuOptions

Location: Github Link
This class appears to dictate the context of when an action is available in the command panel, checking against the ContextKeyExpr object it appears.

Making Your Command Execute Specific Scope & Functions

In the class which extends EditorAction, you have to implement the function titled run. This function is crucial, for it is exactly as you’d guess, the code which is hit upon calling your command from the panel. Since my own isn’t 100% complete at the time of writing this blog post, I’ll reference comment.ts again for how a proper run implementation works.

It is still unclear to me why editor.pushUndoStop() is executed twice, perhaps to correct duplicates? Perhaps I still have more to research and understand regarding the command panels data store, for the only hint I found being the code comment itself, Push an “undo stop” in the undo-redo stackfound here

ICodeEditor

Location: Github Link
An interface of the editor itself. Listening for events and acting as the glue between the user’s keypresses and the rest of the system. This is fed into the run command to provide access to context, events and user input. If that doesn’t provide enough weight towards just how powerful this interface is, the current structure spans 409 lines (which does include 5 lines roughly of TSDoc providing documentation to an estimated 81 (409 / 5) functions!

Comment Command Action

Conclusion to this Experience

I can admit there will probably be quite a few mistakes, missed scopes or crucial details that a weekend of research and speculation cannot provide, but in that time I’ve tried to acquire as much as possible, in the process learning a great deal of how Code’s command panel operates, the overall architecture relating to the editor and it’s extensions, and how CMD+T (or CTRL + T on Windows and Linux) brings up a contextually aware panel full of options and usability. I cannot understate just how vital it is to seek guidance from other developers, developers who have already contributed and work to the project and thus, can help guide you through the never-end maze of classes, interfaces, services, observables and architectures which make up such a huge project.

On an architectural footnote, VSCode (and perhaps in response, React) follows a very different order of components, services, and delegation of tasks compared to Angular does. The difference is quite colorful at first, some being obvious compliments such as Observable / RXJS patterns, others being grotesque and difficult to understand. I was looking forward to both ends of the spectrum jumping in, for it allows me to compare and perhaps even evaluate the different development decisions made between my own projects, work projects, Code, and tutorials. I hope that through this, future projects are inherently improved upon in design and implementation from said experiences. Interestingly enough, I’m reading The Art of Unix Programming by Eric S. Raymond, which provides different insight still relevant even this day to the idea of software development and architecture. The parallels between Code and Unix’s philosophy appear more and more the deeper I look, and I’m hoping to gather enough on the topic to write a blog post later in the year explaining such.

.