The governance of elm docs and smaller tools

Request Feedback
1

I am looking to understand better and discuss the governance of elm-packages. The discussion can probably be extended to the docs and other tools. Disclaimer: I’m rather new to using Elm, so the answers here might be obvious to more involved users and contributors. I must say though that I have read/listened to several articles and talks about Elm and it’s governance, so I have a rough idea of the philosophy behind it.

I understand that the governance of the language (and of some of the critical tooling like elm-test) is a very sensitive thing, and I fully appreciate the advantage of having Evan validate and think through every language change. I feel that it’s a good system and that it benefits the language’s design in the long run. The primary benefit that I can perceive is to avoid adding features that people start depending on, and that get removed later on, or solving the wrong problems, or solving the right problems in the wrong way.

But I do not feel that this requirement should apply to every repository/project of the elm “official” sphere.
Looking at elm-packages today, I saw a few PRs that solve basic problems that I (as weel as others, judging by the feedback in the PRs and the issues) have encountered while learning the very basics of elm. Those two are prime examples:

Those have been sitting here for months, and reading the PRs and the linked issues, there seems to be both :

  1. an agreement that the features are useful
  2. no response from anyone as to whether or not this will ever be addressed/merged.

Looking at those PRs accumulating and missing very basic opportunities to provide a better experience for newcomers (to the point some folks have had to create a browser extension to add some of those features: https://github.com/elm/package.elm-lang.org/issues/27#issuecomment-516638844), I’m left wondering: are tools like elm-packages under the same governance as the language itself? If so, has the relevance of using such governance for such tools been discussed?

The docs, package manager (as far as presenting information goes) are different to the language in substantial ways: their features can be switched on and off, and decisions can be undone easily, without much trouble.
For instance, say we decide to display the install code on the package’s page. Later on, new information shows it was the wrong decision, and we find a better way to solve the install problem. Well, we’ll just remove it! Those kinds of features have very little dependencies, but can still significantly improve the user experience (I personally have had a few highly frustrating hours at the start trying to install a package with a command from an (old) example on a 0.19 project, or trying to find out why this nice package wasn’t available - it turned out to only be available for 0.18. Both of those problems wouldn’t have existed if those PRs had been merged).

So my point here is that such small decisions shouldn’t have to be validated and accumulate on the top contributor’s todo-list, but rather that guidelines could made for each tool category, giving other people the ability to merge such small improvements.
Or perhaps I’m uninformed (and stand ready to be corrected), and there actually already exists a way to do so, but having PRs like those sit for more than a year without feedback seems to demonstrate that it doesn’t quite work right.

26 Likes
2

One way to think about this is to consider that in an open source project there are two distinct roles: contributor and maintainer. The contributor contributes some change (a PR), the maintainer role is to evaluate the contribution and merge it or reject it based on some criteria.

Right now, the elm organization has only one maintainer: Evan. Evan is also the main contributor to that organization. Because of this setup and because some things are more important than others, various PRs do get delayed. Evaluating a PR is not as trivial as it might seam when you want to do a good job. A lot of consequences have to be weighted and sometimes, a huge chunk of code has to be uploaded to “main memory” in order to properly evaluate the PR. Context switching is very costly when you do deep work.

This setup is what was decided to be the best setup for the evolution of Elm. It might not be perfect and it has its downsides but this is what was considered to work best. There are historical reasons for this. There were various other setups that were tried.

Also, historically, some discussions around this topic ended up with a lot of emotions. Two relevant resources that I recommend you read/watch are:

  1. What is “constructive” input?
  2. The Hard Parts of Open Source

It’s all a game of trade-offs. Each option/setup has its own advantages and disadvantages.

I suspect that I’m Mr. Helpful from the above post and in the time that has passed since that post was written, I realized that the best way forward is to accept the things the way they are. The best way to criticize is by creating.

“It is not the critic who counts; not the man who points out how the strong man stumbles, or where the doer of deeds could have done them better. The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood; who strives valiantly; who errs, who comes short again and again, because there is no effort without error and shortcoming; but who does actually strive to do the deeds; who knows great enthusiasms, the great devotions; who spends himself in a worthy cause; who at the best knows in the end the triumph of high achievement, and who at the worst, if he fails, at least fails while daring greatly, so that his place shall never be with those cold and timid souls who neither know victory nor defeat.”
― Theodore Roosevelt

In closing I would also like to add two other resources that I consider very useful for a person new to Elm, especially if they want to approach contributing :

  1. Building Trust: What Has Worked
  2. Code is the Easy Part
1 Like
3

I was going to write a lengthy response outlining the problems and proposing solutions, but from the posts you linked, I realise that by its very nature, my post, as well as my point of view, are unwanted. While I understand why, it saddens me, and from my perspective, it is very much tied to the lack of distinction between criticality levels (I must be part of the “just delegate” brigade).

I hope that if anything, my post was another data point that outlines very real hindrances to beginners that are not being addressed (more than a year is a very different time scale than “right now”). But I trust the maintainers to look at the data and make the right decisions at the appropriate time!

I apologise for the potential headaches this post would have caused them :wink:

After I got frustrated for a few hours trying to figure out how to install and import elm-css (there was great confusion for me between 0.18 and 0.19), when I finally had it working, I immediately opened a PR to add this information to the README, so that this friction I felt didn’t impact anyone else : Add installation instructions to the README for newcomers by GabeAtWork · Pull Request #482 · rtfeldman/elm-css · GitHub
It’s close to a year later, and this PR still hasn’t been addressed, and as I said, I now understand why. Of course, this is no mathematics library!

However, for anyone who might care, I’d like share how it made me feel as a new user/small contributor:

Contributions are not welcome.
Trying to help others avoid the problems you faced is not welcome.
Your perspective and experience as a new user is of no interest to us.
The frustration you felt does not matter to us, any more than that of people who’ll have the same experience you had

Now after a lot of reading and trying again, I get it! I get why I got this impression, I get why these types of contributions are disregarded, I get why those “small problems” never get addressed. But I suppose I reserve the right to disagree that those are “small problems” and that they’re not worth addressing “right now” (or within a year). This experience might have made me simply walk away from Elm, or at least dissuaded me to invest any significant time and effort in it.

But the wonderful thing about disagreement between adults is that it doesn’t have to antagonise anyone. I am still thankful for the time and effort that is being put into making Elm great, and I wish the maintainers good luck and good courage to continue to make Elm and its ecosystem better. I can’t wait to see how it will look in the times to come.

EDIT : since there is no point in pursuing this discussion, this topic probably had better be closed early ; however I do not seem to be able to close it myself (whether out of my inability to find the proper button or because it simply isn’t possible)

25 Likes
4

To speak as the maintainer of a smaller tool (elm-format), not all tools and packages follow Evan’s philosophy described in the discourse thread and youtube videos linked above. Elm-format does not.

I’ll make an attempt to state the philosophy for the tools and packages I maintain:

  • input is welcome from anyone using the tool
  • all coherent suggestions deserve an explanation of what factors are influencing the decision
  • everyone is striving for productive discussion, but everyone has different levels of skill at doing so (and that varies over time); lack of communication skill should not be a deal-breaker for participation
  • those interested in participating more but lacking necessary skills should be supported in their growth

This thread has pointed out that I need to make those things explicit somewhere since it’s natural to assume that Evan’s philosophy would apply to elm-format since I’ve never stated otherwise. I’m thinking that for elm-format that would mean adding a CONTRIBUTING.md including something to that effect. Would that help communicate the differences?

Something else to note is that elm-format (and many Elm tools, including elm-test and elm-css) don’t have any financial support. There are several cases where I haven’t (yet) followed through on that philosophy for tools I maintain. That’s simply due to the limited amount of free time I’m able to put toward those projects. What would it take for enough other people to be interested in contributing their time so that all issues get dealt with in a timely way? That’s another thing that I haven’t had enough time to devote to, but contributions to solving it would be welcome.

37 Likes
5

Before I say anything else, thank you for elm-format! It’s such an important part of my development experience, I don’t know how I’d do without it ^^

In my opinion, those a great principles for tools of this scope!

CONTRIBUTING.md is the standard, at least in the JS ecosystem (which I’m more familiar with). I can simply say that that’s where I’d start looking! Stating in the README : “Contributions are welcome! If you’re looking to contribute, you can start with help-wanted issues.” or something along those lines, with a link to CONTRIBUTING.md starts making users conscious that help is needed and wanted.

Of course, issues have varying degrees of value in their being solved. My original post was about what I perceived as high “friendliness value” opportunities with benign fixes being ignored for a year. In fact, in that case, people had already contributed, but their contributions were being ignored.

How do we get people to contribute on the highest value issues ? As someone with only a few minor contributions behind me, of course I’ve got no magic answer. But here’s practices I believe can alleviate some of the stopping points I’ve encountered when I’ve wanted to contribute to a project myself. It’s up to each maintainer to decide which are realistic and valuable to adopt.

  • Openly talk about the need for contributors. Looking at a given repo, I have no idea what the current status is or if help is even wanted on new features or bugs
  • Address current contributions (I’m talking mostly about PRs) in a timespan hopefully short enough to encourage the person who contributed (even if it’s to just decline it or delay its evaluation)
  • You know your tool and what problems need to be solved with what priority : spending time (I know :disappointed:) guiding people to concrete problems they can investigate and solve helps them dip their toe in the water. Two things I usually find missing :
    • Having the help-wanted (or another label) labelled issues mean “anyone can go ahead writing a fix here”. That may already be what this label means for your repos, but as someone from the outside I don’t know that. Stating it in the README or CONTRIBUTING will make it clear.
    • Adding a “Bounty” list of important issues that you want to be tackled in the README or CONTRIBUTING (one of the fears I’ve had is to spend time on unimportant issues)
  • Adding a Code of Conduct to make sure people aren’t pushed away by poisonous behaviour. Kudos for having one on elm-format :smiley:
  • You might already do that, but you can ask people who have already contributed whether they’d like to contribute more, and if so, redirect them towards the “Bounty” list

Again, to be clear, I’m not saying every contribution a project needs will be solved this way. But I do believe that such a care 1. helps solve the kinds of issues my original post is about 2. sends a message to potential contributors, a message that the current governance of Elm doesn’t send (even for less design-critical projects):

You’re welcome, your input and your time are welcome.
You can start small before giving more.
You don’t need a PhD or to have written three libraries to contribute something useful and appreciated

As far as the community is concerned, we need to celebrate more explicitly the maintainers and contributors, and make their work more visible. Thank you for your work Aaron!

2 Likes
6

I really like this framing!

In the interest of shared understanding (and because I know the author perspective isn’t shared very often), I’ll do the same for this PR:

I’ll share how it made me feel as an author to get this PR:

Argh, that’s a shame that he had this experience as a beginner!

Still, I don’t think this fix is the right answer. The only reason he didn’t know how to install elm-css was that it happened to be the first Elm package he ever tried to install. If I accept this, am I setting the precedent that all Elm packages should add this to their READMEs, in case that is the first package they happen to install? That would clutter up a ton of READMEs for a pretty narrow situation.

Alternatively, maybe we should put something in package.elm-lang.org that says like elm install rtfeldman/elm-css at the top of the package’s docs, so you can copy/paste it into your CLI. But then again, we talked about adding exactly that feature once before and ended up deciding against it - although I don’t remember exactly why.

Okay, so I’m not going to accept this PR, but I don’t want to close it without explanation. I’d be upset if someone closed my PR without explaining why. So how do I explain this to him?

Well, I could write down all this stuff that just went through my head, but then he might ask me to link to the discussion where we decided against the copy-pastable elm install thing in the package website. That was years ago though - I have no idea where it was anymore. Was it even in a linkable place, or was it in person at an Elm conference or something?

So maybe I shouldn’t even bring that part up. Instead I should just say “I don’t think this is a good precedent to set,” something like that. But I need to be careful what words I choose to say that, because every time I leave a negative comment on a PR, that is one more thing someone in the future can use to say “the Elm core team closes PRs without engaging with contributors; here’s a link to rtfeldman coldly shutting down a new contributor with practically no explanation. This person was just trying to help with a simple README addition.”

There’s also the question of whether he wants to debate my decision. Once I’ve posted a comment, he knows I saw the PR and I’m obliged to engage with the debate. Otherwise later people will link to this post and say “Elm core team doesn’t listen to people who disagree with them; for example, here’s a link to rtfeldman ignoring this person after he calmly made one single - and completely valid - counterargument to rtfeldman’s reasoning for closing the PR.” I mean, hopefully it won’t happen this time, but it’s definitely happened before. Do I know it won’t happen this time? I don’t know this person; maybe they will want to debate about it. (Plenty of people do.) Do I want to risk getting sucked into an argument over this?

Okay, I’m definitely over-thinking this. Why don’t I just say “I don’t think this is a good precedent to set, but thank you for the idea!” and close it? Then again, wasn’t that the same mindset that led me to post whatever that last comment was that later got used as ammunition against me and people I care about? I should at least revise my wording a little to try and bulletproof it against that.

Argh, what time is it? I don’t want to deal with this right now. I’m going to move on to another PR and come back to it later…

… [repeat every subsequent time I revisit the PR, except in condensed form as I re-remember my thought process from the last time.]

I’m not saying this is a great way for me to live my life or anything, I’m just sharing what goes through my head in situations like these. I’ve done this mental merry-go-round on many a PR I wanted to close.

The dynamics of the Internet are weird. In person I’d have zero problem explaining the situation and it’d be resolved in no time at all.

16 Likes
7

I feel you’re completely overthinking this. Every person new to Elm will have exactly the same problem as the author of the PR. Yeah, first time they installed an Elm package. Why talk about “precedent”? It’s not a legal case. Every first time Elm user would have loved to have this in the README.

And so what if every Elm package includes basic stuff? Just look at other eco-systems, yes, that’s what people add to their README. You want to help the first time user as much as possible.

4 Likes
8

Thanks for the link to Elm Package Info, which I find very helpful!

3 Likes
9

Thank you for taking the time to share your perspective! And again, sorry for the overhead this type of discussion represents for your already busy schedule ^^

If you’d closed it, I don’t know whether I would have understood, and I can imagine it’d have indeed ended up in a discussion. And I mean, who’s to say what the best reaction was? Of course your time is limited and you have to choose the lesser of several evils, and that’s what you did, freeing up your time for more valuable pursuits.

In this case, part of the problem is that a decision concerning whether to display package installation instructions was made a long time ago, and very few people have this information. I don’t know how to fix that, except as we’re doing here, talking about it. Now I have a discussion to point for future reference if I see this point brought up elsewhere.

I do agree with this point. The reason I opened the PR in the first place is that, coming from the JS ecosystem, this felt like it was just missing. I personally don’t see the problem with having setup instructions in the READMEs: either people are familiar with installing packages and they’ll skip right through, or they’re newcomers and they’ll be glad it’s there.

That being said, that’s my point of view as a user. I understand the authors might not have the same point of view for valid reasons I do not see from my perspective.

5 Likes
10

Interesting that knowing how to elm install could be a detail that is hard for a beginner to find.

I had a quick flick through the guide to see if it is mentioned there, and I don’t see anything. I am inclined to think that the guide should be the best place for beginners to start. Are PRs getting merged into it? I see 143 PRs closed, but mostly seem to be for small typos.

The experience that beginners have is incredibly valuable, because only a beginner can see things with fresh eyes, and those eyes see things that more experienced users can no longer see.

===

Also worth noting, that like most unix commands, simply running elm provides instructions on how to use it:

Hi, thank you for trying out Elm 0.19.0. I hope you like it!

-------------------------------------------------------------------------------
I highly recommend working through <https://guide.elm-lang.org> to get started.
It teaches many important concepts, including how to use `elm` in the terminal.
-------------------------------------------------------------------------------

The most common commands are:

elm repl
Open up an interactive programming session. Type in Elm expressions like
(2 + 2) or (String.length "test") and see if they equal four!

elm init
Start an Elm project. It creates a starter elm.json file and provides a
link explaining what to do from there.

elm reactor
Compile code with a click. It opens a file viewer in your browser, and
when you click on an Elm file, it compiles and you see the result.

There are a bunch of other commands as well though. Here is a full list:

   elm repl    --help
   elm init    --help                                                                                         
   elm reactor --help                                                                                         
   elm make    --help                                                                                         
   elm install --help                                                                                         
   elm bump    --help                                                                                         
   elm diff    --help                                                                                         
   elm publish --help                                                                                         

Adding the --help flag gives a bunch of additional details about each one.

Be sure to ask on the Elm slack if you run into trouble! Folks are friendly and
happy to help out. They hang out there because it is fun, so be kind to get the
best results!
2 Likes
11

Missed it, it is described in the Installation section of the guide:

https://guide.elm-lang.org/install/elm.html

1 Like
12

I think the problem here is different people like to learn languages in different ways.

Personally, I tend to read all the tutorials and syntax guides I can get my hands on before I write a single line of code. So for me I had already been vaguely aware from the guide of how to install packages (although I couldn’t perhaps remember the exact command) before I started writing any code. When starting out I also prefer to try and create something using just the official language and libraries first, before exploring external libraries. The result was that the first time I tried to import something that wasn’t in elm/core (e.g. Random) the elm compiler gave me wonderfully precise instructions on exactly what command I needed to run in order to get that to work… (see the hint at the end)

Detected problems in 1 module.
-- MODULE NOT FOUND ----------------------------------------------- src/Main.elm

You are trying to import a `Random` module:

4| import Random
          ^^^^^^
I checked the "dependencies" and "source-directories" listed in your elm.json,
but I cannot find it! Maybe it is a typo for one of these names?

    Array
    Main
    Task
    Browser

Hint: Maybe you want the `Random` module defined in the elm/random package?
Running elm install elm/random should make it available!

So this works great for people like me. But many people prefer to jump in at the deep end, and so it makes sense to have this information available in additional places. Now there are aesthetic arguments to be made about whether cluttering up the README of every single package on https://package.elm-lang.org/ is appealing or not; but from a purely practical point of view I would say it is a very fragile way to deal with this as it relies on every package developer remembering to do so. Much better would be to link prominently to this from the package web page. The question is what is prominent enough? There actually is a link in the sidebar of the packages webpage, under the title “Resources” and with the name “Using Packages”, but I have to say I’m not sure that it’s very prominent. @GabeAtWork it would be good to know whether, as a beginner, you did notice this and if not where you would have looked for such a link? Maybe it could be moved to a better location? The other problem of course is that the link is broken. It points to an archived repository, and following the merge history still doesn’t take you to instructions on installing packages. So this definitely does need fixing. But before filing a bug report on it, maybe as a community there should be some discussion on where best to put this link and what it should link to (the relevant section of the guide? Or to some smaller more specific, less likely to become outdated/deadlinked instructions?).

Finally don’t give up on Elm! As you get a little bit more fluent you will find that most things really are signposted very well. And generally beginner friendliness is something the project is always striving for (in my experience).

2 Likes
13

The hurdle for me had to do with 0.18 tutorials giving other commands, and with the difficulty to figure out the install path from the github repo name. I eventually managed it, but it would have been a lot less confusing.

To compound this problem, I think I remember (although I might be wrong) that the official guide was out of date at the time (0.19 had just come out), so I had to rely on not quite up to date material.

3 Likes
14

That’s indeed what I was doing: I was evaluating whether using it at work would make sense, so I was trying to reproduce the different aspects of what we typically used at the time. When I saw that styling might be different from what I was used to (in the React world, module .css files and/or styled-components), I wanted to try out libraries that seemed to solve that problem, to evaluate whether Elm was a good option.

The place where looked was not package.elm-lang.org, because I saw it as an equivalent to the npm website, which I generally disregard. I prefer going to the Github repos out of habit (I’ve found the information there to be more reliable for some JS packages), so that’s where I tried to find the installation instructions, because of my personal bias. That being said, this bias might be shared by many people in the JS ecosystem.
Secondly, the link you mention only appears on the home page. I probably arrived directly on the package’s page.

Thank you for your encouragement! Don’t worry I’m not giving up :wink: In fact, we planted the seed just last week at my company! I’m having a great time with it now, and in fact @rtfeldman’s manning book was very helpful to shed light on a few things I hadn’t quite figured out before. I look forward to seeing Elm and its community grow, and I hope I’ll find useful ways to contribute myself.

15

Yes that’s definitely a problem. As an experiment I just tried Googling “elm-css” and in fact the Github page is the first hit. Once you are at the Github page clicking on the link to the packages website as you say takes you straight to the package’s page and that link never appears. I definitely agree the link should be viewable from any page on the packages website, as this would seem a very common route to end up taking. (As evidenced by the fact that the Gituhub page features higher on Google’s ranking.)

Glad to hear you’re enjoying Elm more now :grinning:

2 Likes
16

Hello everyone, very interesting discussion.

@rtfeldman It is amazing that because of the preexisting atmosphere of the Elm core team receiving regular criticisms, you end up not knowing how to express your views to the point of staying silent. It gives the impression that being an Elm core team member puts a lot of pressure on you, because people hold you accountable in ways that are beyond reasonable. I know I would hate if people over-interpreted everything I said the way they need to support their point. (And of course, I’m not saying either that people should not be held accountable for what they say.) It looks quite similar to harassment to me (except that the usual understanding of harassment is when one person repeatedly targets another one, but there are precedents for interpreting a crowd of people repeatedly targeting a person / a category of population as harassment too). Therefore, it seems like this is something that should be part of the code of conduct. Whenever it happens, you should be able to reach out to another member of the core team (or whoever it is who enforces the code of conduct) to put an immediate stop to it. Being an open source maintainer should never have to feel like this :cry:

Now, back to the topic of addressing newcomers contributions:

As a maintainer of the reference manual of another language, I can only agree with this statement. Let me share the way that I, as a maintainer, would have addressed this contribution (after deciding I wouldn’t accept it).

First, do not wait to delay the decision: it is always disheartening to have open PRs linger without feedback. Clear-cut decisions to close (when done politely) are always preferable.

Second, seize the opportunity to chat with a beginner: as @rupert said, beginners’ feedback is incredibly valuable. It is not so frequent that beginners feel confident enough to contribute back from the start, and thus, when people start contributing, it is often too late to have that kind of early feedback.

Clearly, in this case, there was both an issue, and a proposed (but unsatisfying) solution. I would have answered something like the following:

Hello, thank you for your contribution. I don’t think that this goes in the right direction though: there is no reason why elm/css in particular should have installation instructions, and if it is all packages that should have such instructions, then it probably means that there is a bigger issue to address. Would you mind describing your experience and the issue you faced in much more details? It is always very interesting to hear from newcomers, and it can ignite discussions with other Elm core team members to come up with ways of making your experience better. I cannot promise immediate action, or a report on what our conclusions are, but your feedback is definitely appreciated!

The last sentence echoes what GitHub staff always say when you send them feedback:

I can’t promise that we will implement any changes any time soon, but your feedback is super appreciated and is noted.

Furthermore, I think that this kind of answer, which asks for feedback for later consideration, entirely closes the door to a possible debate on the decision of closing itself (I might be wrong of course, but then it should always be OK to close the debate with “Hey, I’m the maintainer here! I’m entitled to make decisions on what to merge or not. Thank you very much!”).

10 Likes
17

As a (very) small point of reference, I come from the Go world, and consider myself a relative expert. I still find the “how to install this package” one-liner that almost every Go package readme includes useful.

7 Likes
18

Here on more observation from this great article on How to Reach Your Goals: 1000 GitHub Stars in the first Open-Source Software:

Imagine that your project has already captivated some users who want to try it but you have not provided instructions on how to start it …What a disaster!

Finally, Richard had a whole talk on how functional languages can become more popular. He mentioned “the killer app”. What if someone comes to Elm for elm-css? And hey haven’t gone through the Elm tutorial. It seems to me Richard assumes there’s only one way into Elm, and that’s through the tutorial. But what if they come through the door of for the killer app? They first want to try that out, before investing more time. And then they stumble at the install. What a pity.

5 Likes
19

This topic was automatically closed 10 days after the last reply. New replies are no longer allowed.