Proposal & looking for feedback: fostering more of a community

[hugelgupf]

Hey all,

I've made some observations I want to remark on in the last few months. Apologies for the rant-style... just on my mind today.

u-root isn't a Google project, but de facto those of us at Google provide >80% of the contributions - I would like that to change.

The four largest contributors to u-root and fiano are, naturally, the four of us working full time on LinuxBoot at Google. After that, the number of contributions and LoC or whatever drops off steeply. Most of the ones after us are our former interns. Yet, anecdotally, LinuxBoot is seeing pretty good adoption, from the stories people tell us.

At the same time, anecdotally, I've told many people that u-root might contain some good first projects for people who want to learn Go. A lot of the commands we have are very self-contained, very testable, and there's often work to be done on them. Yet - none of them ever do. (And I didn't expect a high conversion rate.) And external LinuxBoot users don't seem to be contributing back much. Are they just taking u-root as is and happy with it? I doubt it, we have lots of problems and bugs. And many contributors that do start often drop off after a few commits. Why is that?

There are probably some "all is good" reasons for that, everybody gets busy, but more than likely there are things we can do to improve. After all, the long-term vision of the project is for us all to collaborate and share knowledge and code.

A few things I've gathered:

Bad for adoption

• We (the four of us) have been pretty bad at responding to issues and PRs. They sit around for a while, it takes some time for us to investigate, or maybe nobody feels responsible for a particular issue / PR.
• I'm unsure if people are unhappy with how we handle PRs?

Bad for newcomers

• We have very little in the way of documentation.
  • Our godocs are pretty bad. (See: https://godoc.org/github.com/u-root/u-root/pkg and its lacking package docs, see the mess that is this: https://godoc.org/github.com/u-root/u-root/cmds) We don't follow godoc format, we put examples in random places outside of godoc formatting, etc.)
  • LinuxBoot docs in general are lacking. The "book" of docs is trying to make up for it - https://github.com/linuxboot/book - but it isn't linked anywhere yet.
  • Our top-level godoc is empty: https://godoc.org/github.com/u-root/u-root
  • We have a README here, as well as an outdated website (u-root.tk) as well as the LinuxBoot website (linuxboot.org).
• Our issues are very hard to read.
  • The titles make sense only to us, the content is sometimes worse.

Some Ideas

Inspired by @bobcatfish's talk at the Open Source Summit (yes, months ago).

1. Github issues need more context.

   • Need to do a scrub of everything: either add more info, or close the issue.

2. Enforce godoc standards for code.

   • Move some of our READMEs and examples to godocs.
   • See https://blog.golang.org/godoc-documenting-go-code
   • See https://godoc.org/github.com/fluhus/godoc-tricks
   • Good example: gVisor is extremely good at this. https://godoc.org/github.com/google/gvisor/pkg

3. Enforce real commit messages w/ real context.

   • At the level of rigor that the Linux kernel runs on. What, why, why this.

4. We need one unifying landing site for open source firmware.

   • It should concisely make clear what each project is, and how they relate. A chart.
   • Link to site, repos, and docs of each project.
   • List recommended approaches.
     • You're running x86 servers? Look at this!
     • Chromebooks? Look at that! Etc.
   • Like the LinuxBoot book, but another level up.
     • Someone should go through and edit (like editor-edit) those docs. They could become that site, tbh?
   • Get rid of u-root.tk, redirect to site.
   • This is not fully fleshed out in my head, but the proliferation of stuff is bothering me.

5. ???

Looking For Feedback

What can we do better for you to be excited to work on u-root?

[hugelgupf]

E.g.: u-root minimum kernel requirements. For LinuxBoot and for u-root as its own thing. https://github.com/u-root/u-root/tree/master/configs says the configs are for tests. We should make that not so.

[rminnich]

I wonder how many of us will be at the firmware workshop in june and if we should put part of our time into making this better.

[zaolin]

Maybe some topics could be added to the OSF Hackathon: https://docs.google.com/document/d/1YsxFkX1CgHdRFf-updioOIO4BPH47Oz78invd6y9ryU/edit#heading=h.qbqupv1g13wg

[JulienVdG]

I've taken the liberty to add two points to the agenda, I'll be there and as a newcomer I can express some of my frustrations...