En travaillant sur notre package {gitdown}, je voulais montrer plus d’informations sur le rapport généré en récupérant tous les tickets de mes dépôts Gitlab / Github. En effet, ajouter des titres aux numéros d’issues pourrait améliorer la lisibilité et l’information du rapport git de ce package. Comment puis-je télécharger toutes les informations des issues des dépôts git ?
Contexte du développement de {gitdown}
Table des matières
{gitdown} est un package pour créer un rapport HTML à partir de vos commits sur git. Ce package récupère numéros d’issues et autres patterns figurant dans vos messages de commit pour présenter tous les commit liés à chaque pattern. Nous avons créé ce package pour un client d’une entreprise Pharmaceutique qui voulait lier tous nos commit à son propre système de gestion de projet. En effet, en Pharma, chaque modification du logiciel construit doit être documentée. Ici, dans chacun de nos messages de commit, nous avons ajouté une référence à leur système de gestion de projet qui a été utilisé en parallèle de notre procédure de développement Gitlab.
Revenons au sujet de cet article de blog. Ici, je veux télécharger la liste des issues de mon compte Gitlab/Github pour ajouter des informations dans mon livre {gitdown}. Avec cette liste, je pourrai ajouter le titre de l’issue au lieu du seul numéro “#1”, comme dans la figure ci-dessus.
Créer un faux projet git
Pour les besoins des tests et exemples dans le package {gitdown}, la fonction fake_repo() permet de construire un faux projet avec quelques fichiers et commits.
# remotes::install_github("ThinkR-open/gitdown")
library(gitdown)
# Create the repo here
repo <- fake_repo(path = "repo.rtask", as.package = TRUE)
# Content of the repo
fs::dir_tree(repo)## repo.rtask
## ├── NEWS.md
## ├── R
## │ └── my_mean.R
## ├── example.txt
## └── vignettesCe dépôt contient des messages git spécifiques. Vous utilisez peut-être déjà le numéro d’issue pour faire le lien avec vos messages de commit, comme #123 pour un lien avec l’issue 123. Ici, nous avons également ajouté des patterns de texte spécifiques à lier à un système de gestion de projet client, commme ticket123 pour leur ticket interne nommé 123. Vous pouvez voir ces modèles dans le commit suivant.
library(git2r)
summary(last_commit(repo))## Commit: 66aa7a694f28f60888231ee7fb475e6ae27ef025
## Author: Alice <[email protected]>
## When: 2020-08-10 15:11:50 GMT
##
## Add NEWS
##
## issue #32.
## issue #1.
## issue#12
## ticket6789.
## ticket1234
## Creation of the NEWS file for version 0.1.
## 1 file changed, 3 insertions, 0 deletions
## NEWS.md | -0 +3 in 1 hunkDans mon précédent article “Transformer un dossier en projet git synchronisé sur Github ou Gitlab”, j’ai déjà créé deux dépôts distants pour mon projet sur Gitlab (https://gitlab.com/statnmap/repo.rtask) et sur Github (https://github.com/statnmap/repo.rtask).
Dans ces deux dépôts, il y a deux issues.
Télécharger les issues depuis Gitlab
J’utilise {gitlabr} pour télécharger les issues depuis Gitlab. Utilisez dans la branche de développement sur Github si {tibble} est à jour sur votre ordinateur (voir note à la fin de cet article).
remotes::install_github("statnmap/gitlabr")library(gitlabr)
library(dplyr)Connexion à Gitlab depuis R
Vous devrez créer votre jeton d’accès (token). Vous pouvez en générer un dans l’interface web sous “
# Store your token in .Renviron and restart your session
usethis::edit_r_environ()
# Add: GITLAB_COM_TOKEN=YourTokenHere
# You can verify it worked
Sys.getenv("GITLAB_COM_TOKEN")Vous pouvez ensuite vous connecter à votre projet sur Gitlab. L’objet my_project() créé est une fonction permettant de communiquer avec l’API Gitlab, à condition d’utiliser les bonnes fonctions.
Je vous recommande vivement d’utiliser l’ID du projet, sinon la fonction tentera de télécharger l’intégralité du site gitlab.com pour rechercher votre projet. Vous pouvez trouver votre ID de projet dans Gitlab dans les Paramètres généraux.
# Connect as a fixed user to a gitlab instance
my_project <- gl_project_connection(
gitlab_url = "https://gitlab.com",
project = 20384533, #repo.rtask",
private_token = Sys.getenv("GITLAB_COM_TOKEN")
)Télécharger les numéros Gitlab d’un projet spécifique
Nous utilisons gl_list_issues pour récupérer la liste des issues, en utilisant notre connexion. On obtient donc un tableau avec une ligne pour chaque issue sur Gitlab.
my_project_issues <- my_project(gl_list_issues)
my_project_issues## # A tibble: 2 x 32
## <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
## 1 6952… 2 20384533 A se… The blog p… open… 2020-08-0… 2020-08-0… 4809823 Sébastien …
## 2 6952… 1 20384533 An e… No desc in… open… 2020-08-0… 2020-08-0… 4809823 Sébastien …
## # merge_requests_count <chr>, upvotes <chr>, downvotes <chr>, confidential <chr>,
## # web_url <chr>, time_stats.time_estimate <chr>, time_stats.total_time_spent <chr>,
## # task_completion_status.count <chr>, task_completion_status.completed_count <chr>,
## # has_tasks <chr>, `_links.self` <chr>, `_links.notes` <chr>, `_links.award_emoji` <chr>,
## # `_links.project` <chr>, references.short <chr>, references.relative <chr>,
## # references.full <chr>Télécharger les issues de Github
J’utilise {gh} pour télécharger les issues de Github, grâce aux notes fournies par Jenny Brian “How to obtain a bunch of GitHub issues or pull requests with R”. D’abord, vous devrez définir votre token Github comme variable d’environnement (voir ?gh_token pour plus d’informations).
library(gh)
library(purrr)
# gh_token()
issue_list <- gh(
"/repos/:owner/:repo/issues",
owner = "statnmap",
repo = "repo.rtask",
state = "all", since = "2015-09-01T00:00:00Z",
.limit = Inf)
issue_df <- issue_list %>%
tibble(number = map_int(., "number"),
id = map_int(., "id"),
title = map_chr(., "title"),
state = map_chr(., "state"),
n_comments = map_int(., "comments"),
opener = map_chr(., c("user", "login")),
created_at = map_chr(., "created_at") %>% as.Date())
issue_df## # A tibble: 2 x 8
## . number id title state n_comments opener created_at
## 1 <named list… 2 6.75e8 A second issue to illust… open 0 statnm… 2020-08-06
## 2 <named list… 1 6.75e8 An example of issue open 0 statnm… 2020-08-06Créer un rapport git contenant les noms des issues avec {gitdown}
Voici maintenant {gitdown}, pour créer le rapport. Le rapport standard qui prend les informations dans les messages de commit est le suivant.
git_down(repo = repo)
Comme j’ai téléchargé les tableaux de mes issues avec leurs noms depuis Gitlab ou Github, je peux utiliser une partie de ce tableau pour enrichir le rapport de {gitdown}. J’utilise le paramètre pattern.table qui nécessite un tableau à deux colonnes de pattern et de titre. Le pattern doit être écrit en entier, comme #1 pour le numéro 1.
# From gitlab
my_pattern_table <- my_project_issues %>%
mutate(
pattern = paste0("#", iid),
title = paste(pattern, title)
) %>%
select(pattern, title)
# From github
my_pattern_table <- issue_df %>%
mutate(
pattern = paste0("#", number),
title = paste(pattern, title)
) %>%
select(pattern, title)
my_pattern_table## # A tibble: 2 x 2
## pattern title
## <chr> <chr>
## 1 #2 #2 A second issue to illustrate a blog post
## 2 #1 #1 An example of issue# Launch gitdown
git_down(repo = repo, pattern.table = my_pattern_table)
Créer un rapport git avec des patterns spécifiques à l’utilisateur
Vous me direz peut-être que le rapport avec les issues, vous pouvez l’avoir en ligne avec votre compte Gitlab / Github. Ce n’est pas complètement faux… Le rapport {gitdown} est dédié aux personnes qui ne savent pas ce qu’est un dépôt git. Il est également destiné à être livré pour une documentation hors ligne associé à une version spécifique de votre logiciel.
De plus, ce rapport peut être utilisé en combinaison avec un système de gestion de projet externe, celui de votre client par exemple. Pour ce faire, vous devrez définir un pattern de texte pour identifier les tickets de vos clients et écrire ce pattern lorsqu’il est pertinent dans vos messages de commit.
Dans l’exemple avec fake_repo(), il y a donc un second pattern que nous avons identifié avec ticket1234 dans les messages de commit. Vous l’avez vu dans le dernier commit par exemple.
summary(last_commit(repo))## Commit: 66aa7a694f28f60888231ee7fb475e6ae27ef025
## Author: Alice <[email protected]>
## When: 2020-08-10 15:11:50 GMT
##
## Add NEWS
##
## issue #32.
## issue #1.
## issue#12
## ticket6789.
## ticket1234
## Creation of the NEWS file for version 0.1.
## 1 file changed, 3 insertions, 0 deletions
## NEWS.md | -0 +3 in 1 hunkAinsi, nous pouvons également créer le rapport pour ce pattern spécifique avec pattern.table.
pattern.table <- data.frame(
pattern = c("ticket1234", "ticket6789"),
title = c("Design of the Shiny app",
"Core of the app in Rmd")
)
git_down(repo, pattern = c("Tickets" = "ticket[[:digit:]]+"),
pattern.table = pattern.table)
Pour les mêmes raisons, nous avons créé {testdown}, un package pour transformer vos résultats {testthat} en un rapport HTML gitdown.
Essayez vous-même et dites-le nous !
Maintenant que vous avez vu les possibilités de {gitdown}, {gitlabr} et {gh}, dites-nous ce que vous allez en faire !
Pour {gitdown}, si vous trouvez un problème ou si vous voyez des fonctionnalités à ajouter, vous pouvez ouvrir un problème ou une demande de fusion (pull request) sur le dépôt Github : https://github.com/ThinkR-open/gitdown
Note : {gitlabr} a été développé à l’origine par Jirka Lewandowski (https://github.com/jirkalewandowski/gitlabr) qui est malheureusement décédé l’an dernier. Du coup, j’ai pris en charge le développement de ce package sur mon propre compte Github. Comme il n’a pas été mis à jour depuis un certain temps, il ne fonctionne pas totalement correctement avec les dernières versions de {tibble}, {dplyr}, … J’ai donc commencé à faire quelques modifications dans la “branche master”. Si vous voulez aider à la mise à jour de ce package, venez contribuer au projet Github : https://github.com/ThinkR-open/gitlabr, proposer des “pull requests” et ouvrir des “issues”.
