I’ve begun to think more about how the restrictions of contributing to Elm are communicated lately. The reason is that I’ve now seen two posts on reddit (on different sub-reddits, here and here), which cautioned newcomers about those restrictions, and recommended they read about them by reading the all time top posts on the Elm sub-reddit.
The actual top post is Luke’s blog post on leaving Elm (discussed on Discourse as well), which is not a great way to start someone off with Elm. Both the aforementioned reddit posts are, as far as I can tell, trying to set expectations for the newcomer. Elm doesn’t operate as many other open source projects do, and many people seem to care about this aspect.
So I tried to figure out, how are the restrictions that are in place actually communicated? Is there a document we can point people to instead of Luke’s blog? And the answer is: not really.
There’s a number of tidbits here and there, like this quote from the elm-lang community page:
So given our goals and resources, we have found that having good working relationships is crucial for collaboration on core code.
The same page also points to several YouTube videos, like Code is the Easy Part. That’s all on that page though.
Then there’s also a GitHub repository called expectations, which is a collection of best practices for how to successfully contribute to Elm core code. I haven’t seen any links to this repository though. There’s also the projects repository, with ideas for projects to collaborate on. This page also links to Code is the Easy Part on YouTube, as the introduction for how to contribute to Elm. It also points to the roadmap, that was published while 0.18 was the newest Elm release.
In my opinion, this means there’s really no single summary of how you can contribute to Elm. You have to piece together much of the information from disparate sources, and just looking at the above links, there’s still some gaping holes to be surprised by, like:
- You can’t compile core Elm code without being a member of the right GitHub organization
- How do you become a member of said organizations?
- Does it require the aforementioned “good working relationships” first, and how might you build that?
- It’s common knowledge that Evan is a busy man, so should you try and get a good relationship with him, or is it better to talk to someone else?
- What’s the difference between
I’ve been frequenting this community for a few years now, and I can’t answer any of those questions, so I doubt newcomers stand a chance. In fact, my impression from spending time here on Discourse, is that trying to contribute as much as a spelling correction requires years of patience, and may never be met with more than silence. This impression is based on posts like this and this. But this impression also seems to be counter to the praise that Evan gave Bekk and Robin in this blog post for their contributions to Elm.
I have three concrete suggestions:
Have something like a “Governance” page on the main elm-lang site, which explains the restrictions around working with libraries containing kernel code, the purpose of
elm-explorations, and so on. It should also link to the
expectationsrepository. Describe what it actually takes to contribute code, so people can better judge if it’s worth trying. How do I start building a good working relationship without opening pull requests?
CONTRIBUTING.mdfiles to every repository in the
elm-explorationsrepositories. The only ones with such a file, at the time of writing, are webgl and linear-algebra. I imagine many people will try and look for these descriptions, and they can link back to the governance page, and add instructions that are specific to the repository.
Don’t refer to YouTube videos for important information. It’s fine to have those videos, but if there’s something important in there, it should be available in writing as well. Videos are very poor for searching and skimming of information.
In short, being more transparent about all this would be good. Feel free to critique my findings and ideas, and add your own as well