Make sure you revert this or sync to master

same on revert to master

hardcoded get

I suggest adding a bit of motivation on why someone should care about process mining and a summary of what you learned from the video I shared with you. OK to reference the video URL too.

Should use get() functions instead of direct access. See the cheat sheet associated to it for rationale on why.

So for example, to get the owner of the desired Github I should use "get_github_owner()" and rely on the configuration file for the users input?

The path to the configuration file should be passed to your /exec. However, to load the config from the path, and the subsequent accesses to get field information should use get() functions. The functions exist on R/config.R. if it doesn't exist, you should define new ones. See "accessing configs from Notebooks". That also applies to configs: https://github.com/sailuh/kaiaulu_cheatsheet/blob/main/cheatsheets/project-analysis-cheatsheet.pdf

Not all the code on PR is fully reviewed (I see Dao missed the config get to load the file), but it exists:

See the cheatsheet linked above why we enforce the get() this was a major milestone for the Fall'24 group : )

You should not use reticulate. This is a strong dependency on Kaiaulu side. Rather, it is the Python script that should call this exec script.

Hmm. Up to this point notebooks document the API, not the execs. I will need to give more thought on this in the future.

@carlosparadis The function github_parse_project_issue_events is a R/github.R function but R/github.R is not sourced at the top

Nice catch! Could you check if source is required for /exec to work? For R/ functions within an R package we do not need to use source, so it would be nice to check we are using the appropriate method for R packages specifically.

Looking at the requirement list, I see:

https://github.com/sailuh/kaiaulu/blob/8b0582539bbb18b8d4d2f2e410abe554b4c5acba/exec/github.R#L12C17-L12C24

As Kaiaulu is an R package, all files in Kaiaulu and its API should be loaded using this command. Did the code not rn for you?

I see my mistake; I haven't properly installed the packages and therefore I had to source both scripts. After installing the packages, it works as intended and sourcing those two scripts are no longer necessary.

CLI docs still refer to github_events.R. To stay consistent with the actual script name, this should be updated to ghevents.R

Could you check the other exec to see which should we stick with for consistency? E.g. if the others are all github_* then it may be best we move ghevents to github_events.R throughout the code.

source("R/config.R")
source("R/github.R")
should be added here since functions are called from those files.

I see require above as opposed to source, is there a reason you are suggesting source instead of require? In Noteboks we also use require. I suspect this PR predates when we created the config module. It may be a good idea for you to also see the cheat sheet about configs as you will be relying n it when coding on the /exec folder. I.e. the cheat sheet should explain you why we decided to create a bunch of get_ functions to read the config instead of just parsing directly!

Looking at the requirement list, I see:

https://github.com/sailuh/kaiaulu/blob/8b0582539bbb18b8d4d2f2e410abe554b4c5acba/exec/github.R#L12C17-L12C24

As Kaiaulu is an R package, all files in Kaiaulu and its API should be loaded using this command. Did the code not rn for you?

I see my mistake; I haven't properly installed the packages and therefore I had to source both scripts. After installing the packages, it works as intended and sourcing those two scripts are no longer necessary.

No worries, it is a common mistake!

The call to github_api_iterate_pages() includes verbose = TRUE, but the function doesn’t accept a verbose argument. Consider removing verbose = TRUE here to fix the error. This also occurs in lines 80 and 90.

What about

gh_response is used here but it isn't defined. Adding gh_response <- github_api_project_issue_or_pr_comments(owner, repo, token) before it is used within this else if block fixes it.

Isn't it defined on line 64? This is the entirety of the code block after it is defined:

gh_response in line 64 was defined within the scope of the 1st if block. Since gh_response was called in line 87 in the 3rd if block, it doesn't see gh_response.

I tested both scenarios where I'd add gh_response <- github_api_project_issue_or_pr_comments(owner, repo, token) in line 85 and one without it. The one without it gave me this error: Error: object 'gh_response' not found
Execution halted

Sorry, I replied without looking at the notebook. You are correct, this was likely an oversight: Every IF code block has more or less the same look and feel:

and

both have ghresponse.

However the one you pointed out is missing:

Meaning no data is being downloaded here. So this is a mistake. Please add the line here. Also thank you for trying to run the code while reviewing it (sometimes people don't! )

I also recommend you give some thought about all these GitHub endpoints we use:

We have a few for issues and a few for PR. The issue endpoints are for issue body and issue comment. However, the PR is far more complicated than what appears on the surface. We spent a lot of time making a cheatsheet about it. I encourage you take a look: https://github.com/sailuh/kaiaulu_cheatsheet/blob/eda5e0017419a2746fe823156c19798ae862fe76/cheatsheets/github-comments-cheatsheet.pdf

As you can see, there is a fair amount of cheatsheets around Kaiaulu. As you learn from them, use it as an exercise to consider what is the best visual representation to convey an idea without using too many words. Just imagine how many meetings we would need or walls of text absent all the cheatsheets I shared over the past 10 minutes across the comments!

Assuming this notebook runs in the vignettes directory, lines 50 and 53 contains exec/ghevents.R which should be changed to ../exec/ghevents.R since to run that the ghevents.R script it has to move one directory up before it can access exec/ghevents.R. If these commands are supposed to be ran in the root directory, this can be ignored.

Same should be applied to conf/process_mining.yml, instead it should be ../conf/process_mining.yml to access the conf folder if this notebook were to be ran in vignettes directory.

Note: process_mining.yml does not currently exist within this branch nor the master branch. I had to temporarily change process_mining.yml to kaiaulu.yml to test this notebook. Pushing this PR to master branch when process_mining.yml does not exist on either branch could be misleading.

Thank you for catching this. Unfortunately, this notebook implementation is incorrect. So I am glad you found it and asked me about it to avoid also doing the same. You see, the R notebook in Kaiaulu purpose is to explain to the user how to use Kaiaulu API (functions in R/) to write their own analysis. So, although the code here is functional, it is not complying to Kaiaulu architecture. There is also no reason to use the script when the user can just use the R function, it is an R notebook afterall.

The place which the exec should be used is outside Kaiaulu. This generally makes more sense if you are using another language, in which case you will not have the ability to call an R function directly or it is less desirable. For example, @austindang67 would want to issue a command line call to Kaiaulu to get the data he needs. This also keeps his side of the code clean on the frontend (the only responsability of the frontend is to request data from Kaiaulu, not preprocess it, etc).

Does that make sense? So the fix here would be to go to the script exec/ghevents.R and bring in the code block that is calling functions there into the notebook. In the notebook you may have a few code blocks and english around the code blocks explaining it.

Or is this code just cited here to acknowledge it exists and the rest of the notebook goes API function-wise?

In that case, we can leave the ghevents.R CLI commands as it is so people can see how to run the steps outside of R but exclude those commands from being ran in a code chunk since we do not want it to run in the notebook. Right after, we show the same steps using R functions that is implemented in a runnable code chunk. This way, people can learn both how the CLI works and how to do it in R.

Directly under the CLI commands, we can implement the R API functions equivalent of the CLI commands with the proper text:

In this notebook, the following code chunk shows the equivalent workflow using Kaiaulu R API functions, which can be run interactively and reproduces the same results as the CLI commands.

# Equivalent workflow using Kaiaulu R API functions.
# This can be run interactively and reproduces the same results as the CLI commands.
library(kaiaulu)
library(data.table)
library(jsonlite)

conf <- parse_config("../conf/process_mining.yml")
owner <- get_github_owner(conf, "project_key_1")
repo <- get_github_repo(conf, "project_key_1")
save_path <- get_github_issue_event_path(conf, "project_key_1")
token_path <- "~/.ssh/github_token"
output_file <- "../output.csv"

token <- scan(token_path, what="character", quiet=TRUE)
if(!dir.exists(save_path)) dir.create(save_path, recursive=TRUE)

# Download GitHub issue events 
gh_response <- github_api_project_issue_events(owner, repo, token)
github_api_iterate_pages(token, gh_response, save_path, prefix="issue_event")

#  Parse downloaded JSON files 
json_files <- list.files(save_path, full.names=TRUE)
all_issue_event <- lapply(json_files, read_json)
all_issue_event <- lapply(all_issue_event, github_parse_project_issue_events)
all_issue_event <- rbindlist(all_issue_event, fill=TRUE)
all_issue_event[, issue_body := NULL]

write.csv(all_issue_event, output_file, row.names=FALSE)

I've tested this implementation (with ../conf/kaiaulu.yml since process_mining.yml does not exist) in my code space in place of the two commands and it yielded the same results. I've also included comments to show what parts of the code downloads and parses. Also the config process_mining.yml is being parsed here, considering that .yml currently does not exist in this branch, should it be changed to kaiaulu.yml?

@carlosparadis I'm pinging now in the case you were not notified of my above comment ^

I missed this.

I suggest you still remove the CLI mention altogether. The main concern here is that, should the CLI be changed in the future (as you are doing now), we will need to keep tabs on which Notebook may be trying to explain it. If we forget it, then it becomes outdated. This type of implicit dependency is hard to manage, hence the requirement to keep the Notebooks as API only.

The project configuration file, however, I do feel we should explain at the start, as it clarifies what information is needed to run the notebook and the API specifically.

Also the config process_mining.yml is being parsed here, considering that .yml currently does not exist in this branch, should it be changed to kaiaulu.yml?

Presuming you will need to merge master into this branch (note who is being merged to who) in order to eventually merge this PR to master, wouldn't kaiaulu.yml be added here at that point?

@carlosparadis
In save_path <- path.expand(conf[["issue_tracker"]][["github"]][["replies"]]) , tries to access "replies" in kaiaulu.yml but that key does not exist.

Edit 1: Additionally, if the replies key were to be implemented in kaiaulu.yml, we also have to access "project_key_1" before reaching "replies". Therefore, if the "replies" key is implemented, the code should be save_path <- path.expand(conf[["issue_tracker"]][["github"]][["project_key_1"]][["replies"]]) instead.

Edit 2: The lines:
owner <- conf[["issue_tracker"]][["github"]][["owner"]]
repo <- conf[["issue_tracker"]][["github"]][["repo"]]
has to be changed to:
owner <- conf[["issue_tracker"]][["project_key_1"]][["github"]][["owner"]]
repo <- conf[["issue_tracker"]][["project_key_1"]][["github"]][["repo"]]

This is also outdated code, so thank you for catching this. The notebook should not be accessing directly the attributes of the conf folder. Rather, it should be using the get() functions defined in R/conf.R. The reason for that is simple: The conf architecture (the layout of how information is formatted) changes from time to time. You can imagine that every time that file changes, well, everything on Kaiaulu has to change which is a massive undertake.

A few sessions back, one group worked on an interface to access the fields using get() functions. Please have a look on this cheatsheet: https://github.com/sailuh/kaiaulu_cheatsheet/blob/main/cheatsheets/project-analysis-cheatsheet.pdf on the middle top, "Accessing Configs from Notebooks". It goes over that.

So the fix here is to replace the functions with get() from R/config.R.

I also hope you see here why the data cheatsheets exist for when you get around working on yours: They simplify conceptual design decisions we made in Kaiaulu that prevent the code to devolve into chaos. Once you understand the underlying idea there, you can apply the principle when writing your own code.

Good work on finding these issues!

The lines 47 to 49 can be replaced with:

owner <- get_github_owner(conf, "project_key_1") # Has to match github organization (e.g. github.com/sailuh)
repo <- get_github_repo(conf,"project_key_1") # Has to match github repository (e.g. github.com/sailuh/perceive)
save_path <- path.expand(get_github_issue_or_pr_comment_path(conf, "project_key_1")) # Path you wish to save all raw data. A folder with the repo name and sub-folders will be created. 

This uses the get() functions from R/config.R which is functionally equivalent.

@carlosparadis I'm pinging now in the case you were not notified of my above comment ^

If the get() functions already exist, I agree you can proceed with this!

Parse commands require running refresh first to download the GitHub JSON files; otherwise, CSV outputs will be empty. For documentation purposes, it would be better if the refresh commands are above the parse commands in this documentation in the case that the user wants to run these in a linear order.

This makes a lot of sense, please implement this change. I am also glad you encountered the refresh feature here. This also has a cheatsheet: https://github.com/sailuh/kaiaulu_cheatsheet/blob/main/cheatsheets/refresher-cheatsheet.pdf

Please take a look so you understand the core idea of why we named it "refresh". It is just an idea to simplify how users can get data without having to re-download everything and keeping on .csv files rather than add a whole database requirement to setup Kaiaulu. This was also a prior student group contribution!

Nice catch!