Skip to content

Add valid year ranges to the docs#127

Open
bradisbrad wants to merge 10 commits into
mainfrom
37-add-valid-year-ranges-to-the-docs
Open

Add valid year ranges to the docs#127
bradisbrad wants to merge 10 commits into
mainfrom
37-add-valid-year-ranges-to-the-docs

Conversation

@bradisbrad

Copy link
Copy Markdown
Contributor

Table of Contents generated with DocToc

Pull Request

Summary

Creates an auto-updater script and an internal dataframe to dynamically surface minimum years for functions that have a year argument.

Type of Change

  • feat: New feature (e.g. new cfbd_*, espn_cfb_*, or load_cfb_* wrapper)
  • fix: Bug fix
  • docs: Documentation only (roxygen, README, NEWS, vignettes)
  • test: Adding or updating tests (includes the pbp equivalence harness)
  • refactor: Code refactoring (no functional change -- e.g. extracting helpers into R/pbp_*.R)
  • chore: Maintenance / tooling (.Rbuildignore, tools/, lockfiles)
  • perf: Performance improvement
  • ci: GitHub Actions / workflow changes

Related Issues

Closes #37

Background & Context

Main thing here is that the script looks for all functions that have a year argument, and sets defaults for week (if required) and ESPN team_id (where necessary) when running the auto-updater. I also make a couple of assumptions on inheritance for ease of use so we don't need to search across time for athlete IDs from previous years to dynamically set defaults for the updater, so these might not be perfect minimums, but certainly a good estimate.

In some cases, we have functions that return results with a year all the way back to 1000. This is partially addressed in #126, but largely what's happening here is ESPN is returning current state but requiring a year to be passed, so I'm allowing those to pass through until we figure out what we want to do about those calls.

Changes Made

  • Adds internal data in sysdata.rda called min_year_map_df, which stores minimum year for a function, a last updated date, and the function that supplies the minimum year, if inherited
  • Adds a script in raw-data/ that works through all functions in the table and updates minimum year
    • Removes raw-data/ from .gitignore (still in .RBuildIgnore)
  • Adds a test for outdated minimum year updates (set to 3 months, can change if y'all want)
  • Adds dynamic documentation for minimum year to all functions that reside in this mapping df

Submission Checklist

  • Code follows tidyverse style (snake_case, 2-space indent, native pipe |>)
  • Return variables are initialized before any tryCatch block (e.g. df_list <- list(), plays_df <- NULL)
  • Column drops use dplyr::select(-dplyr::any_of(...)); renames use dplyr::rename(dplyr::any_of(c(new = "old")))
  • User-facing messages use cli::cli_alert_*() / cli::cli_warn() / cli::cli_abort() (not message() / stop() / warning())
  • devtools::document() has been run (NAMESPACE updated; no hand-edits to man/ or NAMESPACE)
  • New / changed functions have roxygen with @export, @family, @return, and a runnable example (\donttest{} for live-network calls)
  • Tests added / updated in tests/testthat/ with skip_on_cran() + skip_on_ci() and a skip-if-empty guard right after the API call
  • Column assertions use the subset direction: expect_in(sort(expected), sort(colnames(x)))
  • If touching the 2.3.0 PBP pipeline: test-pbp_equivalence.R still passes (or the allow-list is updated with justification)
  • devtools::check() passes with no errors or warnings
  • NEWS.md updated under the current # **cfbfastR 2.3.0** heading (if user-facing)
  • cran-comments.md updated (if behavioural / user-visible)
  • _pkgdown.yml updated for new exports that need an explicit reference entry (the starts_with("cfbd_") / starts_with("espn_cfb_") selectors pick up most prefix-matching additions automatically)
  • README.Rmd re-rendered with devtools::build_readme() if README content changed
  • DESCRIPTION normalized with usethis::use_tidy_description() if it was edited
  • doctoc TOC re-run if any of NEWS.md / CLAUDE.md / CONTRIBUTING.md / .github/copilot-instructions.md / .github/pull_request_template.md changed
  • Commit messages use conventional commit format (type: description); no AI co-authors

Reviewer Checklist

Reviewers: Do not approve until all items are verified

  • Summary clearly explains what this PR does
  • Background & Context provides enough information for someone unfamiliar with the change
  • All changed files are documented with descriptions in the Changes Made table
  • Testing approach is documented and sufficient (offline + live coverage where relevant)
  • Documentation (NEWS.md, cran-comments.md, _pkgdown.yml, roxygen) has been updated or marked N/A with justification
  • Are all items in the PR template completed properly?

Additional Notes

@bradisbrad bradisbrad linked an issue Jul 24, 2026 that may be closed by this pull request
@vercel

vercel Bot commented Jul 24, 2026

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
cfbfastr Ready Ready Preview, Comment Jul 24, 2026 6:27pm

Request Review

@bradisbrad
bradisbrad requested a review from saiemgilani July 24, 2026 18:27

@sourcery-ai sourcery-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry @bradisbrad, your pull request is larger than the review limit of 150000 diff characters

@coderabbitai

coderabbitai Bot commented Jul 24, 2026

Copy link
Copy Markdown
Contributor

Important

Review skipped

Too many files!

This PR contains 169 files, which is 69 over the limit of 100.

To get a review, narrow the scope:
• coderabbit review --committed # exclude uncommitted changes
• coderabbit review --dir # limit to a subdirectory
• coderabbit review --base # compare against a closer base

Upgrade to a paid plan to raise the limit.

This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 76373ffc-a3f2-4ec7-8311-b6ae20f3d373

📥 Commits

Reviewing files that changed from the base of the PR and between f4681d5 and e5efd00.

📒 Files selected for processing (169)
  • .gitignore
  • DESCRIPTION
  • R/cfbd_betting.R
  • R/cfbd_coaches.R
  • R/cfbd_draft.R
  • R/cfbd_drives.R
  • R/cfbd_games.R
  • R/cfbd_metrics.R
  • R/cfbd_pbp_data.R
  • R/cfbd_pbp_data_v2.R
  • R/cfbd_play.R
  • R/cfbd_players.R
  • R/cfbd_ratings.R
  • R/cfbd_recruiting.R
  • R/cfbd_stats.R
  • R/cfbd_teams.R
  • R/espn_cfb_catalog.R
  • R/espn_cfb_player.R
  • R/espn_cfb_ratings.R
  • R/espn_cfb_schedule.R
  • R/espn_cfb_season.R
  • R/espn_cfb_team.R
  • R/pbp_prep_epa_df_after.R
  • R/sysdata.rda
  • data-raw/min_year_map_df.R
  • man/cfbd_betting_ats.Rd
  • man/cfbd_betting_lines.Rd
  • man/cfbd_calendar.Rd
  • man/cfbd_coaches.Rd
  • man/cfbd_draft_picks.Rd
  • man/cfbd_draft_positions.Rd
  • man/cfbd_draft_teams.Rd
  • man/cfbd_drives.Rd
  • man/cfbd_game_box_advanced.Rd
  • man/cfbd_game_info.Rd
  • man/cfbd_game_media.Rd
  • man/cfbd_game_player_stats.Rd
  • man/cfbd_game_records.Rd
  • man/cfbd_game_team_stats.Rd
  • man/cfbd_game_weather.Rd
  • man/cfbd_live_plays.Rd
  • man/cfbd_live_scoreboard.Rd
  • man/cfbd_metrics_fg_ep.Rd
  • man/cfbd_metrics_ppa_games.Rd
  • man/cfbd_metrics_ppa_players_games.Rd
  • man/cfbd_metrics_ppa_players_season.Rd
  • man/cfbd_metrics_ppa_predicted.Rd
  • man/cfbd_metrics_ppa_teams.Rd
  • man/cfbd_metrics_wepa_players_kicking.Rd
  • man/cfbd_metrics_wepa_players_passing.Rd
  • man/cfbd_metrics_wepa_players_rushing.Rd
  • man/cfbd_metrics_wepa_team_season.Rd
  • man/cfbd_metrics_wp.Rd
  • man/cfbd_metrics_wp_pregame.Rd
  • man/cfbd_pbp_data.Rd
  • man/cfbd_pbp_data_v2.Rd
  • man/cfbd_play_stats_player.Rd
  • man/cfbd_play_stats_types.Rd
  • man/cfbd_play_types.Rd
  • man/cfbd_player_info.Rd
  • man/cfbd_player_returning.Rd
  • man/cfbd_player_usage.Rd
  • man/cfbd_plays.Rd
  • man/cfbd_rankings.Rd
  • man/cfbd_ratings_elo.Rd
  • man/cfbd_ratings_fpi.Rd
  • man/cfbd_ratings_sp.Rd
  • man/cfbd_ratings_sp_conference.Rd
  • man/cfbd_ratings_srs.Rd
  • man/cfbd_recruiting_player.Rd
  • man/cfbd_recruiting_position.Rd
  • man/cfbd_recruiting_team.Rd
  • man/cfbd_recruiting_transfer_portal.Rd
  • man/cfbd_stats_categories.Rd
  • man/cfbd_stats_game_advanced.Rd
  • man/cfbd_stats_game_havoc.Rd
  • man/cfbd_stats_season_advanced.Rd
  • man/cfbd_stats_season_player.Rd
  • man/cfbd_stats_season_team.Rd
  • man/cfbd_team_info.Rd
  • man/cfbd_team_matchup.Rd
  • man/cfbd_team_matchup_records.Rd
  • man/cfbd_team_roster.Rd
  • man/cfbd_team_talent.Rd
  • man/cfbfastR-package.Rd
  • man/espn_cfb_award.Rd
  • man/espn_cfb_awards.Rd
  • man/espn_cfb_calendar.Rd
  • man/espn_cfb_clear_cache.Rd
  • man/espn_cfb_coach.Rd
  • man/espn_cfb_coach_record.Rd
  • man/espn_cfb_coaches.Rd
  • man/espn_cfb_franchise.Rd
  • man/espn_cfb_franchises.Rd
  • man/espn_cfb_futures.Rd
  • man/espn_cfb_game_broadcasts.Rd
  • man/espn_cfb_game_drive_plays.Rd
  • man/espn_cfb_game_drives.Rd
  • man/espn_cfb_game_leaders.Rd
  • man/espn_cfb_game_odds.Rd
  • man/espn_cfb_game_pbp.Rd
  • man/espn_cfb_game_play.Rd
  • man/espn_cfb_game_player_box.Rd
  • man/espn_cfb_game_player_statistics.Rd
  • man/espn_cfb_game_powerindex.Rd
  • man/espn_cfb_game_predictor.Rd
  • man/espn_cfb_game_probabilities.Rd
  • man/espn_cfb_game_situation.Rd
  • man/espn_cfb_game_status.Rd
  • man/espn_cfb_game_team_leaders.Rd
  • man/espn_cfb_game_team_linescores.Rd
  • man/espn_cfb_game_team_records.Rd
  • man/espn_cfb_game_team_roster.Rd
  • man/espn_cfb_game_team_statistics.Rd
  • man/espn_cfb_game_teams.Rd
  • man/espn_cfb_groups.Rd
  • man/espn_cfb_pbp_v2.Rd
  • man/espn_cfb_player.Rd
  • man/espn_cfb_player_career_stats.Rd
  • man/espn_cfb_player_eventlog.Rd
  • man/espn_cfb_player_gamelog.Rd
  • man/espn_cfb_player_overview.Rd
  • man/espn_cfb_player_seasons.Rd
  • man/espn_cfb_player_splits.Rd
  • man/espn_cfb_player_stats.Rd
  • man/espn_cfb_player_stats_v3.Rd
  • man/espn_cfb_players.Rd
  • man/espn_cfb_position.Rd
  • man/espn_cfb_positions.Rd
  • man/espn_cfb_powerindex.Rd
  • man/espn_cfb_qbr.Rd
  • man/espn_cfb_rankings.Rd
  • man/espn_cfb_recruits.Rd
  • man/espn_cfb_scoreboard.Rd
  • man/espn_cfb_season_info.Rd
  • man/espn_cfb_season_types.Rd
  • man/espn_cfb_season_weeks.Rd
  • man/espn_cfb_seasons.Rd
  • man/espn_cfb_standings.Rd
  • man/espn_cfb_team.Rd
  • man/espn_cfb_team_ats.Rd
  • man/espn_cfb_team_awards.Rd
  • man/espn_cfb_team_coaches.Rd
  • man/espn_cfb_team_events.Rd
  • man/espn_cfb_team_leaders.Rd
  • man/espn_cfb_team_powerindex.Rd
  • man/espn_cfb_team_ranks.Rd
  • man/espn_cfb_team_record.Rd
  • man/espn_cfb_team_roster.Rd
  • man/espn_cfb_team_schedule.Rd
  • man/espn_cfb_team_stats.Rd
  • man/espn_cfb_teams.Rd
  • man/espn_cfb_unnest_plays.Rd
  • man/espn_cfb_venue.Rd
  • man/espn_cfb_venues.Rd
  • man/espn_cfb_week_rankings.Rd
  • man/espn_ratings_fpi.Rd
  • man/load_cfb_pbp.Rd
  • man/load_cfb_rosters.Rd
  • man/load_cfb_schedules.Rd
  • man/load_cfb_teams.Rd
  • man/update_cfb_db.Rd
  • man/yahoo_cfb_boxscore.Rd
  • man/yahoo_cfb_player_season_stats.Rd
  • man/yahoo_cfb_player_season_stats_legacy.Rd
  • man/yahoo_cfb_scoreboard.Rd
  • man/yahoo_cfb_team_season_stats.Rd
  • man/yahoo_cfb_team_season_stats_legacy.Rd
  • tests/testthat/test-min_year_df.R

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch 37-add-valid-year-ranges-to-the-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@bradisbrad

Copy link
Copy Markdown
Contributor Author

I think these failures are fixed in #126

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add Valid year ranges to the docs

1 participant