Fairly assign home/away matches amongst players

[jarodburchill]

I really like your use of the circle method here, however, when using robin() I found myself wanting to fairly assign "home" matches to players, meaning that in the event of an odd number of players, each player has the same amount of home matches:

// players 1-5 all play 2 home and 2 away matches

// [ away, home ]
[
  [ [ 2, 5 ], [ 3, 4 ] ],
  [ [ 5, 1 ], [ 2, 3 ] ],
  [ [ 1, 4 ], [ 5, 3 ] ],
  [ [ 3, 1 ], [ 4, 2 ] ],
  [ [ 1, 2 ], [ 4, 5 ] ]
]

or in the event of an even number of players, each player has at most 1 more/less home match:

// players 1,3,5 each play 2 home and 3 away matches
// while players 2,4,6 each play 3 home and 2 away matches

// [ away, home ]
[
  [ [ 1, 6 ], [ 2, 5 ], [ 3, 4 ] ],
  [ [ 5, 1 ], [ 6, 4 ], [ 2, 3 ] ],
  [ [ 1, 4 ], [ 5, 3 ], [ 6, 2 ] ],
  [ [ 3, 1 ], [ 4, 2 ], [ 5, 6 ] ],
  [ [ 1, 2 ], [ 3, 6 ], [ 4, 5 ] ]
]

This PR accomplishes this.

This method was also mentioned in the wiki article you referenced in robin.js

The upper and lower rows can indicate home/away in sports, white/black in chess, etc.; to ensure fairness, this must alternate between rounds since competitor 1 is always on the first row.

I also bumped the version to 2.0.0 as some might see this as a breaking change if they for some reason relied on the order of the match arrays (although I doubt it because the [ away, home ] concept is new and I don't see why else the order would matter).

Let me know what you think :)

[clux]

I think this is a great idea, and it's handled very gracefully. I agree that a major is needed (even though the interface itself is unchanged, and the change will likely go under the radar), as it does change determinism of groupstages higher up the stack, so people trying to resume a tournament might be confused.

Will leave a few questions on the PR, but overall the thing looks pretty good right of the bat. Thanks a lot for doing this!

[clux]

questions on order and a seed suggestion

[jarodburchill]

Perhaps we should also update README.md to say that in version 2.0.0 a user can expect fair home/away assignment and also explain the [ away, home ] ordering/reasoning.

[jarodburchill]

Perhaps we should also update README.md to say that in version 2.0.0 a user can expect fair home/away assignment and also explain the [ away, home ] ordering/reasoning.

Done in commit 6d06751.

How does it look?

[clux]

How does it look?

Looks great :-)

As a somewhat amusing sidenote; this will be the second ever update to this library. Last PR was ~7 years ago (issue #1).

[jarodburchill]

As a somewhat amusing sidenote; this will be the second ever update to this library. Last PR was ~7 years ago (issue #1).

Haha, yeah I know this repo is a bit old but while I was working on a React Native side project I needed to lay out teams in a round robin format and I thought I'd see if anyone had done it yet. Turns out you had, I just needed to add home/away support. Figured I'd open a PR rather than just keep the changes to myself :)

[clux]

Definitely appreciated :-)

[clux]

roundrobin@2.0.0 released 🎉