Back to the schedule
Previous: CLEDE: the Common Lisp Emacs Development Environment
Next: How to build an Emacs

How to help Emacs maintainers?

Bastien Guerry

Q&A: live
Duration: 10:07

If you have questions and the speaker has not indicated public contact information on this page, please feel free to e-mail us at emacsconf-submit@gnu.org and we'll forward your question to the speaker.

Talk

00:00 Introduction
00:47 What is a free software maintainer?
02:19 What do I do as the Org maintainer?
03:24 Do you see a pattern here?
04:18 What a free software maintainer is or should be
05:03 Summary
05:26 ACDC: Asynchronous Collective Distributed Care
06:28 How can you help Emacs maintainers?
06:37 Become a maintainer for your own project, however small
06:56 Volunteer as a contributor steward for another project
07:10 Learn how to teach
07:25 Test and enhance the project's contribution process
07:35 Take care of the project's calls for help
07:52 Encourage users from outside the project to contribute to the core forum
08:08 Let the core forum know about what happens in this outside world
08:16 Propose your help for non-code tasks
08:26 If you expect someone else to fix your bug, try fixing someone else's bug first
08:42 Don't expect the maintainer to be a hotline
08:49 Complete this list
08:57 Yes, this is hard
09:35 Thanks

Q&A

00:00 Thanks
04:30 How did you come up with this knowledge? By doing or by experience or by reading books? Which?
06:10 How did you come to start using Org?
08:39 You have recently overseen a major transition for org mode maintenance. What would you advise for other teams that are preparing for transitions so that processes can be maintained with minimal disruption? How do we take processes that were originally maintained by a single person to one maintained by multiple people?
10:55 Which place is the right place to request a dark mode in Org Mode website?
11:27 More thanks
15:09 Does this mean that you do not need to be technical to become a maintainer?
17:24 What does the day of the Org Mode maintainer look like? Lots of hours of work every day?
21:11 Do you think having centralized roles for people to carry out certain tasks such as documentation across multiple areas would be a constructive approach to inviting new maintainers (in contrast to "every person take an issue of their own choosing", which leaves parts of maintenance and documentation neglected)?
24:21 I think Org has and may potentially greatly influence Emacs development. If you would tend to agree, do you have places where you feel Emacs need to "pull back" harder, to influence Org? Key areas where Org is clearly "leading the way"?
27:52 Could you expand a little on what's happening on contrib?
35:32 Orgdown
54:54 What about backlinks?

Description

https://bzg.fr/en/how-to-help-gnu-emacs-maintainers/

After 11 years of helping as the Org maintainer, I would like to share a few lessons learned. My goal is help everyone take care of Emacs maintainance by taking care of Emacs maintainers.

Discussion

Pad:

• [00:04:30.840] Q1: How did you come up with this knowledge? By doing or by experience or by reading books (which?)?
  • A: All 3 of them.
  • He was reading the book: Fred turner : counter culture to cyberculture
    • The other one he mentioned appears to be Eghbal, Nadia [Stripe Press] (2020) Working in public: the making and maintenance of open source software
• [00:06:10.000] Q2: (Maybe answer this last, if time permits) How did you come to start using Org?
  • A: Bastien started with his own library BHL and was introduced/invited to contribute to Org by Carsten.
• [00:08:39.720] Q3: You have recently overseen a major transition for org mode maintenance, what would you advise for other teams that are preparing for transitions so that processes can be maintained with minimal disruption? How do we take processes that were originally maintained by a single person to one maintained by multiple people?
  • A: (Probably answered by voice.)
• [00:35:32.840] Q4: What do you think about the latest Orgdown thing? (Yes, it's me, Karl )
  • A: (Probably answered by voice.)
• Q5: Could you settle this "Org" vs "Org-mode" vs "orgmode" vs ... once and for all (i.e. which one, capitalized how, and where)?
  • A: (Probably answered by voice.)
• [00:15:09.880] Q6: Does this mean that you do not need to be technical to be(come) a maintainer? Would that really work?
  • A: The co-maintainer could be a person with less technical background.
• [00:17:24.520] Q7: If time — what does the day of the orgmode maintainer look like? Lots of hours of work every day? Spread out?
  • A: Not always. Last two months "MIA." Bastien wants to step down as maintainer but wants to prepare project/community for the next maintainer. "When I was working hard on this it was something like two hours a day. But usually it would be 2-4 hours per week." Most of time spent on mailing list (Bastien notes that he likes mailing list isn't split between users/developers).
• [00:10:55.200] Q8: Thanks for the hard work. Which place is the right place to request a dark mode for orgmode.org website ?
  • A: write an email to the Org-mode team. This seems to be a reasonable request.
• [00:21:11.800] Q9: Do you think having centralized roles for people to carry out certain tasks such as documentation across multiple areas would be a constructive approach to inviting new maintainers (in contrast to "every person take an issue of their own choosing", which leaves parts of maintenance and documentation neglected)? From personal experience, sometimes it can be easier for those to be told "hey, we need this area maintanined, or a focus on contribution to this particular area". If we take a page from Catalonian Spain of the early 1900's, even the most decentralized organizations have to dedicate certain persons to specific tasks. Sorry for the long winded question.
  • A: (Probably answered by voice.)
• [00:24:21.440] "Q10: incluence org? Key areas where org is clearly "leading the way"?
  • A: "Org is to Emacs was Emacs is to computer systems"
• [00:27:52.320] Q11: Could you expound a little on what's happening with contrib ... I'm a little confused. Mechanics/technical.
  • (Karl: Do you mean technically "how to migrate" or the background why this happened? I personally did the conversion this week. I got the separate repository (or package) and had to do more local "use-packages" (the way of loading elisp files in my setup) and that's it. The hard thing was to find out which error refers to which org file to load separately.) Thanks. Seems like time for bankrupcy again :-/.
  • A: contrib = stuff that didn't go to Emacs (copyright assignment not necessary). This was not a clean solution because it was mixed with copyright-transferred files in the same repository. New contrib goes now to "non-GNU" which is a clear separation according to copyright assignments. The way to install Org is via Org MELPA and contrib for Non-GNU MELPA. YES. THANKS.
• Q12: (Maybe not a question, just an observation) I like the analogy to gardening. FOSS projects seem much like community gardens. Also, shepherding seems like an apt analogy; I could imagine files having "shepherds"
  • A: (Probably answered by voice.)
• [] Q13: Has splitting contrib actually reduced maintenance load? Is it too soon to tell? (I have found that splitting repos ultimately increases maintenance overhead due to multiplying release overhead etc.)
  • A: It is clearly easier now and less confusing for contributors. org-contrib is soon to die: packages will be moved to their own packages since contrib was founded when there was no packaging around.
• Q14: So was BHL the basis for org-export?
  • A: https://bzg.fr/en/theorgfather/

BBB:

• agreed, I appreciate that the list isn't split.
  • vastly simplifies workflows.
• (Missing context) Wouldn't they be missing the key part, Emacs?
  • Questioner: (ah, i understood forking for a different toolset, vs markdown-based org-mode on Emacs, apologies)
  • Bastien Guerry: https://list.orgmode.org/87y2jvkeql.fsf@gnu.org/
• devil's advocate to Karl's point now though: is that from habit?
• link syntax in markdown is impossible to remember for simplifying e.g. keyword syntax can be made regular. consistency across levels is extremely hard due to interactions between features, in part because you only encounter those much later in implementation. another part of the issue is that Org has more features than pandoc markdown so it is sometimes unrepresentable.
• interestingly Timothy has solved most of the markdown &> org
  • plain orgmode is easy to visualize. with markdown you need to export this if you have many md lines. org tables is a clear example of the visualization
• I think the argument of the best syntax is a hard battle to fight, but where the bar is clear is the software (org-mode) and what it can do with it, as of today.
• [00:54:54.080] FYI org-sidebar provides a backlinks tool
• Backlinks! Yes!
• Backlinks for me: https://karl-voit.at/2020/07/22/org-super-links/
• was going to say : many of the org-roam features should make their way into core org-mode eventually
• how to manage and cache other types of data that are similar to backlinks
• something like org-id caching, you mean?
• alphapapa: not quite, more things that we don't want to put in the org file directly; e.g. babel caches for huge pieces of data
• id caching for performance would be great, some of the vizualisation things are very interesting too
  • it is a hard problem

BBB feedback:

• Thank you for taking the time to share your accumulated wisdom with us, Bastien
• merci Bastien!

IRC:

• I love it when people just kick it old school and write things out.
• the spiderman syndrome is evil. it causes imposter syndrome that god knows how many contributors it has cost us
• excellent analysis on bdfl/spidysyndrome, you can see it play out in other communities as well
• Very interesting, I suppose I get an idea that maintainers are put on a pedestal, and you see a lot of the good, and bad from both sides of the spectrum. It can be thankless, but also incredibly rewarding. It's easy to miss the forest for the trees, and keep in mind that most every piece of FLOSS software is a very decentralized and maintanance heavy vs. centralized and focused on LOC.
• i don't get the project vs product
  • project is the process of creating the product (usually)
  • because "project" has been redefined over time to mean the product (such as the codebase), together with the project as in the endeavor to create/develop it
  • Project is a greater scope than product, in my view. A project is not only the code, but the relationships with others who interact with it. The product can be the same, but doesn't usually include the support aspect since it's "free".
• FLOSS software is a fascinating psychological study on that ACDC concept.
• i feel that this doesnt apply only to maintainers. So many managers should listen to it too
• It is really good advice to keep in mind as a manager
• GUIX has a really great community, and has folk like 'jgart' mainly, that has package maintaince workshops where they invite newbies and experienced users alike to contribute packages to GUIX.
• one of the things that hasn't been brought up yet is maintainer territoriality, I know for many of my projects I can be quite territorial, sometimes unintentionally
• That kind of contribution is invaluable for being an inviting environment for congtributing to a project.
• I think even if the maintainer doesn't intend this potential contributors can perceive it
• Awesome talk! Not just in the context of Org-mode!
• The hand written slides are so engaging!

Transcript

[00:00:00.799] Hello, I'm Bastien Guerry, and I'm very happy to be here. I've been the Org-mode maintainer for the last 10 years, and I would like to ask the question how to help GNU Emacs maintainers in general. By GNU Emacs, I mean the whole GNU Emacs ecosystem, including packages, not just the core GNU Emacs that we all love. After a decade of dealing with the Org community, my view of what a maintainer is changed. I'd like to share some ideas with you as I think they could be useful to help Emacs maintainers in general. And hopefully, these ideas also apply to other free software projects, at least those where contributors are all volunteers.

[00:00:47.568] First of all, what is a free software maintainer?
- Obviously this is some rich dude with a lot of free time
- Acting both as a supersmart hacker and a super-patient community manager
- Someone who acts as the central hotline for users and contributors
- Who knows how to write many emails, probably at the same time
- Who does not hesitate to publicly scold annoying users
- and someone narcissistic enough to seek credits for community efforts
- But really looking for a job in some big IT company
Right? Well... no. That was a joke. But maybe you did smile and that's probably because there is some truth to it. Why? Because our culture encourages free software users and casual contributors to think about maintainers this way. Don't we continue to use the expression “Benevolent Dictator For Life”? This is what I'd call the “Spiderman syndrome”: maintenance is perceived in terms of great power and great responsibility. But I believe our culture of superheroes is not helpful here: it does not reflect the truth, it does not set the right expectations, and it prevents contributors to properly understand how to help maintainers.

[00:02:19.601] So let's start again. And instead of asking what a maintainer is, let me take the list of what I do as the Org maintainer. Here is my TODO-list:
- First of all, I take care of the orgmode.org website.
- I also take care of the org-contrib NonGNU ELPA package.
- I do gardening on the community-driven documentation, Worg.
- I do add contributors to Worg.
- I read emails on emacs-orgmode@, emacs-devel@ and bug-gnu-emacs@.
- I contribute to email moderation of the emacs-orgmode@ list with a bunch of other contributors.
- I reply to private emails asking me for help about org-mode.
- I coordinate with GNU Emacs maintainers and thanks to them for Emacs/Org integration.
- I contribute with public emails on the Org mailing list.
- I release new versions of Org-mode.
- and sometimes, sometimes, I contribute with code.

[00:03:24.601] Do you see a pattern here? Yes. I bet the last three tasks is what most people have in mind when they think of a maintainer: it's all about hacking and being an efficient hotline. But in fact, these tasks are only a superficial part of what I do as a maintainer. Some would consider that these core tasks are the interesting ones, while the others are the boring ones. I don't see it that way: some tasks are about the product, others are about the project. Without a good product, there is little chance you will have a good project, but maintaining a project requires thinking in terms of infrastructure, not in terms of bugs, thinking in terms of resources that enable both users and contributors, not in terms of commits.

[00:04:18.401] So let me try to define again what a free software maintainer is or should be. A free software maintainer is someone who cares about enabling users and contributors so that they collectively take care of the project. See another pattern here? Yeah, that's all about the project, versus the product. It's about taking care of it, versus being a direct hotline for users, so, it's caring about the project infrastructure and about empowering users with tools and incentives so that they care too. How can you help such a maintainer? By focusing on the project and becoming an enabler yourself.

[00:05:03.901] So, let's pause and summarize: our culture wants heroes and this leads us to expect maintainers to be superhackers and superactive hotlines. This is the HOT mindset of maintenance, where the maintainers are Headmasters Of Tweaks and soon becomes the Headmaster Of Troubles.

[00:05:26.901] To resist this HOT mindset, I suggest to redefine maintenance as ACDC: “Asynchronous Collective Distributed Care”:

[00:05:36.534] “Asynchronous” because time management is a private matter and we are all volunteers.

[00:05:41.968] “Collective” because, well, no man is an island.

[00:05:45.634] “Distributed”: because the more power to the “edges”, the more resilient the system and the project is.

[00:05:53.534] “Care” because this is all about care: with each other as users or as contributors, with the project's infrastructure (servers, websites, bug trackers, etc.) and care about having a useful product.

[00:06:08.701] So, “enabling” users and contributors means encouraging them to take ownership, which is more than just delegating tasks. Let your users and contributors know that they need to tap into the collective attention pool with care: the more autonomous they are, the better.

[00:06:28.801] So, with this ACDC definition in mind, how can you help Emacs maintainers?

[00:06:37.534] First of all, by becoming a maintainer for your own project, however small. Think in terms of project vs. product. Empower users and contributors. This will help you understand how to help other maintainers. “More power to the edges!”

[00:06:56.501] Volunteer as a contributor steward for another project: you don't need to be a supersmart hacker to help others to contribute. For Org-mode, we are lucky to have two great contributor stewards.

[00:07:10.901] Learn how to teach, because pedagogical skills are invaluable. Taking the time to explain how to write a bug report or a patch is invaluable and this is a core part of the Org culture.

[00:07:25.401] Test and enhance the project's contribution process. For Org-mode, you would read and suggest contributions to the org-contribute pages on Worg.

[00:07:35.634] Take care of the project's calls for help. For Org-mode, this would be this list that we have on updates.orgmode.org For Emacs, this would be etc/TODO file. If the calls for help are not explicit enough, try to contribute some.

[00:07:52.834] Encourage users from outside the project to contribute to the core forum. For Org-mode, there are many hacks and fixes being shared on Reddit and Stack Overflow, and that's fine, but we we should not wait for months before having this shared on the list.

[00:08:08.801] Let the core forum know about what happens in this outside world by sharing important information yourself.

[00:08:16.601] Propose your help for non-code tasks: maintain a website, enhance the community-driven documentation, help with bug triage, etc.

[00:08:26.101] If you expect someone else to fix your bug, try fixing someone else's bug first, and too: that's how you'll learn Emacs Lisp and that's how you'll concretely train your empathy, your sense of taking care. That is so critical.

[00:08:42.068] Don't expect the maintainer to be a hotline, especially a private one. Address yourself to the community.

[00:08:49.234] And last but not least, complete this list. I'm trying to open a conversation here, so don't be shy.

[00:08:57.168] That's it. Uhm, is it hard? Yes, this is hard, and that's because helping maintainers by becoming such a enabler in this ACDC mindset is not immediately rewarding, whereas fixing a bug clearly, clearly is. But if you start thinking of the project as something that enables you to do amazing things, and I believe Org is this kind of project, and if you start thinking of the maintenance as something that enables more contributions, you will see how important and rewarding it is to become such an enabler.

[00:09:35.668] So, definitely grateful to all the enablers that we have in Org's community! And to everyone who maintains a culture of teaching and learning through polite and respectful interactions on the mailing list and elsewhere: we always need more “power to the edges”. And I'm also very grateful to the EmacsConf organizers, because that's really taking care of the community! So, thanks very much! captions by bzg, sachac, and zaeph

Back to the schedule
Previous: CLEDE: the Common Lisp Emacs Development Environment
Next: How to build an Emacs