{"id":23398287,"url":"https://github.com/mattruggio/playoffs","last_synced_at":"2025-06-14T08:08:54.601Z","repository":{"id":241283889,"uuid":"798315815","full_name":"mattruggio/playoffs","owner":"mattruggio","description":"Underlying data structures to power a bracket-style tournament of teams/competitors.","archived":false,"fork":false,"pushed_at":"2024-05-23T20:46:03.000Z","size":1104,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-14T08:08:54.276Z","etag":null,"topics":["playoffs","ruby","tournament"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mattruggio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-05-09T14:33:23.000Z","updated_at":"2025-03-30T00:52:29.000Z","dependencies_parsed_at":null,"dependency_job_id":"bcf66460-964a-4d1d-bfd5-7cb1674a8942","html_url":"https://github.com/mattruggio/playoffs","commit_stats":null,"previous_names":["mattruggio/playoffs"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/mattruggio/playoffs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattruggio%2Fplayoffs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattruggio%2Fplayoffs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattruggio%2Fplayoffs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattruggio%2Fplayoffs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mattruggio","download_url":"https://codeload.github.com/mattruggio/playoffs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mattruggio%2Fplayoffs/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259783063,"owners_count":22910300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["playoffs","ruby","tournament"],"created_at":"2024-12-22T09:38:33.626Z","updated_at":"2025-06-14T08:08:54.585Z","avatar_url":"https://github.com/mattruggio.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Playoffs\n\n[![Gem Version](https://badge.fury.io/rb/playoffs.svg)](https://badge.fury.io/rb/playoffs) [![CI](https://github.com/mattruggio/playoffs/actions/workflows/ci.yaml/badge.svg)](https://github.com/mattruggio/playoffs/actions/workflows/ci.yaml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nI was looking to create a turn-based sports game which, inevitably, would include a playoffs simulator. This library provides a few, easy-to-use APIs to create, simulate, and complete a team \u0026 series-based tournament with one clear winner.\n\n### Installation\n\nTo install through Rubygems:\n\n```zsh\ngem install playoffs\n```\n\nYou can also add this to your Gemfile using:\n\n```zsh\nbundle add playoffs\n```\n\nCopy the executables locally:\n\n```zsh\nbundle binstubs playoffs\n```\n\n### CLI Usage\n\nThis library comes with an executable which shows off the basics of consuming the underlying data structures. It is currently limited to supporting NBA-style playoffs (play-in games included). Let's say we are looking to model the 2024 NBA playoffs, we could run these commands to simulate step-by-step:\n\n#### Create New Tournament\n\n```zsh\nbin/playoffs 2024.yaml new BOS,NYK,MIL,CLE,ORL,IND,PHI,MIA,CHI,ATL,OKC,DEN,MIN,LAC,DAL,PHX,LAL,NO,SAC,GS\n```\n\nNote(s):\n\n* This will save a serialized tournament to `2024.yaml`\n* The last argument is a comma-separated list of teams in ranked order per conference.\n\n### View Bracket\n\n```zsh\nbin/playoffs 2024.yaml\n```\n\nThis will output a tree-based text representation:\n\n```zsh\nTBD\n└ BestOf::7::Series::TBD::0::TBD::0\n  ├ BestOf::7::Series::TBD::0::TBD::0\n  │ ├ BestOf::7::Series::TBD::0::TBD::0\n  │ │ ├ BestOf::7::Series::BOS::0::TBD::0\n  │ │ │ └ BestOf::1::Series::TBD::0::TBD::0\n  │ │ │   ├ BestOf::1::Series::PHI::0::MIA::0::LoserAdvances\n  │ │ │   └ BestOf::1::Series::CHI::0::ATL::0\n  │ │ └ BestOf::7::Series::CLE::0::ORL::0\n  │ └ BestOf::7::Series::TBD::0::TBD::0\n  │   ├ BestOf::7::Series::MIL::0::IND::0\n  │   └ BestOf::7::Series::NYK::0::TBD::0\n  │     └ BestOf::1::Series::PHI::0::MIA::0::WinnerAdvances\n  └ BestOf::7::Series::TBD::0::TBD::0\n    ├ BestOf::7::Series::TBD::0::TBD::0\n    │ ├ BestOf::7::Series::OKC::0::TBD::0\n    │ │ └ BestOf::1::Series::TBD::0::TBD::0\n    │ │   ├ BestOf::1::Series::LAL::0::NO::0::LoserAdvances\n    │ │   └ BestOf::1::Series::SAC::0::GS::0::LoserAdvances\n    │ └ BestOf::7::Series::LAC::0::DAL::0\n    └ BestOf::7::Series::TBD::0::TBD::0\n      ├ BestOf::7::Series::MIN::0::PHX::0\n      └ BestOf::7::Series::DEN::0::TBD::0\n        └ BestOf::1::Series::LAL::0::NO::0::WinnerAdvances\n```\n\n### View Rounds\n\n```zsh\nbin/playoffs 2024.yaml rounds\n```\n\nThis will output all series, grouped by round:\n\n```zsh\nBestOf::1::Series::PHI::0::MIA::0\nBestOf::1::Series::CHI::0::ATL::0\nBestOf::1::Series::LAL::0::NO::0\nBestOf::1::Series::SAC::0::GS::0\n\nBestOf::1::Series::TBD::0::TBD::0\nBestOf::1::Series::PHI::0::MIA::0\nBestOf::1::Series::TBD::0::TBD::0\nBestOf::1::Series::LAL::0::NO::0\n\nBestOf::7::Series::BOS::0::TBD::0\nBestOf::7::Series::CLE::0::ORL::0\nBestOf::7::Series::MIL::0::IND::0\nBestOf::7::Series::NYK::0::TBD::0\nBestOf::7::Series::OKC::0::TBD::0\nBestOf::7::Series::LAC::0::DAL::0\nBestOf::7::Series::MIN::0::PHX::0\nBestOf::7::Series::DEN::0::TBD::0\n\nBestOf::7::Series::TBD::0::TBD::0\nBestOf::7::Series::TBD::0::TBD::0\nBestOf::7::Series::TBD::0::TBD::0\nBestOf::7::Series::TBD::0::TBD::0\n\nBestOf::7::Series::TBD::0::TBD::0\nBestOf::7::Series::TBD::0::TBD::0\n\nBestOf::7::Series::TBD::0::TBD::0\n```\n\n#### View Up Next\n\n```zsh\nbin/playoffs 2024.yaml up\n```\n\nThis will output the current round number and series (nothing if the tournament is over):\n\n```zsh\n1\nBestOf::1::Series::PHI::0::MIA::0\n```\n\n#### Log a Win\n\nOnce you know which series is currently up, use this command to pick a winner:\n\n```zsh\nbin/playoffs 2024.yaml win PHI\n```\n\nThis will output the current series after the win:\n\n```zsh\nBestOf::1::Series::PHI::1::MIA::0::Done\n```\n\n#### Simulate\n\nThe CLI example executable comes with a randomized simulator. This is where this library stops and the application should start: the consumer is responsible to actually deciding winners while this library is only focused on providing the state machine. Run this command to simulate the rest of the games and series:\n\n```zsh\nbin/playoffs 2024.yaml sim\n```\n\nThis will output the number of games simulated and the winner:\n\n```zsh\n97\nDAL\n```\n\n#### View Winner\n\n```zsh\nbin/playoffs 2024.yaml winner\n```\n\nWill output the winner (nothing if the tournament is not over):\n\n```zsh\nDAL\n```\n\n### Ruby API Usage\n\nWhile the CLI executable exemplifies building a consumer app using the data structures provided here, the real power is extending yourself to fit your needs, specifically:\n\n1. Subclassing `Playoffs::Team` to customize per your domain-specific needs\n2. Constructing your own tournament using the main `Playoffs::Series` data structure. View `Playoffs::Basketball#tournament_for` to see how an NBA tournament is constructed.\n3. Interact with the tournament state machine directly, such as:\n\n   * `Playoffs::Tournament#up_next`: Get the current series which needs a winner.\n   * `Playoffs::Series#win`: Log a winner for the current series.\n   *  `Playoffs::Tournament#winner`: Get the winning team once there is no current series (series is over).\n\n## Contributing\n\n### Development Environment Configuration\n\nBasic steps to take to get this repository compiling:\n\n1. Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/) (check playoffs.gemspec for versions supported)\n2. Install bundler (gem install bundler)\n3. Clone the repository (git clone git@github.com:mattruggio/playoffs.git)\n4. Navigate to the root folder (cd playoffs)\n5. Install dependencies (bundle)\n\n### Running Tests\n\nTo execute the test suite run:\n\n```zsh\nbin/rspec spec --format documentation\n```\n\nAlternatively, you can have Guard watch for changes:\n\n```zsh\nbin/guard\n```\n\nAlso, do not forget to run Rubocop:\n\n```zsh\nbin/rubocop\n```\n\nAnd auditing the dependencies:\n\n```zsh\nbin/bundler-audit check --update\n```\n\nAnd Sorbet:\n\n```zsh\nbin/srb\n```\n\n### Publishing\n\nNote: ensure you have proper authorization before trying to publish new versions.\n\nAfter code changes have successfully gone through the Pull Request review process then the following steps should be followed for publishing new versions:\n\n1. Merge Pull Request into main\n2. Update `version.rb` using [semantic versioning](https://semver.org/)\n3. Install dependencies: `bundle`\n4. Update `CHANGELOG.md` with release notes\n5. Commit \u0026 push main to remote and ensure CI builds main successfully\n6. Run `bin/rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Code of Conduct\n\nEveryone interacting in this codebase, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mattruggio/playoffs/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThis project is MIT Licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattruggio%2Fplayoffs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmattruggio%2Fplayoffs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmattruggio%2Fplayoffs/lists"}