Week 23 at an Unbootcamp

Best practices

As I noted last weekLearners Guild in Oakland works to instill in its Learners a variety of virtues, not just the ability to write code that computes correctly. The best practices include:

  • Stylistically consistent code (with respect to indentation, punctuation, capitalization, etc.)
  • Well-modularized code (each piece doing one thing)
  • Self-explanatory names of variables
  • Test-driven development (writing thorough tests before coding)
  • Parsimony (putting any code that is used multiple times into a named function rather than repeating the code)
  • Kind, helpful, and respectful conduct toward teammates

An important practice that supports the first of these is linting. You might think of this as an automatic process that reads all of your code and screams at you if you have failed to comply with the counterpart of the Chicago Manual of Style or the Blue Book. At Learners Guild, the linter most commonly recommended is named ESLint. Unlike some linters, it has only one opinion: You should be consistent. It doesn’t care which rules you obey, as long as you obey them all the time. You decide to turn rules on and off, and, if you turn them on, you can make them either fail your code or merely warn you. In this respect, linting with ESLint is distinct from using published style manuals, since manuals usually tell you which rules to obey. ESLint is basically a write-your-own-style-manual tool, which then enforces your rules for you.

Reaching out

During my just-ended week 23 at the Guild, my relationship with ESLint changed. Here’s the story.

I’m in phase 4, where Learners have stopped doing exercises and are actually helping build, improve, and repair real open-source software. I began, like everybody in phase-4, doing this with the software that manages the Guild’s own curriculum and monitors the Learners’ progress through it. I added missing functionality and repaired bugs that I found.

By mid-week I had reached a reasonable turning point. I had submitted 80 different changes to the Guild’s software and was waiting for them to be approved and incorporated into the running code (or criticized for flaws requiring correction). However, phase 4 was suffering from a temporary shortage of leadership, causing the work done by the Learners to pile up and leaving some of us without obvious ways to make more contributions.

This personnel imbalance was one manifestation of the flux that the Guild is now in, as it takes stock and embarks on an effort at cooperative (i.e. Learner–staff) redesign of the Guild itself. In response, some Learner time is being spent making proposals for Guild reorganization. Other than that, Learners are exercising plenty of de facto discretion in deciding how to progress as members of this learning community. Several Learners are busy learning (and teaching each other) technologies and frameworks that have not (yet) made it into the curriculum, such as blockchain development. I decided this week to shift my contributions from the Guild’s software to external open-source projects—something that is in the phase-4 description but was not currently being practiced.

Having made this decision in principle, I proceeded to survey the thousands of open-source projects that can use contributions from JavaScript developers. After a couple of days of research, I narrowed my list of candidates to 6 projects: Etherpad Lite, pdf.js, Sandstorm, Sequelize, Material Components for the Web, and ESLint. I ultimately chose ESLint. Thus, I decided to stop being merely a user of ESLint, and start also being one of its producers. (“Making my own dog food”.)

When you decide to contribute to such a project, you first follow the instructions for contributors. They tell you how to install a copy of the software on your own computer. That’s where you’ll do all your coding and testing, before you are ready to submit proposed changes.

I followed the instructions and got to the point of running the existing tests, to ensure that the software on my machine would behave as expected. I entered the command, npm test. About 2 minutes later, I got the results: 17,644 tests passing, 1 test failing.

I couldn’t start working on the code until the count of failing tests became 0. A single failing test is unacceptable. But hey, what an opportunity! Maybe I could figure out what went wrong with that test, and, if it was a problem with the test, I could correct it, thereby making my first contribution to ESLint. That is exactly what I did. The culprit was, indeed, a flaw in the test. The test made an assumption that I wouldn’t have a certain file in a certain directory—but I did. So I proposed a sequence of changes to deal with this problem, starting with instructions and warnings to contributors and more accurate error messages, and ending with a revised test that would not fail under the same condition.

When I began submitting proposals to change the documentation and code, project personnel began responding within 15 minutes. Proposals that were ready for adoption were merged into the running code within hours, or by the next day. Proposals needing revision elicited clearly explained change requests. And accepted contributions got expressions of gratitude.

What ESLint has, and Learners Guild (like the vast majority of open-source projects) is only beginning to approach, is a rock-solid system for managing volunteer labor. The instructions are exhaustive. The battery of tests is enormous. The response time to contributions is lightning-fast. And the decision makers are courteous, clear, competent, and thankful. A corollary benefit is personal validation: If you get contributions accepted and incorporated into ESLint, then you know (and any JavaScript developer knows) that you must be doing something right.

We Learners are now being asked to tell the Guild how to make itself better. One piece of advice I’m giving is: Make contributing to external projects a fundamental element of the curriculum, and help us learn to do it well.

 

Leave a Reply