search

fairlearn / fairlearn-proposals

Proposal Documents for Fairlearn
MIT License
9 stars 6 forks source link

Why is there a seperate repo for proposals? #10

Closed koaning closed 4 years ago

koaning commented 4 years ago

There's probably a good reason, but why is there a seperate repo for proposals? Doesn't the original issues tab on the main repo suffice?

MiroDudik commented 4 years ago

We tried to have some of the high-level discussions in issues, but things got unwieldy, see: #3 (that issue was moved from the original repo into this one).

The thinking is that when you iterate on an API proposal it is good to have a document where you can comment on different aspects of it. I suspect it's the same reason why there is https://github.com/scikit-learn/enhancement_proposals .

koaning commented 4 years ago

Ah, I think I'm starting to realise that the fairlearn project is distributed across the world. Is this accurate?

romanlutz commented 4 years ago

You mean distributed physically or distributed across repositories? We have contributors in Europe and both coasts of the US right now, so I guess that applies, although I don't quite see that as a factor in the decision to have the repo. Repository-wise we're pretty much contained to the main fairlearn repository right now, although performance tests have moved out into their own. Perhaps at some point certain pieces will move to their own repo. But overall I find it useful to have a separate space to think more holistically about design, end-to-end workflows, and major changes. GitHub Issues is very much focused on the single thread without allowing for more flexibility, and once it's resolved the issue is hard to find again. With this repository it's easy for contributors to find the design decisions we all agreed on. Does that make sense to you? I'm curious whether there are better approaches.

koaning commented 4 years ago

The risk of having another repo for bigger proposals is that I potentially need to look in two different repositories in order to find an answer to a question. There's a risk of an information split and you could get the same discussion happening in two different places.

It should be said, I've never started a project with many folks on board at the beginning. I've always had the opportunity to start with one/two people so bigger design decisions were always made on a whiteboard. I guess there can be a need for something like slack where you can branch multiple discussions ... but then a slack channel with core maintainers seems more sensible than another github issue list on another repo. It's bound to have the same issues as the original github repo with regards to connunication style with the added drawback of data being in two places.

adrinjalali commented 4 years ago

We've been working with this model (having a separate repo for API design/high level discussions, etc) in sklearn, and since the issues and PRs are usually linked to one another across the two repos (the main code repo and the proposals repo), it's quite easy to navigate between them.

Usually people who are not very involved in the project won't end up on the proposals repo, since most people have a small issue with a part of the code, and for people who are involved with the project, they usually end up knowing where things are.

An important thing in and open source projects to me is to make sure people in different time zones are included in discussions and decision making processes, and that means discussions should be kept asynchronous and people should usually wait for the other time zones to reach their working hours and see what's happening. A real time discussion on a chat channel does not give that opportunity to people across the globe.

There's also the persistence issue with chat conversations and that they get lost and not not indexed by search engines and the same discussions end up happening quite a few times.

koaning commented 4 years ago

@adrinjalali that's certainly a fair point thats a downside of slack.