Improving collaboration

[Evan Czaplicki]

I tend to be more conservative and risk averse on technical stuff, so I tend to be a control freak. Things have gotten complex enough that I cannot fit it all in my brain or react to things at the same rate that they come in. Furthermore, the foundations are solid enough that we collectively know "the right thing" in most cases by now.

So I think two things need to happen.

Testing needs to get better. The big problems with 0.14 were primarily related to cabal. I don't know how to fix cabal-related stuff, but the point is that testing overall needs to improve. Short term, this means nice tests on core repos. Long term, I'd like to be running test for all packages uploaded with elm-package.

I need to be more trusting and encouraging about collaboration. I think people are sort of hesitant to send PRs, and I think my behavior is a part of that. These days, there are many issues where I have little or no competitive advantage. I don't remember the code exactly in most cases anymore. I think a lot of the hardest questions have answers or basic guidelines, and this community knows a ton about how things should look.

So I think the guidelines are sort of like this:

• If it is a bug that does not change any public API
  => you probably know as well as I do, go for it! I think an increasing number of issues fall into this category
  
• If it is an API change to a core library
  => it may be best to do a package like array-extra or elm-html-extra or whatever-extra to build a case for the new functions (usage-examples, users, etc.) Maybe we can have some sort of monthly review window where stuff is considered for inclusion in core libraries. Or maybe there can be some community review process to filter it down. Not sure.
• If it is a language change
  => always should be discussed. In almost all cases it should be rejected, so I don't think it makes sense to do PRs until it is properly planned out and agreed upon. Even after it is implemented, it may still not make it in because it does not feel good. I know I reject most language ideas I have, and I hope I already meet these guidelines.

Laszlo and I discussed some code review rules so we can have a couple collaborators and some sort of checks-and-balances system.

I'm going to try to write up proper guidelines, but I wanted to first tell you the broader intent so you can catch me if I am not living up to these goals.

[Jeff Smits]

Nice to see some concrete guidelines. But they will drown in the mailing list. They should get a more permanent place, and I think the website is probably the best place given that Elm is now divided over many GitHub repos.

Random related thought: I listened to a podcast episode on free software community building yesterday where they mostly talk about a formal contract for the community. Maybe it can give you some inspiration?

--
You received this message because you are subscribed to the Google Groups "Elm Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Laszlo Pandy]

Awesome. It's fun to send pull requests and I will love to see more tests so we will have fewer regressions. 

[Sean Corfield]

On Jan 6, 2015, at 6:31 AM, Jeff Smits <jeff....@gmail.com> wrote:
> Nice to see some concrete guidelines. But they will drown in the mailing list. They should get a more permanent place, and I think the website is probably the best place given that Elm is now divided over many GitHub repos.

Or add them to CONTRIBUTING.md in each repo, worded appropriately for each repo (since elm-compiler will have stricter guidelines than elm/core for example).

Sean Corfield -- (904) 302-SEAN
An Architect's View -- http://corfield.org/

"Perfection is the enemy of the good."
-- Gustave Flaubert, French realist novelist (1821-1880)

[Max Goldstein]

+1 for a periodic review of whatever-extra. It would be good to collaboratively decide what's best, add some tests, and avoid overlap.

Thanks for acknowledging PR slowness. Do you want the community to review PRs and give thumbs up?

[John Mayer]

Is there a list of low-hanging fruit? Evan saying "this is a bite sized task for a first timer" might be helpful.

--

[Janis Voigtländer]

Certainly a good point in time for having a quick look over open PRs is just before a release. Many PRs will be trivial to decide about. For example, given the impending 0.14.1 release, here is a list of PRs I think should be decided about right now:

https://github.com/elm-lang/core/pull/8
https://github.com/elm-lang/core/pull/11
https://github.com/elm-lang/core/pull/46
https://github.com/elm-lang/core/pull/53
https://github.com/elm-lang/core/pull/62
https://github.com/elm-lang/core/pull/72
https://github.com/elm-lang/core/pull/74

Each of these PRs will not take more than two minutes to decide about:

a) just accept it

b) reject it and thus clean out the PR queue

c) write one sentence informing the PR's author about why this is not accepted at the moment

Some of the above PRs simply aim to improve documentation, which will immediately benefit users of the standard lib. Two of the above PRs correct user-facing bugs in standard library functions. (For example, Mouse.y currently returns the x-position of the mouse pointer, instead of the y-position.) Certainly, at least these should be incorporated before releasing a new version?

2015-01-07 0:37 GMT+01:00 Max Goldstein <maxgol...@gmail.com>:

+1 for a periodic review of whatever-extra. It would be good to collaboratively decide what's best, add some tests, and avoid overlap.

Thanks for acknowledging PR slowness. Do you want the community to review PRs and give thumbs up?

--

[Evan Czaplicki]

Is there a list of low-hanging fruit? Evan saying "this is a bite sized task for a first timer" might be helpful.

I know this as well as everyone else, don't block on me!

Thanks for making a list of stuff Janis, that was super helpful. All of them should be resolved or addressed.

Max, yeah, Laszlo and I were talking about having a review process in which all changes come in via PRs and need to get a LGTM from a trusted reviewer who can merge stuff. No one should get through without a review, including me. I think we need to develop proper guidelines for reviews (PRs are minimal, code guidelines for JS/Haskell/Elm, etc.), but it seems that this is a good route to scaling to deal with more volume of issues and PRs.

[Peter Damoc]

I remember something I heard in the SICP lectures: "computer science is all about techniques for controlling the complexity". 

I guess it would be amazing if a language for these techniques could be created so that people can express their intent in a more precise manner. 

Guidelines, like the ones proposed by Evan, fall into the category of techniques but it would be lovely if the elm community can come up with other techniques. 

I would love to see guidelines for reporting something broken. Like easy categories of the kind of broken. 
e.g. the elm-lang.org is broken because the top navigation links do not behave like links (they don't change the mouse cursor)
Reporting broken stuff is a wonderful gateway for turning a curious person into a contributor. If the experience is crafted to be wonderful, this community could benefit a lot.

On Tue, Jan 6, 2015 at 3:16 PM, Evan Czaplicki <eva...@gmail.com> wrote:

--

You received this message because you are subscribed to the Google Groups "Elm Discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to elm-discuss...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

There is NO FATE, we are the creators.
blog: http://damoc.ro/

[Peter Damoc]

On Tue, Jan 6, 2015 at 3:31 PM, Jeff Smits <jeff....@gmail.com> wrote:

Nice to see some concrete guidelines. But they will drown in the mailing list. They should get a more permanent place, and I think the website is probably the best place given that Elm is now divided over many GitHub repos.

A wiki might be more appropriate for this. 

[Joey Eremondi]

For me, two things would be very helpful for collaboration:

1. A mailing list called elm-announce, where I can announce every release of my libraries. Right now I'm at the point where I feel like if I posted every bugfix it would clutter the mailing list way too much.

2. A list/section/forum where I can discuss works-in-progress, both for compiler internals and libraries. For example, right now I'm working on changing the compiler internals to allow for AST annotations and, eventually, optimizations. It's far from being done, and even when it is, it's way too major of a change to just submit as a PR. It would be nice to have a place where I can post partial work, ask for advice, get opinions on which approach to take, etc.

As you can see, most of my hesitations are from fear of cluttering the mailing list, so I think having more clearly defined guidelines as for what to discuss where would be good. Both of these things I could do with the current list structure, but I feel like it would be too mundane and make the list too cluttered, especially if others started doing it too.

[Evan Czaplicki]

Okay, I just started two mailing lists: elm-announce and elm-dev. The latter is for talking about nitty-gritty details.

I also created a CONTRIBUTING.md for the core libraries that has the general guidelines. I think the ground rules are a good first pass over PRs that we can all apply. Hopefully that'll be enough for an LGTM on most PRs.

--

[Evan Czaplicki]

I think it'd be good to have better guidelines on issues as well. I don't know how to do that. Right now, problems include:

• Issues get duplicated across elm-compiler, elm-reactor, elm-make, and elm-lang.org depending on where people see it first. It's hard to keep track of this and close stuff appropriately.
  
• People open issues like "broken link in this file" when it'd be roughly the same amount of work to replace it with the correct URL and send a PR. These are hard because it sounds trivial to fix, but context switching a brain is very expensive. Not sure what strategy to use here.
• Examples of problems that are not minimal. Like, a link to a github repo or a 100 line chunk of code.

What are strategies to make these better?

[Jeff Smits]

I think these are problems that will always continue, and minimising them would require a GitHub feature for issues like the one for PRs with Contributing.md.

You can always give feedback through comments on the issue. Things like:

• This is how you recognise that it's a compiler issue, please copy your issue to there. I'm closing this one.
  
• I fixed the broken link, but next time please go ahead and make the change yourself. Small changes like that are much appreciated! It's easier to check such a PR and merge it than to read an issue and do the small change myself. You already know where the problem lies, so don't be afraid to fix it yourself.
• Can you minimise your example? This is too much code.
  

[Jeff Smits]

Great! So elm-announce is only for announcements and not for discussion? How would you do an announcement like the new installers, given that you ask for feedback right now? Is elm-announce more for public announcements than testing alpha stuff?

On Thu, Jan 8, 2015 at 11:14 AM, Evan Czaplicki <eva...@gmail.com> wrote:

[Evan Czaplicki]

Part of what I'm trying to say here is, you can say these things too. I am having a hard time, and these are things that we can all help with.

On the first one, it's not as easy as you make it sound. It's not always clear where the issue should be until you look into it more. But yeah, that seems like the right strategy once you know the real problem. I could imagine doing a "close the issue, open a new one that summarizes it more concisely."

Big picture though, to scale, I can't be the only one doing these things

[Evan Czaplicki]

Great! So elm-announce is only for announcements and not for discussion? How would you do an announcement like the new installers, given that you ask for feedback right now? Is elm-announce more for public announcements than testing alpha stuff?

Ask Joey and the others who asked for this.

My understanding is that it's for package releases, but it does not really fit a use case I have. I still need to announce installers on the list so that as many people as possible see it and try it out.

[Jeff Smits]

On Thu, Jan 8, 2015 at 11:50 AM, Evan Czaplicki <eva...@gmail.com> wrote:

Part of what I'm trying to say here is, you can say these things too. I am having a hard time, and these are things that we can all help with.

I see. That wasn't clear from your earlier posts. Maybe you should create a more general "contributing" page on the elm-lang.org website. It can link to the different GitHub repo Contributing.md documents but also mention the possibility for someone to contribute a few minutes to issue triage. Allow people to become collaborators who agree to only touch issues (You should be able to manage some rights, but it's not possible to force only changing issues). Set up some rules for how to deal with different kinds of issues, set up standard labels over all repositories.

[Mads Flensted-Urech]

About issue handling:

Would it be an idea to have all issues raised on a single repo? Maybe even create a special non-code repo for it? (elm-issues)

You can still link to commits in the other repos:

In pull requests, issues or any comment, sha and issue number (#1 for example) will be automatically linked. Besides, you can link sha or issue number from another repository with the format of user/repo@sha1 or user/repo#1 respectively.

[Sean Corfield]

On Jan 8, 2015, at 12:43 PM, Mads Flensted-Urech <ma...@flensted-urech.dk> wrote:
> Would it be an idea to have all issues raised on a single repo? Maybe even create a special non-code repo for it? (elm-issues)

I’d be strongly against this. Whilst folks may not be certain which repo to open an issue against today, I think that will become much clearer as more people use Elm and we all get used to the structure.

If an issue is opened against the "wrong" repo, a polite note about which repo to use and closing the issue should be fine. That’s what works for other projects.

[Joey Eremondi]

@Evan, I apologize if I was too demanding on this. I had thought that others wanted it too, so I hope I wasn't too pushy.

I'm fine without those ones if we have more clearly defined guidelines for what is and is not appropriate for this list, but I know there were complaints about the volume of the mailing list.

The main use case was to separate internal discussions from "help" questions, and the idea of "Announce" was to post updates for libraries mostly. Is this reasonable?

I'm sorry, now I'm worried I was too demanding about these.

[Sean Corfield]

On Jan 8, 2015, at 3:37 PM, Joey Eremondi <joey.e...@gmail.com> wrote:
> @Evan, I apologize if I was too demanding on this. I had thought that others wanted it too, so I hope I wasn't too pushy.

Just to be clear: I’m strongly against an artificial repo as a central place to log issues (I think it would be a logistical nightmare for tracking fixes).

I _am_ in favor of additional mailing lists as needed to serve different sub-communities. elm-announce, elm-users, elm-discuss would seem like a good first cut:

* elm-announce - low traffic, for announcements about Elm, releases of libraries, and maybe interesting projects built with Elm

* elm-users - discussions about solving problems with Elm etc (probably the majority of what’s currently on elm-discuss these days, now Elm is getting more users)

* elm-discuss - discussions about the design of Elm itself, and its standard libraries - including works in progress / proposed new libraries

Joey, does that cover the areas you were asking for?

(by comparison, Clojure has a public clojure@ list and a closed clojure-dev@ list - the latter is for folks who signed the Contributors’ Agreement and plan to get involved with core/contrib development - announcements are made on the clojure@ list)

[Mads Flensted-Urech]

@Sean: maybe managing issues across the 10 elm-lang repos can also be a "logistical nightmare" ? :-)

I guess it depends on which side you view the problem from, i.e. as an issue-raiser or as an issue-fixer. Again it was just a suggestion.

Maybe it would be enough to be able to have a shared view of the issues raised on all the different elm repos?

As for mailing lists I think 2 would be enough, elm-users and elm-dev. Announcements of packages are in the interest of the users so they could go on the elm-users list. I think the discussions on elm-discuss today benefit from the openness and hence the elm-dev should remain open to all, not just contributors.

[Jeff Smits]

There are interesting upsides to having a single issue repository:

1. There is only one place to file an issue.
2. Evan can assign people rights to that repo so they can triage issues (edit, label, close), without having to give those people write access to any repository.
   
3. It might become the central place to use a GitHub Wiki too.

Downsides I can think of:

1. People will have a harder time finding where to file issues given that normal repos don't allow issues any more. 

@Sean: can you add some concrete downsides to this list?

@Mads: I believe there are some people who expressed a preference for a low-traffic mailing list that keeps them in the loop on significant news. I believe that's what the elm-announce list would be for.

[Mads Flensted-Urech]

@Jeff: yes, and since Evan already set them up, I guess it is just a matter of seeing how they get used and then taking it from there.

[Peter Damoc]

On Fri, Jan 9, 2015 at 11:35 AM, Jeff Smits <jeff....@gmail.com> wrote:

Downsides I can think of:

1. People will have a harder time finding where to file issues given that normal repos don't allow issues any more. 

Is there a rule prohibiting adding a link in the READMEs of the repos to this new repo with a text like "for any issue you might encounter regarding this repo, please use repo X with the tag Y"? :)

[Sean Corfield]

On Jan 9, 2015, at 1:35 AM, Jeff Smits <jeff....@gmail.com> wrote:

Downsides I can think of:

1. People will have a harder time finding where to file issues given that normal repos don't allow issues any more. 

@Sean: can you add some concrete downsides to this list?

Well, pretty much every single project on Github has issues for a given repo actually in that repo and Github is designed to allow you to manage milestones and tags and releases per repo - and issues can be tagged with milestones so you can easily track what issues are targeted for a future release as well as what issues got fixed in a given release (assuming you actually get organized enough to use milestones in the first place and that you tag issues with milestones - two things I’d strongly recommend for ease of collaboration).

And Github has no way to move issues from repo to repo - so if you open issues in the "common" repo, you can’t move them to the repo to which they "belong" and then you can’t take advantage of any of Github’s milestone / release planning stuff.

On the other hand, see this thread for people who have requested this (and two hacks for leveraging the Github API to fake the ability to "move" issues - that create a new issue from the old issue and then close the old issue):

https://github.com/holman/feedback/issues/413

Still, you can turn issues OFF for a repo, so if Elm decided to buck the Github trend and create a central elm-issues repo just for issue management, you could - after migrating issues from the other repos (246 open issues!) - turn off issues on the old repos. However, you can’t turn off Pull Requests and there are 42 open PRs spread across ten repos so folks are still going to be submitting PRs across ten old repos, even if they can only open issues on one new one - which makes it harder still to figure out what’s going on.

Unless you migrate all the open issues from the ten existing repos to the new issue-only repo (manually, one at a time, or write a program to do it), and then turn off issues on those ten repos, you’ll still have folks opening issues everywhere - and even if you do, you’ll still have folks sending PRs to each repo (which some folks do instead of opening an issue).

Overall, I think the lack of ability to leverage Github’s features for milestone planning and the lack of coherence would be big downsides.