RFC: documenting PureScript's governance/structures/policies/processes

#1

Why am I posting this

The context for this post is that some time ago I voiced a proposal to move Spago under the PureScript org on GitHub (the various reasons for why this is a decent idea are in the linked post).
People seemed to like it, so this finally happened some days ago! :tada: However you might have noticed that I just moved the repo back to the Spacchetti org.
The reason for that is that I found myself unable to perform administrative tasks in the new location, and the reason for that is that I’d need to be member of the PureScript org to have access to the aforementioned things.
However, it was decided that I didn’t have enough contributions to the org repos to deserve a spot in there (I could quote the exact words, but then I might be misquoting and/or leaving context out, etc etc, so note that what you’re reading here is my perception of the story, how I experienced it, how I felt, and so on)

This said, the point of this post is to bring awareness to the larger community on how the language governance is handled, and hopefully spark some change (which some of you might read as “making a fuss about things publicly”, but you know, that’s kind of the point of democracy as well, so I guess it’s a good practice to have? You know, “call your representatives”, etc)

What’s my problem here

In the span of a couple of days both me (in Spago) and @justinw (in psc-package, see this thread) lacked access to CI settings for performing administrative tasks that are normal as maintainers of these pieces of software, and I think this is terrible: I feel it’s frustrating to be a maintainer of something but still not have access to all the things related to the lifecycle of that something.

(Note: of course I could continue just fine to develop stuff under my profile or the Spacchetti org - and that’s what I’ll do anyways - but that wouldn’t solve the problem that we were trying to solve in the first place)
(Note: I tagged Justin but he’s not involved in all these words, I just noticed the pattern happening)

What’s my wish for today: empowering people that want to do things

So I just wish that we’d liberally give out membership of the PureScript org (on GitHub). In particular, the policy that makes most sense to me is “if someone’s a maintainer of a repo in the org, they should be a member of the org”.
Note: member of the org is not the same as admin of the org.

But isn’t this dangerous?

No: org members cannot interact in any special way with repos they don’t have access to in the org. They can only create repos new repos under the org, which admins can quickly revert if anything suspicious happens.

My main source of inspiration for how this empowerment can happen beautifully in the context of Open Source projects is dhall-lang’s “contributing” document (shoutout to Gabriel for handling all of this so gracefully). In there - very early in the history of the language - were defined things like:

  • how to propose changes
  • how they get approved and who can approve them
  • timeouts for decisions
  • how to get the commit bit to things

I’ve been involved with Dhall for some time now and these policies have worked out wonderfully and very effectively.
I also adapted that document for Spago, and as a matter of fact I give out the commit permissions very liberally (one needs very few non-trivial commits usually), which seems to work out very nicely as well :blush:


What’s my wish for this topic in general: documenting processes for PureScript

Currently it is not possible to find publicly any info about the following things in PureScript land:

  • if there’s a “core team”
  • who’s in the “core team” exactly
  • what are the rights and obligations of the members of the “core team”
  • how this “core team” overlaps with the purescript org on GitHub
  • what are the rights and obligations of the org members
  • what’s the process to get in and out of both the “core team” and the org
  • what’s the contribution process to get the commit bit to the repos owned by the org
  • etc

What I would like to see happening in the longer term is that we create a place to write all of this down (maybe a purescript/governance repo? It doesn’t really matter how, it just needs to be a public container)

Note: something that I am not expressing here is any kind of moral judgement on what this “governance model” is. For what I care we can have open membership, or a BDFL, etc. Whatever thing is fine by me, as long as procedures are documented in the public: this is so that expectations are clear and openly stated, and this avoids mismatches and implicit behaviours from happening.

Why do I wish for this?

Subtitle: why is transparency important?

Now, the last thing I want to do is to sit here and give a lecture about why transparency in organizational processes is important, but I guess the need is present after all.
Here are some reasons why a public organization should make their processes as transparent as possible:

  • accessibility: if processes are documented publicly, everyone is aware of them, and can engage freely into these processes if they want to, and there’s a “correct” way to do that
  • …which enables diversity: if the rules of engagement are clear, this levels the field for everyone to contribute, since there’s a standard measure that everyone is being hold to, and implicit power structures are less effective
  • bus factor is also a very important one: publicly-documented procedures empower enthusiastic contributors to contribute to their maximum potential. If procedures are unclear they might get discouraged and shy away. If knowlegeable contributors get tired/busy/sick/etc and policies are not written down this might lead to lost knowledge, etc.

All of these factors are major contributors to project health, also known as “the probability that this language is still relevant in 5 years”.
I really want this probability to be as high as possible, and I really like this community, and I’d like all of us to succeed, so let’s try our best at this :slightly_smiling_face:

Peace,
Fabrizio

9 Likes
#2

Thanks for creating this thread. In general, I’m in favor of overall making member access more open. I’d like to address the issue of the scope of your inclusion, which may be in part due to miscommunication or misunderstanding.

This is just based on my understanding of the conversation, and I haven’t gone back to verify anything, so I’m happy to be corrected. When it was originally brought up, my understanding was there was a request to be an org owner. I expressed hesitation on the grounds that (and this is just my opinion):

  • The PureScript org is the language as we know (being implementation defined), which is the compiler and core libraries.
  • Org owners have the responsibility to maintain the language.
  • Org ownership should be predicated on significant and long-term contributions to both.

I was not under the impression that was what you wanted to do, and I didn’t think it would be necessary for maintaining the Spago tooling. I’ll admit, I don’t know the details of what tooling you use, what access you need, and I don’t really know what all the details of what membership vs ownership entails as far as GitHub permissions for those things. I am supportive of giving you and Justin everything you need to make your contributions successful. If you need membership to be successful, then you should have it. I apologize for that not being the case, and for it being frustrating.

As far as governance goes, it’s ad hoc, and that’s really all there is to it. It can be very frustrating, but we’ve generally taken the stance that we don’t want any given maintainer to feel pressured to do things that their life and schedules don’t permit. Unfortunately, we are all pretty strapped for OSS time right now, and so most of that goes to existing issues and features, and not into structure, governance, and outreach. I personally hope I can be supportive of anyone willing to take on these things and work it out if they have a vision to do so. I initially started work on a document outlining the org but I have not had time to get back to it, and I didn’t receive much feedback at the time from the other org owners (it happens). But I agree with you that it would be good to take this further and document it in a repo.

7 Likes
#3

Thanks for writing this up @f-f - I agree that this conversation is worth having publicly, and and project health is also something that I have been thinking more about recently.

That gist @natefaubion shared looks good to me so far, although I guess @f-f you’d be happier if it were a little more detailed?

The following sets out my personal understanding of the kind of governance procedures I think you are interested in. I don’t want to speak for the rest of the core team here, so what follows isn’t necessarily the official stance. Also, I’m happy to receive criticism on this.

On the topic of commit bits, I do think our current policy of only very rarely handing them out is preferable, at least for the compiler and core libraries. I have two main reasons for this: firstly, I don’t want the compiler to move too quickly. Decisions will often have unintended knock-on effects, and can sometimes be very difficult to walk back from once made, and handing out lots of commit bits can lead to well-meaning people taking the initiative on issues and moving decisions along faster than they really ought to be moved. In my experience, having been involved with the compiler for a while is usually necessary for developing the context to be able to foresee potential problems with suggested features.

On the topic of how decisions are made, the way I would describe it is that it’s not a democracy - community input is a large factor and of course we do want to make sure the community has a voice in the development of the language, but the core team has the final word. There isn’t really a BDFL situation either, i.e. there’s no (explicit) hierarchy among the core team; when there has been disagreement amongst the core team, we either find a compromise solution or defer making a decision on the issue. (If we were going to have a BDFL it probably would have been Phil, but he has stepped down and isn’t really involved with the development of the compiler or core libraries at all these days).

For the specific problem that you draw attention to regarding CI settings, do you know if being an org member (not admin) on GitHub is sufficient to be able to view and/or modify CI settings for repos in that org? I think different CI services might have different policies around this. In particular I think AppVeyor doesn’t handle this use case very well, I don’t think it really supports “org-scoped” CI projects at all.

#4

I literally just asked what was the policy for (quoting myself here) “pulling people in the org”, so the one you mention was definitely not my request.
I apologise for not having that conversation in the open, as I feel that would have avoided the miscommunication here. I’ll stick to public-posting only from now on.
(small note: if anyone is curious I can post the whole email thread here, as I assume all my emails to be public communication anyways)

Thank you! I’d be happy to move back the Spago repo if pulled in as a member of the org

That was exactly my impression (and it’s a very common situation in OSS to be strapped on time) and in fact my intention behind asking for clearer policies in general is to help involving more people in the process - so that some tasks can be lifted off the shoulders of someone that might not have enough time to dedicate to them - thus alleviating this whole problem. You could frame it as an investment for the language in the long term that has greater leverage than working on features.
Point in case the CI settings stuff: instead of having to sync with Harry to access them we’d save everyone’s time if we could just access them, and so on.

This already looks like a good start! :clap: I do have some a vision on this (as outlined in my first post, which is just a summary of how I see it, happy to expand further), so if you push this document to a purescript/governance repo I can start opening issues/PRs there so we can discuss every point further.

#5

I think it’s important to differentiate the groups of people that can “approve changes” with the people that have the “commit bit”

The “compiler movement” should be limited by the first group that approves/rejects things - which would coincide with the core team - so nothing would really change if we’d change the “commit bit” policy.

Having an additional “commit bit” group would mean that these people could do things like:

  • merge approved PRs
  • manage the issue tracker (label, close, tidy up issues)
  • cut releases if there’s the green light to do so
  • etc etc

As an example, in Spago a bunch of people have the commit bit, but they usually only merge once I approve things. And even in the case a change gets merged without approval, it is trivial to roll back.
Again, I invite you to read through Dhall’s contribution document to see what I mean.

I don’t have much to say on this, other than I’d like to move these discussions to a place where all of this can be documented and called an “official policy” (note: this includes the fact that there’s a clear process to change this official policy, etc)

I think just being a member is enough. E.g. in Spago @klntsky is member of the org and he can manage CI settings of projects just fine. And in the case of services where it’s not enough I can write to their support and enact a manual change (the important point is that I can do so as a representative of the org, which means probably having a chance to get the fix through)

#6

Sure, but I don’t think any of these things are a bottleneck. For example, merging a PR once it has been approved is also trivial - the hard bit is getting it to a state where it’s mergeable. I’ve read Dhall’s contribution document by the way - as it happens I remember it being written, as I followed the evolution of Dhall from back when Gabriel first started blogging about it - and my reaction to it then, which is the same as it is now, was that I’m impressed that he’s committed himself to all of those obligations and procedures, but there’s absolutely no way I can ever see myself running an OSS project in a remotely similar way. In particular I think it’s more effective, and less stressful, to wait until we are confident that any given PR is good to merge before merging it.

(note: this includes the fact that there’s a clear process to change this official policy, etc)

While I’m happy to move these things to a GitHub repo, I am not keen on having all of them being permanently up for debate with anyone who wants to debate them. Of course I’m prepared to explain and defend governance decisions to an extent but I don’t see the value of having an official process to change them - I don’t think we should be changing them particularly often, and anyway, any change to it is up to the core team, which hasn’t really suffered from not having set out explicit frameworks for making these sorts of decisions in the past.

I do agree with @natefaubion in that you having org membership on GitHub would be a good thing to do if it enables you to do the things you need to do to maintain things like package-sets and Spago.

#7

@f-f I agree completely with what you’ve said.

A few months ago, I tried to start documenting things with the thought that we could make that documentation public. I got frustrated again pretty quick, and gave up the ghost. Sorry for not following through. I’ll be real honest; I’m probably not going to pick that back up.

Here’s where I stand:

  • I don’t think the current model/process is good.

    Decisions are made by one person, basically, assuming they have the support of other people. Who else needs to support it, who knows? Conflicts are resolved by someone backing down, or someone giving up. This doesn’t foster growth in any way. People are discouraged from trying something different because it involves so much effort.

    What can someone on the core team do? Who knows what the limits are of one person? Who is going to stop someone that does something others don’t agree with? How would we even do that? I have no clue what I’m allowed to do, or what I’m not allowed to do.

  • The lack of open membership is a bigger problem than anybody is willing to talk about.

    There’s no rhyme or reason to membership. Why am I part of the core team? I make like one package every three months, which I rarely contribute to. I don’t participate in conversations with the core team–primarily because they’re all in private. I don’t participate in conversations in the general. I don’t respond to PRs in a timely manner. Yet, here I sit on the core team.

    Why isn’t Jordan part of the core team? He’s documenting so much, and in such detail. Why isn’t Alex part of the core team? He’s done a ton in community events. Why aren’t you part of the core team? You’re fixing so many rough edges around tooling. How does anybody else even become part of the core team? None of this stuff is clear, and it’s not clear why not.

    Keeping the core team as minimal as it has been hasn’t been great for the ecosystem as a whole. People get burned out and leave. And there’s always been this talk about how the core team is understaffed, but we don’t bring in more people, so it stays understaffed. I don’t know what other outcome could be expected. It takes nothing to staff more contributors to the core team except relinquishing control that we were given by the luck of the draw.

    As you mentioned, Dhall took a different approach. Dhall hasn’t collapsed under its own weight, and it’s probably not going to any time soon. It’s a thriving community because there’s no gate keeping (well, much less). You can also look at things other than languages, like k8s. k8s is a huge project with tons of people contributing to it daily, yet it’s also not collapsed under this model.

The long and short of all this is that I support what you’re saying, so I wanted to say that explicitly. I’m probably not going to fight for change because I don’t have the energy to try and change things anymore.

4 Likes
#8

Ok, yes, I suppose I have to concede that you are right that the understaffing situation is not going to improve with the current model. I think there probably are some people who are deserving of the commit bit to the compiler, as well as some autonomy in directing its development.

If it helps explain my defensiveness, I think (having been burned in the past by allowing myself to be exploited by poorly behaved users) my default response to these kinds of suggestions has been to think “ok, but how are the worst people going to exploit this.” But I am starting to see that this approach is probably not healthy for the community (or, indeed, me).

Decisions are made by one person, basically, assuming they have the support of other people

Do you mean “decisions are made by one person who, in the process of making the decision, makes the assumption that they have the support of other people”, or “decisions are made by one person provided that others support them”?

There’s no rhyme or reason to core membership.

Alex, Jordan, and @f-f are all doing really fantastic work, but as @natefaubion said, core team membership is predicated on compiler contributions; my impression (happy to be corrected here) is that their work hasn’t really involved much contribution to the compiler, and therefore not being on the core team has not really gotten in the way of what it is they have been working on, until just now, with the situation @f-f described.

In your case @joneshf, I don’t know the circumstances of you being added, as (if I remember correctly) it happened before I became involved with PureScript. The reason you are still on it is because currently the only way someone leaves the core team is by them deciding to do so (as Phil did a while ago).

I am not keen on “responding to PRs in a timely manner” being a prerequisite for core team membership, by the way; that would probably disqualify all of us based on past performance, and it would definitely stress me out to the extent that I would probably end up stepping down voluntarily anyway.

1 Like
#9

Under a less-than-careful (less-than-charitable?) reading of this, I worry that there is political implication here (strong-arming, stonewalling, dictatorial, etc.). I don’t think that was your intent. I would just like to clarify that it has not been the case in my personal experience as a maintainer so far. Actions are taken on by those with the motivation to do so, and I am not aware of a situation where something was done despite reservations just because someone “gave up”. I understand the frustration here, but I believe everyone has been genuinely open to the concerns and voices of other maintainers.

#10

@joneshf I’d like to express my gratitude for letting all of this out publicly, I really see you.

The first post of this thread was written down and sitting in my browser for three days before I could send it.
I was scared that I’d be the troublemaker, an unnecessary source of drama, and I was very close to give up on this as I’ve already seen some people doing.

In the end I allowed myself to post it, and seeing that it allowed you to let your feelings out - which I imagine would otherwise bitterly sit inside - makes me feel like I did something useful for the community at large in sparking this discussion.

I want all of us to talk about this hard stuff, to reflect as a community, to be transparent about things, because this is how collaboration is best fostered: by communicating as much as possible.

You do not need to put all the energy to change things all by yourself (as I do not need to do that either), we can move things forward all together :slightly_smiling_face:

3 Likes
#11

If a change to the process doesn’t change anything other than making people feel more empowered, that’s a very good outcome and should be enacted.

I’ll note again that I’m not arguing for a specific process here - the process can look like something from “we approve changes that have X thumbs up on github” to “changes need a majority vote of the core team” to “any changes will be decided by our BDFL”. Anything is fine really, as long as it’s written down somewhere.

If changes are “up to the core team”, that’s totally fine! Let’s write that down.

The key point I’m trying to convey here is: the moment you go from “ad-hoc” processes (which are fluid by definition) to “well-defined, documented processes” there will be the need to change these processes sometimes.
If we accept the above sentence, then we cannot avoid having a “change management process” too.

As Hardy clearly noted above, at least some part of the core team has suffered from the current approach.

I see you and I just want to let you know that you’re not alone in this, as we’re supposed to help each other move forward as a community :slightly_smiling_face:

Not putting much trust in drive-by-contributors is fairly reasonable, but there should also be a strive to empower and trust regular ones so that they can eventually step up and help out with all of these worries!

It looks to me that the whole discussion here is hinting at the need for a separation between:

  • a “compiler team”: people that commit to the compiler, guide language evolution, and for which membership would be predicated by compiler contributions
  • and a “core team”: people involved with core libraries, packaging infrastructure, package managers, websites, documentation, etc, and for which membership would be predicated on merits for the things listed (i.e. “everything else community”)

I have the feeling that adopting such an arrangement could have a bunch of nice side effects:

  • separation of concerns: the two teams could have different processes and structure
  • the compiler would move at the speed that the “compiler team” would consider appropriate, and the “core team” would not be involved in this
  • there could be different processes to staff the two teams, making it easier to distribute responsibilities, etc.
  • …and last but not least: getting the ecosystem ready for a 1.0 version
3 Likes
#12

I’ve been following this thread and having been thinking about what I could say in this situation. I’m still thinking about it, so for now, I thought I’d just respond to @joneshf’s comment

There’s a few reasons for that:

  1. No one’s asked me to be a part of the core team
  2. I haven’t asked anyone whether I could be a part of the core team
  3. As @hdgarrood pointed out above, I don’t need to be a part of the “core team” (or maybe “compiler team” …?) to still document things. My only contribution to the language was adding the docs for the Prim modules (or something like that).

Related to joneshf’s comment, I also don’t feel like I’m qualified to approve changes on PRs, much less merge things. There’s a lot about compilers, languages, and general type theory that I likely do not know. In short, I understand Harry’s concern about not just letting anyone have write access to the language repo.

#13

There’s a lot to discuss in this thread, so apologies for skipping over most of it with this post, just wanted to chime in on two things quickly:

It looks to me that the whole discussion here is hinting at the need for a separation between: …

I think there’s something to be said for having more possible roles under purescript, but splitting the core library and compiler teams is something I’d have reservations about. Despite there being no implicit prelude or anything, the core libraries are quite closely linked to the language in my mind at least. We went through several releases where we did a poor job of making a coordinated release of libraries along with the compiler, and it was pretty disastrous.

…and last but not least: getting the ecosystem ready for a 1.0 version

I’d like to ask everyone that we don’t discuss this any further in this thread. There’s plenty to talk about, but it could completely hijack the main discussion in here, so if anyone wants to talk more about it now, let’s start a new thread for it.

#14

Sorry @joneshf, I didn’t realise how frustrated with it you were. I appreciated your efforts on starting discussions about many of these things, even though they all stalled.

I think one of the reasons these efforts went nowhere is that in the current core team none of us are leader types, we’re basically all just in here as we were early enthusiasts of the language, and governance/process stuff requires someone to kinda take charge briefly even if it’s just to codify the ad-hoc way we’ve been doing things. So when you posed questions about how we do/should do things you never got clear answers as we’re mostly just, like, whatever maaan.

Maybe I’m speaking out of turn for the other core members here, so if any of you disagree, apologies. I’m definitely this way at least. And not from indifference, more that I don’t feel qualified to provide authoritative answers or take a lead on any of this as I have little experience in being in this kind of position.

I’m also fine with having more of the core team chat public. There’s almost nothing said in the private channel that needs to be kept private - it’s predominantly rubber ducking/discussing specific compiler issues or coordinating releases, just things that might get disrupted in the flow of the normal discussion channels. Maybe we could move more of the technical stuff back to GH issues, and for things where we don’t want interruption, use issues that are locked to members, as at least people can read them then.

2 Likes
#15

Sorry for not making this clearer, but I imagined we’d have an overlap between the two sets, exactly to avoid having the concern you’re pointing out here

#16

It seems like we are all basically in agreement, at least in terms of what the next steps should be:

  • Create a purescript/governance repo, where we can start opening issues and PRs to flesh out all of these things in more detail
  • Move the spago repo back to the purescript org, and add @f-f as an org member
  • Within the core team: start thinking about inviting more people to the core team (while we want most of these governance discussions to be in the open, I think the ‘should we invite this person’ discussions should probably stay private, at least for now)

Does that sound reasonable to everyone? Have I missed anything?

3 Likes
#17

I’ve created the governance repo with the initial draft I had written. https://github.com/purescript/governance

5 Likes
#18

Any news on this? I wanted to cut a new release, but moving the repo back and forth somehow really messed up the CI setup - i.e. I don’t think I’d be able to release without spending more time on fixing CI - so I’d like to have the repo in its final location before trying to fix CI again

#19

@f-f ah yes sorry, how about this: I’ll add you as an org admin again, you move the repo across and get everything set up, and then change your status to a regular org member?

1 Like
#20

Sounds great, let’s go with this :+1: