Merge pull request #405 from r-world-devs/371-bump-version-to-200

Bump version, update NEWS, remove docs folder.

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: GitStats
 Title: Get Statistics from GitHub and GitLab
-Version: 1.1.0.9008
+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"),

NEWS.md

@@ -1,4 +1,6 @@
-# GitStats (development version)
+# 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:
 
@@ -8,29 +10,25 @@
 
 - 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 `use_storage` parameter in the function. ([#333](https://github.com/r-world-devs/GitStats/issues/333))
+- 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 parameters have been introduced for limiting messages to user when pulling data (`verbose`) - these parameters can be set in all `get_*()` functions. You can also turn the verbose mode on/off globally with `verbose_on()`/`verbose_off()` functions.
+- `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:
 
-- Along with that changes `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.
+- `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.
-
-## Minor features:
-
 - 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)).
 

R/GitStats.R

@@ -59,7 +59,8 @@ GitStats <- R6::R6Class("GitStats",
     #'   information to repositories.
     #' @param with_code A character, if  defined, GitStats will pull repositories
     #'   with specified text in code blobs.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_repos = function(add_contributors = FALSE,
@@ -94,7 +95,8 @@ GitStats <- R6::R6Class("GitStats",
     #' @description A method to get information on commits.
     #' @param since A starting date for commits.
     #' @param until An end date for commits.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_commits = function(since,
@@ -155,7 +157,8 @@ GitStats <- R6::R6Class("GitStats",
 
     #' @description Get information on users.
     #' @param logins Character vector of logins.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_users = function(logins, cache = TRUE, verbose = TRUE) {
@@ -180,7 +183,8 @@ GitStats <- R6::R6Class("GitStats",
 
     #' @description Pull text content of a file from all repositories.
     #' @param file_path A file path, may be a character vector.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_files = function(file_path, cache = TRUE, verbose = TRUE) {
@@ -209,7 +213,8 @@ GitStats <- R6::R6Class("GitStats",
     #' @description Get release logs of repositories.
     #' @param since A starting date for release logs.
     #' @param until An end date for release logs.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_release_logs = function(since,
@@ -245,7 +250,8 @@ GitStats <- R6::R6Class("GitStats",
     #' @param package_name A character, name of the package.
     #' @param only_loading A boolean, if `TRUE` function will check only if
     #'   package is loaded in repositories, not used as dependencies.
-    #' @param cache A logical, if `TRUE`, cached results will be used.
+    #' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+    #'   result from its storage.
     #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
     #'   printing output is switched off.
     get_R_package_usage = function(package_name,

R/gitstats_functions.R

@@ -97,23 +97,24 @@ set_gitlab_host <- function(gitstats_object,
 #'   additional information.
 #' @param with_code A character, if  defined, GitStats will pull repositories
 #'   with specified text in code blobs.
-#' @param cache A logical, if `TRUE`, cached results will be used.
-#' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
-#'   printing output is switched off.
+#' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+#'   result from its storage.
+#' @param verbose A logical, `TRUE` by default. If `FALSE` messages and printing
+#'   output is switched off.
 #' @examples
 #' \dontrun{
 #' my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
 #'     orgs = c("r-world-devs", "openpharma")
 #'   ) %>%
-#'   set_host(
-#'     api_url = "https://gitlab.com/api/v4",
+#'   set_gitlab_host(
 #'     token = Sys.getenv("GITLAB_PAT_PUBLIC"),
 #'     orgs = "mbtests"
 #'   )
-#'   get_repos(my_gitstats)
+#' get_repos(my_gitstats)
+#' get_repos(my_gitstats, add_contributors = FALSE)
+#' get_repos(my_gitstats, with_code = "Shiny")
 #' }
 #' @export
 get_repos <- function(gitstats_object,
@@ -136,24 +137,23 @@ get_repos <- function(gitstats_object,
 #' @param gitstats_object A GitStats object.
 #' @param since A starting date.
 #' @param until An end date.
-#' @param cache A logical, if `TRUE`, cached results will be used.
+#' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+#'   result from its storage.
 #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
 #'   printing output is switched off.
 #' @return A `GitStats` class object with commits table.
 #' @examples
 #' \dontrun{
 #' my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
-#'     orgs = c("r-world-devs")
+#'     repos = c("openpharma/DataFakeR", "openpharma/visR")
 #'   ) %>%
-#'   set_host(
-#'     api_url = "https://gitlab.com/api/v4",
+#'   set_gitlab_host(
 #'     token = Sys.getenv("GITLAB_PAT_PUBLIC"),
 #'     orgs = "mbtests"
-#'   ) %>%
-#'   get_commits(since = "2018-01-01")
+#'   )
+#'  get_commits(my_gitstats, since = "2018-01-01")
 #' }
 #' @export
 get_commits <- function(gitstats_object,
@@ -175,9 +175,22 @@ get_commits <- function(gitstats_object,
 #' @title Get statistics on commits
 #' @name get_commits_stats
 #' @description Prepare statistics from the pulled commits data.
+#' @details To make function work, you need first to get commits data with
+#'   `GitStats`. See examples section.
 #' @param gitstats_object A GitStats class object.
-#' @param time_interval A character, specifying time interval to show statistics.
+#' @param time_interval A character, specifying time interval to show
+#'   statistics.
 #' @return A table of `commits_stats` class.
+#' @examples
+#' \dontrun{
+#'  my_gitstats <- create_gitstats() %>%
+#'    set_github_host(
+#'      token = Sys.getenv("GITHUB_PAT"),
+#'      repos = c("r-world-devs/GitStats", "openpharma/visR")
+#'    )
+#'  get_commits(my_gitstats, since = "2022-01-01")
+#'  get_commits_stats(my_gitstats, time_interval = "week")
+#' }
 #' @export
 get_commits_stats = function(gitstats_object,
                              time_interval = c("month", "day", "week")) {
@@ -191,23 +204,22 @@ get_commits_stats = function(gitstats_object,
 #' @description Pull users data from Git Host.
 #' @param gitstats_object A GitStats object.
 #' @param logins A character vector of logins.
-#' @param cache A logical, if `TRUE`, cached results will be used.
+#' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+#'   result from its storage.
 #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
 #'   printing output is switched off.
 #' @examples
 #' \dontrun{
 #'  my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
 #'     orgs = c("r-world-devs")
 #'   ) %>%
-#'   set_host(
-#'     api_url = "https://gitlab.com/api/v4",
+#'   set_gitlab_host(
 #'     token = Sys.getenv("GITLAB_PAT_PUBLIC"),
 #'     orgs = "mbtests"
 #'   )
-#'   get_users(my_gitstats, c("maciekabanas", "marcinkowskak"))
+#'  get_users(my_gitstats, c("maciekabanas", "marcinkowskak"))
 #' }
 #' @return A `GitStats` object with table of users.
 #' @export
@@ -228,23 +240,22 @@ get_users <- function(gitstats_object,
 #' @param gitstats_object A GitStats object.
 #' @param file_path A standardized path to file(s) in repositories. May be a
 #'   character vector if multiple files are to be pulled.
-#' @param cache A logical, if `TRUE`, cached results will be used.
+#' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+#'   result from its storage.
 #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
 #'   printing output is switched off.
 #' @examples
 #' \dontrun{
 #'  my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
 #'     orgs = c("r-world-devs")
 #'   ) %>%
-#'   set_host(
-#'     api_url = "https://gitlab.com/api/v4",
+#'   set_gitlab_host(
 #'     token = Sys.getenv("GITLAB_PAT_PUBLIC"),
 #'     orgs = "mbtests"
 #'   )
-#'   get_files(my_gitstats, "meta_data.yaml")
+#'  get_files(my_gitstats, c("LICENSE", "DESCRIPTION"))
 #' }
 #' @return A `GitStats` object with table of files.
 #' @export
@@ -268,19 +279,20 @@ get_files <- function(gitstats_object,
 #' @param package_name A character, name of the package.
 #' @param only_loading A boolean, if `TRUE` function will check only if package
 #'   is loaded in repositories, not used as dependencies.
-#' @param cache A logical, if `TRUE`, cached results will be used.
+#' @param cache A logical, if set to `TRUE` GitStats will retrieve the last
+#'   result from its storage.
 #' @param verbose A logical, `TRUE` by default. If `FALSE` messages and
 #'   printing output is switched off.
 #' @return A table of repositories content.
 #' @examples
 #' \dontrun{
 #'  my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
 #'     orgs = c("r-world-devs", "openpharma")
-#'   ) %>%
-#'   get_R_package_usage("Shiny")
+#'   )
+#'
+#'  get_R_package_usage(my_gitstats, "Shiny")
 #' }
 #' @export
 get_R_package_usage <- function(
@@ -306,8 +318,7 @@ get_R_package_usage <- function(
 #' @examples
 #' \dontrun{
 #'  my_gitstats <- create_gitstats() %>%
-#'   set_host(
-#'     api_url = "https://api.github.com",
+#'   set_github_host(
 #'     token = Sys.getenv("GITHUB_PAT"),
 #'     orgs = c("r-world-devs", "openpharma")
 #'   )

README.Rmd

@@ -50,5 +50,5 @@ On how to use GitStats, refer to the [documentation](https://r-world-devs.github
 
 ## Acknowledgement
 
-Special thanks to [James Black](https://github.com/epijim), [Kamil Koziej](https://github.com/Cotau), [Karolina Marcinkowska](https://github.com/marcinkowskak), [Krystian Igras](https://github.com/krystian8207), [Matt Secrest](https://github.com/mattsecrest), [Kamil Wais](https://github.com/kalimu), [Adam Forys](https://github.com/galachad) - for the support in the package development.
+Special thanks to [James Black](https://github.com/epijim), [Karolina Marcinkowska](https://github.com/marcinkowskak), [Kamil Koziej](https://github.com/Cotau), [Matt Secrest](https://github.com/mattsecrest), [Krystian Igras](https://github.com/krystian8207), [Kamil Wais](https://github.com/kalimu), [Adam Forys](https://github.com/galachad) - for the support in the package development.
 

README.md

@@ -46,11 +46,11 @@ On how to use GitStats, refer to the
 
 ## Acknowledgement
 
-Special thanks to [James Black](https://github.com/epijim), [Kamil
-Koziej](https://github.com/Cotau), [Karolina
-Marcinkowska](https://github.com/marcinkowskak), [Krystian
-Igras](https://github.com/krystian8207), [Matt
-Secrest](https://github.com/mattsecrest), [Kamil
+Special thanks to [James Black](https://github.com/epijim), [Karolina
+Marcinkowska](https://github.com/marcinkowskak), [Kamil
+Koziej](https://github.com/Cotau), [Matt
+Secrest](https://github.com/mattsecrest), [Krystian
+Igras](https://github.com/krystian8207), [Kamil
 Wais](https://github.com/kalimu), [Adam
 Forys](https://github.com/galachad) - for the support in the package
 development.