Merge pull request #406 from r-world-devs/devel

Release 2.0.0

.Rbuildignore

@@ -11,4 +11,4 @@
 ^_pkgdown\.yml$
 ^docs$
 ^pkgdown$
-^meta_data.yaml
+^project_metadata.yaml

.gitignore

@@ -2,6 +2,6 @@
 .Rhistory
 .RData
 .Ruserdata
-example_workflow_Roche.R
-example_branch.R
+devel
 inst/doc
+docs/

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: GitStats
 Title: Get Statistics from GitHub and GitLab
-Version: 1.1.0
+Version: 2.0.0
 Authors@R: c(
     person(given = "Maciej", family = "Banas", email = "[email protected]", role = c("aut", "cre")),
     person(given = "Kamil", family = "Koziej", email = "[email protected]", role = "aut"),
@@ -13,16 +13,16 @@ Description: Obtain statistics in a standardized way from multiple Git services:
 License: MIT + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE, r6 = TRUE)
-RoxygenNote: 7.1.2
+RoxygenNote: 7.3.1
+URL: https://r-world-devs.github.io/GitStats/, https://github.com/r-world-devs/GitStats
+BugReports: https://github.com/r-world-devs/GitStats/issues
 Imports:
     cli,
-    data.table,
     dplyr,
-    ggplot2,
+    glue,
     httr2,
     lubridate,
     magrittr,
-    plotly,
     rlang (>= 1.1.0),
     R6,
     purrr (>= 1.0.0),

NAMESPACE

@@ -1,29 +1,19 @@
 # Generated by roxygen2: do not edit by hand
 
-S3method(gitstats_plot,commits_stats)
-S3method(gitstats_plot,repos_stats)
 export("%>%")
 export(create_gitstats)
 export(get_R_package_usage)
 export(get_commits)
 export(get_commits_stats)
 export(get_files)
-export(get_orgs)
+export(get_release_logs)
 export(get_repos)
-export(get_repos_stats)
 export(get_users)
-export(gitstats_plot)
-export(pull_R_package_usage)
-export(pull_commits)
-export(pull_files)
-export(pull_repos)
-export(pull_repos_contributors)
-export(pull_users)
-export(reset)
-export(reset_language)
-export(set_host)
-export(set_params)
-export(set_team_member)
+export(set_github_host)
+export(set_gitlab_host)
+export(show_orgs)
+export(verbose_off)
+export(verbose_on)
 importFrom(R6,R6Class)
 importFrom(cli,cli_abort)
 importFrom(cli,cli_alert_danger)
@@ -32,32 +22,24 @@ importFrom(cli,cli_alert_success)
 importFrom(cli,cli_alert_warning)
 importFrom(cli,col_green)
 importFrom(cli,col_yellow)
-importFrom(data.table,as.data.table)
-importFrom(data.table,rbindlist)
-importFrom(data.table,setorder)
 importFrom(dplyr,distinct)
 importFrom(dplyr,filter)
 importFrom(dplyr,glimpse)
 importFrom(dplyr,mutate)
 importFrom(dplyr,relocate)
-importFrom(ggplot2,aes)
-importFrom(ggplot2,geom_line)
-importFrom(ggplot2,geom_point)
-importFrom(ggplot2,ggplot)
+importFrom(glue,glue)
 importFrom(httr2,req_headers)
 importFrom(httr2,req_perform)
 importFrom(httr2,request)
 importFrom(httr2,resp_body_json)
 importFrom(lubridate,floor_date)
 importFrom(magrittr,"%>%")
-importFrom(plotly,ggplotly)
-importFrom(plotly,layout)
 importFrom(purrr,keep)
 importFrom(purrr,map)
 importFrom(purrr,map_chr)
 importFrom(rlang,"%||%")
 importFrom(rlang,expr)
 importFrom(stringr,str_length)
-importFrom(stringr,str_remove_all)
 importFrom(stringr,str_replace)
-importFrom(utils,head)
+importFrom(utils,URLdecode)
+importFrom(utils,URLencode)

NEWS.md

@@ -1,3 +1,42 @@
+# GitStats 2.0.0
+
+This is a major release with general changes in workflow (simplifying it), changes in setting `GitStats` hosts, deprecation of some not very useful features (like plots, setting parameters separately) and new `get_release_logs()` function.
+
+## Setting hosts:
+
+- `set_host()` function is replaced with more explicit `set_github_host()` and `set_gitlab_host()`([#373](https://github.com/r-world-devs/GitStats/issues/373)). If you wish to connect to public host (e.g. `api.github.com`), you do not need to pass argument to `host` parameter. 
+
+## Simplifying workflow:
+
+- GitStats workflow is now simplified. To pull data on `repositories`, `commits`, `R_package_usage` or other you should use directly corresponding `get_*()` functions instead of `pull_*()` which are deprecated. These `get_*()` functions pull data from API, parse it into table, add some goodies (additional columns) if needed and return table instead of `GitStats` object, which in our opinion is more intuitive and user-friendly ([#345]((https://github.com/r-world-devs/GitStats/issues/345))). That means you do not need to run in pipe two or three additional function calls as before, e.g. `pull_repos(gitstats_object) %>% get_repos() %>% get_repos_stats()`, but you just run
+`get_repos(gitstats_object)` to get data you need.
+- Moreover, if you run for the second time `get_*()` function `GitStats` will pull the data from its storage and not from API as for the first time, unless you change parameters for the function (e.g. starting date with `since` in `get_commits()`) or change directly the `cache` parameter in the function. ([#333](https://github.com/r-world-devs/GitStats/issues/333))
+- `pull_repos_contributors()` as a separate function is deprecated. The parameter `add_contributors` is now set by  default to `TRUE` in `get_repos()` which seems more reasonable as user gets all the data.
+- In `get_commits()` old parameters (`date_from` and `date_until`) were replaced with new, more concise (`since` and `until`).
+
+## Changes to setting parameters and pulling repositories by code:
+
+- `set_params()` function is removed. ([#386](https://github.com/r-world-devs/GitStats/issues/386)) Now the logic is moved straight to `get_*()` functions. For example, if you want to pull repositories with specific `code blob`, you do not need to define anything with `set_params()` (as previously with `search_mode` and `phrase` parameter) but you just simply run `get_repos(with_code = 'your_code')`. ([#333](https://github.com/r-world-devs/GitStats/issues/333))
+- New logical parameter `verbose` have been introduced for limiting messages to user when pulling data - this parameter can be set in all `get_*()` functions. You can also turn the verbose mode on/off globally with `verbose_on()`/`verbose_off()` functions.
+
+## Deprecate:
+
+- `get_repos_stats()` function was deprecated as its role was unclear - unlike `get_commit_stats()` it did not aggregate repositories data into new stats table, but added only some new numeric columns, like number of contributors (`contributors_n`) or last activity in `difftime` format, which is now done within `get_repos()` function.
+- Pulling by `team` and filtering by `language` is no longer supported - these features where quite heavy for the package performance and did not bring much added value. If user needs, he can always filter the output (formatted responses pulled from API) by contributors or language. ([#384](https://github.com/r-world-devs/GitStats/issues/384))
+- Plot functions are no longer feature of `GitStats`, they have been deprecated as the package is meant to be basically for back end purposes and this is the field where developer's effort should now go ([#381](https://github.com/r-world-devs/GitStats/issues/381)). If needed and requested, plot functions may be brought up once more in next releases.
+
+## New features:
+
+- Added `get_release_logs()` ([#356](https://github.com/r-world-devs/GitStats/issues/356)).
+- `get_orgs()` is renamed to `show_orgs()` to reflect that it does not pull data from API, but only shows what is in `GitStats` object.
+- Commits response consists now of two new columns: `author_login` and `author_name` ([#332](https://github.com/r-world-devs/GitStats/issues/332)). This is due to the mix of GitHub/GitLab handles and display names in the `author` column (the original author `name` field in commits API response).
+- Improve printing `GitStats` object - now when you return `GitStats` object in console, it prints `GitStats` data divided into sections to give more readable information to user: `scanning scope` (organizations and repositories), and `storage` (the output tables stored in `GitStats` with basic information on dimensions) ([#329](https://github.com/r-world-devs/GitStats/issues/329)).
+
+## Bug fixes:
+
+- Pagination was introduced to `contributors` response ([#331](https://github.com/r-world-devs/GitStats/issues/331)).
+- Fixed handler of dates parameters when pulling commits. Wrong and complex construction of `gts_to_posixt()` helper which took dependencies on `stringr` was a cause for some users of passing empty value to `since` parameter to commits endpoint which ended in Bad Request Error (400) and infinite loop of retrying the response ([#360](https://github.com/r-world-devs/GitStats/issues/360)).
+
 # GitStats 1.1.0
 
 ## New features:

R/Engine.R

@@ -0,0 +1,22 @@
+#' @noRd
+#' @description A superclass for API connections.
+Engine <- R6::R6Class("Engine",
+  private = list(
+    # A token authorizing access to API.
+    token = NULL,
+
+    # Is scanning whole git platform switched on?
+    scan_all = FALSE,
+
+    # Engine type.
+    engine = NULL,
+
+    # Print messages or not.
+    verbose = TRUE,
+
+    # Set verbose mode
+    set_verbose = function(verbose) {
+      private$verbose <- verbose
+    }
+  )
+)

R/EngineGraphQL.R

@@ -1,9 +1,8 @@
 #' @noRd
-#' @importFrom dplyr distinct mutate relocate filter
-#'
-#' @title A EngineGraphQL class
 #' @description A class for methods wrapping GitHub's GraphQL API responses.
 EngineGraphQL <- R6::R6Class("EngineGraphQL",
+   inherit = Engine,
+
    public = list(
 
      #' @field gql_api_url A character, url of GraphQL API.
@@ -12,22 +11,17 @@ EngineGraphQL <- R6::R6Class("EngineGraphQL",
      #' @field gql_query An environment for GraphQL queries.
      gql_query = NULL,
 
-     #' @description Create `EngineGraphQL` object.
-     #' @param gql_api_url GraphQL API url.
-     #' @param token A token.
-     #' @param scan_all A boolean.
+     #' Create `EngineGraphQL` object.
      initialize = function(gql_api_url = NA,
                            token = NA,
                            scan_all = FALSE) {
+       private$engine <- "graphql"
        self$gql_api_url <- gql_api_url
        private$token <- token
        private$scan_all <- scan_all
      },
 
-     #' @description Wrapper of GraphQL API request and response.
-     #' @param gql_query A string with GraphQL query.
-     #' @param vars A list of named variables.
-     #' @return A list.
+     #' Wrapper of GraphQL API request and response.
      gql_response = function(gql_query, vars = "null") {
        response <- private$perform_request(
          gql_query = gql_query,
@@ -37,72 +31,32 @@ EngineGraphQL <- R6::R6Class("EngineGraphQL",
        return(response_list)
      },
 
-     #' @description Get information on users in the form of table
-     #' @param users A character vector of users
-     #' @return A table
-     pull_users = function(users) {
-       purrr::map(users, function(user) {
-         private$pull_user(username = user) %>%
-           private$prepare_user_table()
-       }) %>%
-         purrr::list_rbind()
-     },
-
-     #' @description A method to retrieve given files from all repositories for
-     #'   an organization in a table format.
-     #' @param org An organization.
-     #' @param file_path A file path.
-     #' @param pulled_repos Optional parameter to pass repository output object.
-     #' @param settings A list of  `GitStats` settings.
-     #' @return A table.
-     pull_files = function(org, file_path, pulled_repos = NULL) {
-       if (!private$scan_all) {
-         cli::cli_alert_info("[Engine:{cli::col_yellow('GraphQL')}][org:{org}] Pulling {file_path} files...")
-       }
-       files_table <- private$pull_file_from_org(
-         org = org,
-         file_path = file_path,
-         pulled_repos = pulled_repos
-       ) %>%
-         private$prepare_files_table(
-           org = org,
-           file_path = file_path
+     # A method to pull information on user.
+     pull_user = function(username) {
+       response <- tryCatch({
+         self$gql_response(
+           gql_query = self$gql_query$user(),
+           vars = list("user" = username)
          )
-       return(files_table)
+       }, error = function(e) {
+         NULL
+       })
+       return(response)
      }
-
    ),
    private = list(
-     # @field token A token authorizing access to API.
-     token = NULL,
-
-     # @field A boolean.
-     scan_all = FALSE,
 
+     # GraphQL method for pulling response from API
      perform_request = function(gql_query, vars) {
        response <- httr2::request(paste0(self$gql_api_url, "?")) %>%
          httr2::req_headers("Authorization" = paste0("Bearer ", private$token)) %>%
          httr2::req_body_json(list(query = gql_query, variables = vars)) %>%
          httr2::req_retry(
-           is_transient = ~ httr2::resp_status(.x) == "400|502",
+           is_transient = ~ httr2::resp_status(.x) %in% c(400, 500, 502),
            max_seconds = 60
          ) %>%
          httr2::req_perform()
        return(response)
-     },
-
-     # @description A method to pull information on user.
-     # @param username A login.
-     # @return A user response.
-     pull_user = function(username) {
-       response <- NULL
-       try(
-         response <- self$gql_response(
-           gql_query = self$gql_query$user(),
-           vars = list("user" = username)
-         )
-       )
-       return(response)
      }
    )
 )