Menu Search
Jump to the content X X
Smashing Conf Barcelona

You know, we use ad-blockers as well. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf Barcelona, dedicated to smart front-end techniques and design patterns.

I Contributed To An Open-Source Editor, And So Can You

A few months ago, Jason Grigsby’s post about autocompletion in forms1 made the rounds. I loved the idea of allowing users to fill in their credit card details by taking a picture of their card. What I didn’t love was learning all of the possible values for autofill by heart2. I’m getting lazy in my old age.

Lately, I’ve gotten spoiled from using an editor that does intelligent autocompletion for me, something that in the past only massive complex IDEs offered. Opening my editor of choice, I created an input element and added an autocomplete attribute, only to find that the code completion offered me the state of on or off. Disappointing.

What I wanted was the following:

All possible values for autocomplete offered by this editor

All possible values for autocomplete offered by this editor

The great thing about our development environments these days is that we build the tools we use in the technologies that we use them to write. Yes, this sounds confusing — we’ve reached code Inception. Node.js3 allows us to run JavaScript on the back end, and with Electron4 we can create installable applications for all platforms using HTML, CSS and JavaScript.

Further Reading on SmashingMag:

Atom9 was the first editor to use this technology and to allow for contributions by being open source, closely followed by Microsoft’s Visual Studio Code10.

Almost all of the other editors in use allow us to write extensions, plugins or snippet collections in various formats. I deliberately didn’t want to write a plugin or extension, but rather wanted to add this functionality to the core of the editor. Plugins, extensions and snippets have their merits; for example, they are easy to update. The problem is that they need to be found and installed per user. I considered autocompletion too important and wanted to hack the editor itself instead.

Both Atom and Visual Studio Code are available on GitHub and come with instructions on how to extend them. The challenge is that this can feel daunting. I’m here today to show you that it isn’t as tough as you might think. Visual Studio Code is my current editor, and it features amazing autocompletion. That’s what I wanted to tackle.

Extensible and customizable tools are nothing new. Most of what we use can be extended in one way or another, whether in the form of add-ons, plugins or specialist languages. The first editor I used in anger was Allaire and Macromedia’s HomeSite11, which had funky languages like VTML12, WIZML13 and JScript, the Windows version of JavaScript at the time. I wrote a lot of extensions and toolbars for that editor, which very much boosted the productivity of my company back then.

Thankfully, these days, companies understand that offering specialist languages is time wasted, when the web stack has grown to become much more interesting to build applications with.

If you download Visual Studio Code now, you will see that my autocomplete feature is a part of it. And here is how I did that.

1. Complain Link

My first step was to go to Visual Studio Code’s GitHub repository14 and file an issue15 requesting this feature for the editor. This could also be your final step if you don’t want to do it yourself. Someone else who is looking for something to do for the project might find your complaint and tackle it for you. In my case, I wanted to find out more.

2. Fork The Code Link

Instead of just filing an issue, I went to the GitHub repository and forked the code. I used my personal account for this. You don’t need to be affiliated with Microsoft or get added to a special group. The repository is public and open. Everybody is welcome. There is even a code of conduct for contributions16, which means that people should be playing nice. I downloaded the code to my hard drive and followed the instructions on how to build the editor locally.

3. Get The Development Workflow In Place Link

Visual Studio Code is written in Node.js and TypeScript. The development flow starts with a script provided by the team, which gives me a development version of Visual Studio Code running next to the one I am using. A script running on the command line ensures that my changes are captured and that every time I save my code, the development version of the editor restarts and I can test the changes. All of this is nicely documented, from building and running the code from source17 to setting up the development workflow18. And it is independent of platform — you get instructions for Windows, Linux and Mac OS X.

You can see what this looks like on my computer in the following screenshot. The large-view editor (1) is the one I use to code the other; the one on the right (3) is the development edition; and on the bottom (2) is the script creating the new version of the development edition. Writing an editor in an editor does feel odd, but you get used to it.

Figure 219

(View large version20)

Don’t get discouraged if all of this doesn’t work for you on the first go. I hit a few snags and had to turn to Google and StackOverflow for solutions. The Node.js community was very helpful.

4. Write The Functionality Link

Next, I was ready to go all in and use TypeScript to write some clever code. I understood that this is where a lot of people throw in the towel, considering it too tough to continue.

My biggest issue was that I had no idea where to begin with this functionality. So, I did what we all do: I did a full text search for autocomplete in the whole project. Using this highly scientific approach, I found an htmlTags.ts file full of tag definitions and arrays of attribute values. I looked up the input element and found this:

input: new HTMLTagSpecification(
        nls.localize('tags.input', 'The input element represents a typed data field, usually with a form control to allow the user to edit the data.'),
        ['accept', 'alt', 'autocomplete:o', 'autofocus:v', 'checked:v', 'dirname', 'disabled:v', 'form', 'formaction', 'formenctype:et', 'formmethod:fm', 'formnovalidate:v', 'formtarget', 'height', 'inputmode:im', 'list', 'max', 'maxlength', 'min', 'minlength', 'multiple:v', 'name', 'pattern', 'placeholder', 'readonly:v', 'required:v', 'size', 'src', 'step', 'type:t', 'value', 'width']),

That autocomplete:o looked interesting, so I checked where o is defined. Here’s what I found:

var valueSets: IValueSets = {

…

    o: ['on', 'off'],

…

}

That looked like what was happening when I added an autocomplete attribute. To change that, I went to the standard definition of possible autocomplete values21 and copied them.

I created a new value set named inputautocomplete and pasted in the values:

var valueSets: IValueSets = {

…

    inputautocomplete: ['additional-name', 'address-level1', 'address-level2', 'address-level3', 'address-level4', 'address-line1', 'address-line2', 'address-line3', 'bday', 'bday-year', 'bday-day', 'bday-month', 'billing', 'cc-additional-name', 'cc-csc', 'cc-exp', 'cc-exp-month', 'cc-exp-year', 'cc-family-name', 'cc-given-name', 'cc-name', 'cc-number', 'cc-type', 'country', 'country-name', 'current-password', 'email', 'family-name', 'fax', 'given-name', 'home', 'honorific-prefix', 'honorific-suffix', 'impp', 'language', 'mobile', 'name', 'new-password', 'nickname', 'organization', 'organization-title', 'pager', 'photo', 'postal-code', 'sex', 'shipping', 'street-address', 't].sort()el-area-code', 'tel', 'tel-country-code', 'tel-extension', 'tel-local', 'tel-local-prefix', 'tel-local-suffix', 'tel-national', 'transaction-amount', 'transaction-currency', 'url', 'username', 'work'],

…

}

I then went to all of the definitions of elements that support autocomplete and replaced the o with my own inputautocomplete:

input: new HTMLTagSpecification(
        nls.localize('tags.input', 'The input element represents a typed data field, usually with a form control to allow the user to edit the data.'),
        ['accept', 'alt', 'autocomplete:inputautocomplete' … ]),

I saved my changes; the script rebuilt the editor; I tried the development version of the editor; and autocomplete worked the way I wanted it to.

5. Send A Pull Request Link

That was that. I committed my changes to Git (inside Visual Studio Code22), went to GitHub and added a pull request. A few days later, I got a comment saying that my pull request went through and that what I did would be part of the next build.

6. Be Baffled Link

Frankly, I didn’t think this was amazing enough to warrant a change to the core of the editor. I just wanted to play around. Many of you might think the same about the work you do. And that’s the thing: We’re wrong. Contributing to open-source projects doesn’t require you to be an amazing developer. Nor does it require you to be famous or part of the in-crowd. Sometimes all you need to do is look at something, analyze it and find a way to improve it.

It is up to us to make the tools we use better. If you see a way to contribute to an open-source project, don’t be shy. You might be the one who comes up with an idea so obvious and so simple that others have overlooked it. You might be the one who makes something more usable or nicer to look at. We all have skills to contribute. Let’s do more of that.

(al)

Footnotes Link

  1. 1 https://cloudfour.com/thinks/autofill-what-web-devs-should-know-but-dont/
  2. 2 https://html.spec.whatwg.org/multipage/forms.html#autofill
  3. 3 https://nodejs.org/en/
  4. 4 http://electron.atom.io/
  5. 5 https://www.smashingmagazine.com/2013/12/open-sourcing-projects-guide-getting-started/
  6. 6 https://www.smashingmagazine.com/2010/03/a-short-guide-to-open-source-and-similar-licenses/
  7. 7 https://www.smashingmagazine.com/2013/01/starting-an-open-source-project/
  8. 8 https://www.smashingmagazine.com/2010/09/the-case-for-open-source-design-can-design-by-committee-work/
  9. 9 https://atom.io/
  10. 10 http://code.visualstudio.com/
  11. 11 https://en.wikipedia.org/wiki/Macromedia_HomeSite
  12. 12 https://en.wikipedia.org/wiki/VTML
  13. 13 http://www.ulitzer.com/node/41695
  14. 14 https://github.com/Microsoft/vscode/
  15. 15 https://github.com/Microsoft/vscode/issues/7142
  16. 16 https://opensource.microsoft.com/codeofconduct/
  17. 17 https://github.com/Microsoft/vscode/wiki/How-to-Contribute#build-and-run-from-source
  18. 18 https://github.com/Microsoft/vscode/wiki/How-to-Contribute#development-workflow
  19. 19 https://www.smashingmagazine.com/wp-content/uploads/2016/08/editor-large-preview-opt.png
  20. 20 https://www.smashingmagazine.com/wp-content/uploads/2016/08/editor-large-preview-opt.png
  21. 21 https://html.spec.whatwg.org/multipage/forms.html#autofill
  22. 22 https://code.visualstudio.com/docs/editor/versioncontrol

↑ Back to top Tweet itShare on Facebook

Chris is a Developer Evangelist living in London, England, who writes about Javascript development, accessibility, and all things open web. After several years evangelizing at Mozilla Foundation, he's now working at Microsoft's EdgeDev team.

  1. 1

    Re: “A few days later, I got a comment saying that my pull request went through and that what I did would be part of the next build.”

    Yes, but what if it wasn’t accepted? Or worse, what if it were rejected AND there was snarky/negative feedback. It’s not like developers are known for their wonderful personalities and an understanding of “customer service.” Gawd, Miss Manners would die if she ever went on Stack Overflow, or had a thought that deviated from the “conventional wisdom” of (say) the WordPress “community.”

    Perhaps the problem isn’t the giver. Perhaps it’s the receiver? Maybe in a future article you can discuss that?

    12
    • 2

      Christian Heilmann

      August 23, 2016 1:33 pm

      Good idea. Of course there may be rejection. There is also a very big likelihood that the maintainer(s) of the repository are humans that make bad decisions or are terrible people. That said, I would still feel that I’ve done something useful with my time and learned something new. Dwelling on possible rejection doesn’t help anyone and we can only change the attitude by being fearless and also calling out bad behaviour in answering to pull requests.

      20
    • 3

      Open source projects have a responsibility to appreciate contributions, assume good will and create a level playing field (code of conduct).

      There are efforts to make this better for both sides:
      http://openopensource.org/
      http://contributor-covenant.org/
      http://spf13.com/post/how-to-be-a-good-open-source-community-member/
      http://www.hanselman.com/blog/BringKindnessBackToOpenSource.aspx

      I think both sides need education. I’m sure there are other articles that other people could contribute here.

      I’d like to see more articles on running opensource projects personally.

      2
    • 4

      I so much agree with you. I’d really like to be more active in the open source community as I wanted to be part of the people answering on StackOverflow… so I answered for the firs time to a question that was on my skill level… never again

      -3
  2. 5

    Aqueel Aboobacker

    August 23, 2016 2:12 pm

    Great article. I want to know whether making my personal project Open-Source and getting pull requests is easy as well. Thanks for sharing your experience.

    2
  3. 6

    Sebastian Andil

    August 23, 2016 2:21 pm

    Nice and encouraging article, but for me, those projects are so overwhelming, that it feels like I have to learn a whole new “world” of that project to at least get an idea how it all works together…

    3
    • 7

      Christian Heilmann

      August 23, 2016 4:21 pm

      Yes, it can be daunting at times. The upside is that you can learn a lot about good code architecture from well-written projects. And it is a good opportunity to demand some documentation if you’re really lost :)

      2
    • 8

      Yes. You need to get the idea that writing open-source code makes the world better. Then doing so will make your life better and it will be worth it.

      1

↑ Back to top