Cogito, Ergo Sumana

Categories: sumana | Work:Zulip

Zulip, the open source group chat software I work on as part of Changeset Consulting - zulip.org


: 2017 Sumana In Review: Four years ago, during my first batch at the Recurse Center, every day I'd write in a little notebook on the subway on my way home, jotting down a few bullet points about what I had learned that day. I found it helped in a variety of ways, and the keenest was that on bad days, reviewing my notes reminded me that I was in fact progressing and learning things.

On any given day in 2017 I often did not feel very happy with my progress and achievements and how I was using my time. I fell ill a lot and I was heartsick at the national political scene and current events. It is genuinely surprising to me to look back and take stock of how it all added up.

Adventures:

I went hiking in Staten Island and in the Hudson Valley. I got back on my bike and had some long rides, including on a canal towpath in New Jersey and over the Queensboro bridge. (And had my first accident -- a car in my neighborhood rear-ending me at a traffic light -- and thankfully escaped without damage or injury.) I learned how to bake bread. I got to meet Ellen Ullman OMG. And I tried to travel less than I had in previous years, but I still had some fine times in other places -- notably, I had a great time in Cleveland, I witnessed the total solar eclipse in Nashville, and I visited Charlotte, North Carolina (where, among other things, I visited the NASCAR Hall of Fame).

Community service:

I did some of the same kinds of volunteering and activism that I'd done in previous years. For instance, I continued to co-organize MergeSort, participated in a fundraising telethon for The Recompiler telethon, signal-boosted a friend's research project to get more participants, and helped revitalize a book review community focusing on writers of color. Also, I served again as the auctioneer for the James Tiptree, Jr. Literary Award fundraising auction at WisCon, which is a particularly fun form of community service. The Tiptree Award encourages the exploration & expansion of gender. I wrote this year about what an award does, and the reflections I've seen from winners of the Tiptree Awards and Fellowships tell me those honors are doing the job -- encouraging creators and fans to expand how we imagine gender. This year I also deepened my commitment to the Tiptree Award by accepting the organization's invitation to join the Tiptree Motherboard; I am pleased to have helped the award through a donation matching campaign.

But the big change in my community service this year was that I tried to prioritize in-person political work. I called, emailed, and wrote postcards to various government officials. I participated in my local Democratic Club, including going door-to-door petitioning to get my local city councilmember onto the ballot for reelection.

And I found that I could usefully bring my technologist perspective to bear on the city and state levels, especially regarding transparency in government software. I spoke to my local councilmember about my concern regarding public access defibrillator data (the topic that led me to file my first-ever Freedom of Information Law requests, for government health department records) and this inspired him to sponsor a bill on that topic. (Which is now filed as end-of-session partly because of the limbo in potentially getting PAD data from NYC's open data portal -- I need to send an email or two.) I was invited to speak to a joint committee of the New York State Assembly on the software side of our forensics labs, and got particularly interested in this aspect of due process in our criminal justice system, publicizing the issue in my MetaFilter posts "'maybe we should throw an exception here??'" and "California v. Johnson". I testified before the Committee on Technology of the New York City Council on amendments to our open data law (I didn't prep my public comment, so this text is reconstructed from memory; video), and then spoke before the same committee on an algorithmic accountability measure (and publicized the bill, especially keeping the Recurse Center community apprised as best I could). And I did research and outreach to help ensure that a state legislature hearing on protecting the integrity of our elections included a few researchers and activists it wouldn't have otherwise.

In 2018 I want to continue on this path. I think I'm, if not making a difference, making headway towards a future where I can make a difference.

Work:

This was by far Changeset Consulting's busiest year.

I had a mix of big projects and smaller engagements. First, some of the latter: I advised PokitDok on developer engagement, with help from Heidi Waterhouse. For Open Tech Strategies, I wrote an installation audit for StreetCRM. And, working with CourageIT, I came in as a part-time project manager on a government health IT open source project so the lead developer could focus more on architecture, code, and product management.

Some larger and longer projects:

Following a sprint with OpenNews in December 2016 to help write a guide to newsrooms who want to open source their code, I worked with Frances Hocutt to create a language-agnostic, general-purpose linter tool to accompany that guide. "The Open Project Linter is an automated checklist that new (or experienced but forgetful) open source maintainers can use to make sure that they're using good practices in their documentation, code, and project resources."

I spent much of the first half of 2017 contracting with Kandra Labs to grow the Zulip community, helping plan and run the PyCon sprint and co-staffing our PyCon and OSCON booths, running English tutoring sessions alongside Google Summer of Code application prep, and mentoring an Outreachy intern, along with the usual bug triage, documentation updates, and so on. We wrapped up my work as Zulip's now such a thriving community that my help isn't as needed!

From late 2016 into 2017, I've continued to improve infrastructure and documentation for a Provider Screening Module that US states will be able to use to administer Medicaid better (the project which spurred this post about learning to get around in Java).

And just in the last few months I started working on two exciting projects with organizations close to my heart. I'm thrilled to be improving HTTPS Everywhere's project workflow for developers & maintainers over the next few months, working with Kate Chapman via Cascadia Technical Mentorship (mailing list announcement). And, thanks to funding by Mozilla's open source grants program and via the Python Software Foundation, the Python Package Index -- basic Python community infrastructure -- is getting a long-awaited overhaul. I'm the lead project manager on that effort, and Laura Hampton is assisting me. (Python milestone: my first time commenting on a PEP!)

Along the way, I've gotten a little or a lot better at a lot of things: git, bash, LaTeX, Python (including packaging), Sphinx, Read the Docs, Pandoc, regular expressions, CSS, the Java ecosystem (especially Gradle, Javadocs, Drools), the Go ecosystem, Travis CI, GitHub Pages, Postgres, sed, npm Linux system administration accessibility standards, IRC bots, and invoicing.

Talks And Other Conferences:

This year, in retrospect, instead of doing technical talks and expository lectures of the type I'm already good at, I played with form.

At LibrePlanet 2017 I gave the closing keynote address, "Lessons, Myths, and Lenses: What I Wish I'd Known in 1998" (schedule, video, in-progress transcript). I tried something aleatoric and it worked pretty well.

At Penguicon 2017 I was one of several Guests of Honor, and spoke in several sessions including "Things I Wish I'd Known About Open Source in 1998" (which was different from the LibrePlanet version, as intended) and "What If Free and Open Source Software Were More Like Fandom?" (further links).

Then, at PyGotham, Jason Owen and I co-wrote and co-starred in a play about management and code review: "Code Review, Forwards and Back" (video on YouTube, video on PyVideo, commentary).

I also attended Maintainerati and led a session, attended !!Con, worked a booth for Zulip at OSCON, attended PyCon and helped run Zulip's sprint there, and co-sponsored a post-PyGotham dinner.

Other Interesting Things I Wrote:

I did not write this year for magazines; my writing went into this blog, MetaFilter, Dreamwidth, microblogging, and client projects, mostly. I also wrote an entry for a local business competition (I didn't make it very far but I'm glad I did it, especially the finance bits) and started two book proposals I would like to return to in 2018.

I've mentioned already some of the posts I'm happy about. Some others:

"On Noticing That Your Project Is Draining Your Soul" (every once in a while someone emails me and mentions that this has helped them, which means a lot)

"How to Teach & Include Volunteers who Write Poor Patches" (12 things you can do)

"Inclusive-Or: Hospitality in Bug Tracking", a response to Jillian C. York and Lindsey Kuper.

I turned part of "Some posts from the last year on inclusion" into "Distinguishing character assassination from accountability", a post about pile-on culture and callout culture where I pulled out quotes from 11 writers on how we take/charge each other with responsibility/power within communities.

I loved Jon Bois's 17776 and discussed it with other fans on MetaFilter, and then, to try to understand its amazingness better, wrote "Boisebration", collecting links to fiction and nonfiction by Bois about class, feminism, aging, sports, politics, wonder, education, & art (and 17776 precursors/callbacks).

I found out about Robert E. Kelly, like so many did, when his kids crashed his BBC interview, then collected some links in a MetaFilter post about his writing on Korea, US foreign policy, international relations, and academia.

I wrote up a bit about "1967's most annoying question for women in Catholic ministry" on MetaFilter to signal-boost another Recurser's cool project.

I enjoyed the learning and the plot twist in "The programmer experience: redundancy edition", in which I discovered a useful resource for Form 990 filings and learned to use the Arrow library for Python date-time manipulation. And was grateful to Pro Publica.

And I made a few jokes on social media I particularly liked:

yesterday, was trying to explain virtual environments/containers/VMs to a friend and said "they range from Inception-style fake computers to putting a blanket on the floor and pretending it's lava"

and

today a friend and I explained leftpad & Left Shark to someone and I began sketching out a hypothetical HuffPo piece connecting them
We habitually crowdsource infrastructure from, expect unsupportedly high levels of performance from unsuspecting participants -> popcorn.gif

Public notice I received:

I got some public attention in 2017 -- even beyond the Guest of Honor and keynote speaker honors and my amazing clients -- that I would like to list, as long as I'm taking an inventory of 2017.

I rode the first revenue ride of the new Q train extension in Manhattan and really loved the art at the new 72nd Street MTA stop. A journalist interviewed me about that on video and my experience got into the New York Times story about the opening.

Presenters at the code4lib conference said their project was specifically motivated by my code4lib 2014 keynote "User Experience is a Social Justice Issue" (written version, video). I was honored and humbled.

And -- this is out of place but I need to record it -- as someone who knew Aaron Swartz, I consented to be interviewed by artists working on a play about him, and so someone briefly portrayed me (as in, pretended to be me and repeated my words aloud) in that play, Building a Real Boy.

Finally, Hari Kondabolu looked at the English Wikipedia page about him, much of which I contributed, and was amazed at how thorough it was. So that was awesome and I was proud.

Habits:

I got on Mastodon as part of my effort to improve how I use social media. I started using a new task tracker. I got back on my bike, and got somewhat into a habit of using it for some exercise and intra-city travel. A new friend got me into taking more frequent photos and noticing the world I'm in. Two new friends caused me to look for more opportunities to see musicians I love perform live.

Watched/listened:

I consumed a fair bit of media this year; didn't get into new music but enjoyed music podcasts "I Only Listen To The Mountain Goats" and "Our Debut Album". I did some book and reading reviews and will catch up to other 2017 reading sometime vaguely soon.

Leonard's film roundups & TV spotlights are a good way to see or remember most of what I saw in the last few years. TV highlights for me for 2017 are The Good Place, Jane the Virgin, The Great British Baking Show (which led me to write a tiny Asimov fanfic), Steven Universe, and Better Call Saul; I also saw Comrade Detective and Yuri!!! On Ice. Films I'm really glad I saw: The Big Sick, Schindler's List, Get Out (I fanned in MetaFilter Fanfare), In Transit, A Man For All Seasons, Hidden Figures, and Lemonade -- and a rewatch of Antitrust.

Social:

I made a few new friends this year, most notably Jason Owen and Mike Pirnat. My friends Emily and Kris got married and I got to hold up part of the chuppah for them. I took care of some friends at hard times, like accompanying them to doctor's visits. I got to see some friends I rarely see, like Mel Chua and Zed Lopez and Zack Weinberg, and kept up some old friendships by phone. My marriage is better than ever.

This year I shall iterate forward, as we all do.

Filed under:


(1) : Inclusive-Or: Hospitality in Bug Tracking:

Lindsey Kuper asked:

I’m interested in hearing about [open source software] projects that have successfully adopted an "only insiders use the issue tracker" approach. For instance, a project might have a mailing list where users discuss bugs in an unstructured way, and project insiders distill those discussions into bug reports to be entered into the issue tracker. Where does this approach succeed, and where does it fail? How can projects that operate this way effectively communicate their expectations to non-insider users, especially those users who might be more accustomed to using issue trackers directly?
More recently, Jillian C. York wrote:

...sick of "just file a bug with us through github!" You realize that's offputting to your average users, right?

If you want actual, average users to submit bugs, you know what you have to do: You have to use email. Sorry, but it's true.

Oh, and that goes especially for high-risk users. Give them easy ways to talk to you. You know who you are, devs.

Both Kuper and York get at: How do we open source maintainers get the bug reports we need, in a way that works for us and for our users?

My short answer is that open source projects should have centralized bug trackers that are as easy as possible to work in as an expert user, and that they should find automated ways to accept bug reports from less structured and less expert sources. I'll discuss some examples and then some general principles.

Dreamwidth logo Dreamwidth: Dreamwidth takes support questions via a customer support interface. The volunteers and paid staff answering those questions sometimes find that a support request reveals a bug, and then file it in GitHub on the customer's behalf, then tell her when it's fixed. (Each support request has a private section that only Support can see, which makes it easier to track the connection between Support requests and GitHub issues, and Support regulars tend to have enough ambient awareness of both Support and GitHub traffic to speak up when relevant issues crop up or get closed.) Dreamwidth users and developers who are comfortable using the GitHub issue tracker are welcomed if they want to file bugs there directly instead.

Dreamwidth also has a non-GitHub interface for feature suggestions: the suggestions form is the preferred interface for people to suggest new features for Dreamwidth. Users post their suggestions into a queue and a maintainer chooses whether to turn that suggestion into a post for open discussion in the dw-suggestions community, or whether to bounce it straight into GitHub (e.g., for an uncontroversial request to whitelist a new site for media embedding or add a new site for easy cross-site user linking, or at the maintainer's prerogative). Once a maintainer has turned a suggestion into a post, other users use an interface familiar to them (Dreamwidth itself) to discuss whether they want the feature. Then, if they and the maintainer come to consensus and approve it, the maintainer adds a ticket for it to GitHub. That moderation step has been a bottleneck in the past, and the process of moving a suggestion into GitHub also hasn't yet been automated.

Since discussion about site changes needs to include users who aren't developers, Dreamwidth maintainers prefer that people use the suggestions form; experienced developers sometimes start conversations in GitHub, but the norm (at least the official norm) is to use dw-suggestions; I think the occasional GitHub comment suffices for redirecting these discussions.

Zulip logo Zulip: We use GitHub issues. The Zulip installations hosted by Kandra Labs (the for-profit company that stewards the open source project) also have a "Send feedback" button in one of the upper corners of the Zulip web user interface. Clicking this opens a private message conversation with feedback-at-zulip.com, which users used more heavily when the product was younger. (We also used to have a nice setup where we could actually send you replies in-Zulip, and may bring that back in the future.)

I often see Tim Abbott and other maintainers noticing problems that new users/customers are having and, while helping them (via the zulip-devel mailing list, via the Zuliping-about-Zulip chat at chat.zulip.org, or in person), opening GitHub issues about the issue, as the next step towards a long-term fix. But -- as with the Dreamwidth example -- it is also fine for people who are used to filing bug reports or feature requests directly to go ahead and file them in GitHub. And if Tim et alia know that the person they're helping has that skill and probably has the time to write up a quick issue, then the maintainers will likely say, "hey would you mind filing that in GitHub?"

We sometimes hold live office hours at chat.zulip.org. At yesterday's office hour, Tim set up a discussion topic named "warts" and said,

I think another good topic is to just have folks list the things that feel like they're some of our uglier/messier parts of the UI that should be getting attention. We can use this topic to collect them :).

Several people spoke up about little irritations, and we ended up filing and fixing multiple issues. One of Zulip's lead developers, Steve Howell, reflected: "As many bug reports as we get normally, asking for 'warts' seems to empower customers to report stuff that might not be considered bugs, or just empower them to speak up more." I'd also point out that some people feel more comfortable responding to an invitation in a synchronous conversation than initiating an asynchronous one -- plus, there's the power of personal invitation to consider.

As user uptake goes up, I hope we'll also have more of a presence on Twitter, IRC, and Stack Overflow in order to engage people who are asking questions there and help them there, and get proto-bug reports from those platforms to transform into GitHub issues. We already use our Twitter integration to help -- if someone mentions Zulip in a public Tweet, a bot tells us about it in our developers' livechat, so we can log into our Twitter account and reply to them.

MediaWiki logo 1MediaWiki and Wikimedia: Wikipedia editors and other contributors have a lot of places they communicate about the sites themselves, such as the technical-issues subforum of English Wikipedia's "Village Pump", and similar community-conversation pages within other Wikipedias, Wikivoyages, etc. Under my leadership, the team within Wikimedia Foundation's engineering department that liaised with the larger Wikimedia community grew more systematic about working with those Wikimedia spaces where users were saying things that were proto-bug reports. We got more systematic about listening for those complaints, filing them as bugs in the public bug tracker, and keeping in touch with those reporters as bugs progressed -- and building a kind of ambassador community to further that kind of information dissemination. (I don't know how well that worked out; I think we built a better social infrastructure for people who were already doing that kind of volunteer work ad hoc, but I don't know whether we succeeded in recruiting more people to do it, and I haven't kept a close eye on how that's gone in the years since I left.)

We also worked to make it easy for people to report bugs into the main bug tracker. The Bugzilla installation we had for most of the time that I was at Wikimedia had two bug reporting forms: a "simple" submission form that we pointed most people to, with far fewer fields, and an "advanced" form that Wikimedia-experienced developers used. They've moved to Phabricator now, and I don't know whether they've replicated that kind of two-lane approach.

A closed-source example: FogBugz. When I was at Fog Creek Software doing sales and customer support, we used FogBugz as our internal bug tracker (to manage TODOs for our products,* and as our customer relationship manager). Emails into the relevant email addresses landed in FogBugz, so it was easy for me to reply directly to help requests that I could fix myself, and easy for me to note "this customer support request demonstrates a bug we need to fix" and turn it into a bug report, or open a related issue for that bug report. If I recall correctly, I could even set the visibility of the issue so the customer could see it and its progress (unusual, since almost all our issue-tracking was private and visible only within the company).

Debian logo An interface example: Debian. Debian lets you report bugs via email and via the command-line reportbug program. As the "how to use BTS" guide says,

some spam messages managed to send mails to -done addresses. Those are usually easily caught, and given that everything can get reverted easily it's not that troublesome. The package maintainers usually notice those and react to them, as do the BTS admins regularly.

The BTS admins also have the possibility to block some senders from working on the bug tracking system in case they deliberately do malicious things.

But being open and inviting everyone to work on bugs totally outweighs the troubles that sometimes pop up because of misuse of the control bot.

And that leads us to:

General guidelines: Dreamwidth, Zulip, MediaWiki, and Debian don't discourage people from filing bug reports in the official central bug tracker. Even someone quite new to a particular codebase/project can file a very helpful and clear bug report, after all, as long as they know the general skill of filing a good bug report. Rather, I think the philosophy is what you might find in hospitable activism in general: meet people where they are, and provide a means for them to conveniently start the conversation in a time, place, and manner that's more comfortable for them. For a lot of people, that means email, or the product itself.

Failure modes can include:

Whether or not you choose to increase the number of interfaces you enable for bug reporting, it's worth improving the user experience for people reporting bugs into your main bug tracker. Tedious, lots-of-fields issue tracker templates and UIs decrease throughput, even for skilled bug reporters who simply aren't used to the particular codebase/project they're currently trying to file an issue about. So we should make that easier. You can provide an easy web form, as Wikimedia did via the simplified Bugzilla form, or an email or in-application route, as Debian does.

And FLOSS projects oughta do what the Accumulo folks did for Kuper, too, saying, "I can file that bug for you." We can be inclusive-or rather than exclusive-or about it, you know? That's how I figure it.


* Those products were CityDesk, Copilot, and FogBugz -- this was before Kiln, Stack Overflow, Trello, and Glitch.

Thanks to Lindsey Kuper and Jillian C. York for sparking this post, and thanks to azurelunatic for making sure I got Dreamwidth details right.

Filed under:


(1) : How to Teach And Include Volunteers who Write Poor Patches: You help run an open source software community, and you've successfully signalled that you're open to new contributors, including people who aren't professional software engineers. And you've already got an easy developer setup process and great test coverage so it's easy for new people to get up and running fast. Great!

Some of the volunteers who join you are less-skilled programmers, and they're submitting pull requests/patches that need a lot of review and reworking before you can merge them.

How do you improve these volunteers' work, help them do productive things for the project, and encourage and include them?

My suggestions for you fall into three categories: helping them improve their code, dealing with the poor-quality pull requests themselves, and redirecting their energies to improve the project in other ways.

Teaching them to improve their code

Dealing with poor patches themselves

Using their knowledge and curiosity to improve the project in other ways

This list is absolutely not the be-all and end-all for this topic; I'd like to know what approaches others use.


Thanks to Noah Swartz for starting a conversation at Maintainerati that spurred me to write this post.

Filed under:


(1) : Rough Notes for New FLOSS Contributors On The Scientific Method and Usable History: Some thrown-together thoughts towards a more comprehensive writeup. It's advice on about how to get along better as a new open source participant, based on the fundamental wisdom that you weren't the first person here and you won't be the last.

We aren't just making code. We are working in a shared workplace, even if it's an online place rather than a physical office or laboratory, making stuff together. The work includes not just writing functions and classes, but experiments and planning and coming up with "we ought to do this" ideas. And we try to make it so that anyone coming into our shared workplace -- or anyone who's working on a different part of the project than they're already used to -- can take a look at what we've already said and done, and reuse the work that's been done already.

We aren't just making code. We're making history. And we're making a usable history, one that you can use, and one that the contributor next year can use.

So if you're contributing now, you have to learn to learn from history. We put a certain kind of work in our code repositories, both code and notes about the code. git grep idea searches a code repository's code and comments for the word "idea", git log --grep="idea" searches the commit history for times we've used the word "idea" in a commit message, and git blame codefile.py shows you who last changed every line of that codefile, and when. And we put a certain kind of work into our conversations, in our mailing lists and our bug/issue trackers. We say "I tried this and it didn't work" or "here's how someone else should implement this" or "I am currently working on this". You will, with practice, get better at finding and looking at these clues, at finding the bits of code and conversation that are relevant to your question.

And you have to learn to contribute to history. This is why we want you to ask your questions in public -- so that when we answer them, someone today or next week or next year can also learn from the answer. This is why we want you to write emails to our mailing lists where you explain what you're doing. This is why we ask you to use proper English when you write code comments, and why we have rules for the formatting and phrasing of commit messages, so it's easier for someone in the future to grep and skim and understand. This is why a good question or a good answer has enough context that other people, a year from now, can see whether it's relevant to them.

Relatedly: the scientific method is for teaching as well as for troubleshooting. I compared an open source project to a lab before. In the code work we do, we often use the scientific method. In order for someone else to help you, they have to create, test, and prove or disprove theories -- about what you already know, about what your code is doing, about the configuration on your computer. And when you see me asking a million questions, asking you to try something out, asking what you have already tried, and so on, that's what I'm doing. I'm generally using the scientific method. I'm coming up with a question and a hypothesis and I'm testing it, or asking you to test it, so we can look at that data together and draw conclusions and use them to find new interesting questions to pursue.

Example:

So I'll ask a question to try and prove or disprove my hypothesis. And if you never reply to my question, or you say "oh I fixed it" but don't say how, or if you say "no that's not the problem" but you don't share the evidence that led you to that conclusion, it's harder for me to help you. And similarly, if I'm trying to figure out what you already know so that I can help you solve a problem, I'm going to ask a lot of diagnostic questions about whether you know how to do this or that. And it's ok not to know things! I want to teach you. And then you'll teach someone else.

In our coding work, it's a shared responsibility to generate hypotheses and to investigate them, to put them to the test, and to share data publicly to help others with their investigations. And it's more fruitful to pursue hypotheses, to ask "I tried ___ and it's not working; could the reason be this?", than it is to merely ask "what's going on?" and push the responsibility of hypothesizing and investigation onto others.

This is a part of balancing self-sufficiency and interdependence. You must try, and then you must ask. Use the scientific method and come up with some hypotheses, then ask for help -- and ask for help in a way that helps contribute to our shared history, and is more likely to help ensure a return-on-investment for other people's time.

So it's likely to go like this:

  1. you try to solve your problem until you get stuck, including looking through our code and our documentation, then start formulating your request for help
  2. you ask your question
  3. someone directs you to a document
  4. you go read that document, and try to use it to answer your question
  5. you find you are confused about a new thing
  6. you ask another question
  7. now that you have demonstrated that you have the ability to read, think, and learn new things, someone has a longer talk with you to answer your new specific question
  8. you and the other person collaborate to improve the document that you read in step 4 :-)

This helps us make a balance between person-to-person discussion and documentation that everyone can read, so we save time answering common questions but also get everyone the personal help they need. This will help you understand the rhythm of help we provide in livechat -- including why we prefer to give you help in public mailing lists and channels, instead of in one-on-one private messages or email. We prefer to hear from you and respond to you in public places so more people have a chance to answer the question, and to see and benefit from the answer.

We want you to learn and grow. And your success is going to include a day when you see how we should be doing things better, not just with a new feature or a bugfix in the code, but in our processes, in how we're organizing and running the lab. I also deeply want for you to take the lessons you learn -- about how a group can organize itself to empower everyone, about seeing and hacking systems, about what scaffolding makes people more capable -- to the rest of your life, so you can be freer, stronger, a better leader, a disruptive influence in the oppressive and needless hierarchies you encounter. That's success too. You are part of our history and we are part of yours, even if you part ways with us, even if the project goes defunct.

This is where I should say something about not just making a diff but a difference, or something about the changelog of your life, but I am already super late to go on my morning jog and this was meant to be a quick-and-rough braindump anyway...

Filed under:


: Zulip & Good Code Review: As Changeset Consulting I've recently done some tech writing work for the Zulip open source project (check out my pull requests for the nitty-gritty). And I've gotten to work with Tim Abbott, Zulip's maintainer, including taking his feedback and course-correction. Often, in the software industry, we pretend or assume a dichotomy between brutal clarity and kind vagueness, especially when it comes to criticizing other people's work. Getting to work with Tim has been a welcome and consistent reminder that you can be straightforward and respectful when you need to give negative feedback.

Here's an example: Tim reviewing a pull request. Check out how he starts by saying it looks good, and then offers suggestions on how to break the patch into logical commits -- and how he makes sure to explain why we want to do that (including a link to a document that explains the reasoning and customs in more detail). Tim also tells the code author that it's fine to deviate from his specific suggestions, but gives him some guardrails. Since rebasing can be tricky for people who haven't done it much, he even suggests some git commands and tools that'll make things easier, and offers to clarify if needed. And Tim wraps it up with a thank-you and a quick explanation about why he's being so rigorous in reviewing this particular patch (security considerations).

It's thoughtful, kind, clear, and collaborative. It's the seventh comment Tim's offered on this pull request, as the author's iteratively improved it, and it shows no hint of impatience. Good stuff.

If this has piqued your interest in Zulip, you might also like the roadmap and README. Also, Zulip's holding a sprint at PyCon US, June 2-5, in Portland, Oregon.

Filed under:



[Main]

You can hire me through Changeset Consulting.

Creative Commons License
This work by Sumana Harihareswara is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
Permissions beyond the scope of this license may be available by emailing the author at sh@changeset.nyc.