This is an automated email from the ASF dual-hosted git repository. zky pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/incubator-devlake-website.git
commit d1075c24bd0b64534dd46fead83377d9a59fad40 Author: abeizn <[email protected]> AuthorDate: Wed Nov 23 15:07:29 2022 +0800 docs: update refdiff docs --- docs/Plugins/refdiff.md | 79 +++++++++++++++++++++++++++---------------------- 1 file changed, 44 insertions(+), 35 deletions(-) diff --git a/docs/Plugins/refdiff.md b/docs/Plugins/refdiff.md index d97f1c1da..4ba983c16 100644 --- a/docs/Plugins/refdiff.md +++ b/docs/Plugins/refdiff.md @@ -4,10 +4,9 @@ description: > RefDiff Plugin --- - ## Summary -For development workload analysis, we often need to know how many commits have been created between 2 releases. This plugin calculates which commits differ between 2 Ref (branch/tag), and the result will be stored back into the database for further analysis. +For development workload analysis, we often need to know how many commits have been created between 2 releases. This plugin calculates which commits differ between 2 commits, and the commits are produced by Ref (branch/tag) or by deployments, and the result will be stored back into the database for further analysis. ## Important Note @@ -22,22 +21,25 @@ This is an enrichment plugin based on the domain layer data, no configuration is To trigger the enrichment, you need to insert a new task into your pipeline. 1. Make sure `commits` and `refs` are collected into your database, `refs` table should contain records like following: - ``` - id ref_type - github:GithubRepo:384111310:refs/tags/0.3.5 TAG - github:GithubRepo:384111310:refs/tags/0.3.6 TAG - github:GithubRepo:384111310:refs/tags/0.5.0 TAG - github:GithubRepo:384111310:refs/tags/v0.0.1 TAG - github:GithubRepo:384111310:refs/tags/v0.2.0 TAG - github:GithubRepo:384111310:refs/tags/v0.3.0 TAG - github:GithubRepo:384111310:refs/tags/v0.4.0 TAG - github:GithubRepo:384111310:refs/tags/v0.6.0 TAG - github:GithubRepo:384111310:refs/tags/v0.6.1 TAG - ``` + ``` + id ref_type + github:GithubRepo:1:384111310:refs/tags/0.3.5 TAG + github:GithubRepo:1:384111310:refs/tags/0.3.6 TAG + github:GithubRepo:1:384111310:refs/tags/0.5.0 TAG + github:GithubRepo:1:384111310:refs/tags/v0.0.1 TAG + github:GithubRepo:1:384111310:refs/tags/v0.2.0 TAG + github:GithubRepo:1:384111310:refs/tags/v0.3.0 TAG + github:GithubRepo:1:384111310:refs/tags/v0.4.0 TAG + github:GithubRepo:1:384111310:refs/tags/v0.6.0 TAG + github:GithubRepo:1:384111310:refs/tags/v0.6.1 TAG + ``` 2. If you want to run calculatePrCherryPick, please configure GITHUB_PR_TITLE_PATTERN in .env, you can check the example in .env.example(we have a default value, please make sure your pattern is disclosed by single quotes '') 3. And then, trigger a pipeline like the following format, you can also define sub-tasks, calculateRefDiff will calculate commits between two refs, and creatRefBugStats will create a table to show a bug list between two refs: + ```shell -curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' +curl 'http://localhost:8080/pipelines' \ +--header 'Content-Type: application/json' \ +--data-raw ' { "name": "test-refdiff", "tasks": [ @@ -45,7 +47,7 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' { "plugin": "refdiff", "options": { - "repoId": "github:GithubRepo:384111310", + "repoId": "github:GithubRepo:1:384111310", "pairs": [ { "newRef": "refs/tags/v0.6.0", "oldRef": "refs/tags/0.5.0" }, { "newRef": "refs/tags/0.5.0", "oldRef": "refs/tags/0.4.0" } @@ -59,12 +61,15 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' } ] ] -} -JSON +}' ``` + Or if you preferred calculating latest releases + ```shell -curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' +curl 'http://localhost:8080/pipelines' \ +--header 'Content-Type: application/json' \ +--data-raw ' { "name": "test-refdiff", "tasks": [ @@ -72,7 +77,7 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' { "plugin": "refdiff", "options": { - "repoId": "github:GithubRepo:384111310", + "repoId": "github:GithubRepo:1:384111310", "tagsPattern": "v\d+\.\d+.\d+", "tagsLimit": 10, "tagsOrder": "reverse semver", @@ -85,15 +90,17 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' } ] ] -} -JSON +}' ``` ## How to use refdiff in DORA + RefDiff can be called by the [DORA plugin](https://github.com/apache/incubator-devlake/tree/main/plugins/dora) to support the calculation of [DORA metrics](https://devlake.apache.org/docs/UserManuals/DORA). RefDiff has a subtask called 'calculateProjectDeploymentCommitsDiff'. This subtask takes the `project_name` from task options to calculate the commits diff between two consecutive deployments in this project. That is to say, refdiff will generate the relationship between `deployed com [...] - + ```shell -curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' +curl 'http://localhost:8080/pipelines' \ +--header 'Content-Type: application/json' \ +--data-raw ' { "name": "test-refdiff-dora", "tasks": [ @@ -101,7 +108,7 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' { "plugin": "refdiff", "options": { - "projectName": "xxxx", + "projectName": "project_name_1", "tasks": [ "calculateProjectDeploymentCommitsDiff" ] @@ -109,7 +116,7 @@ curl -v -XPOST http://localhost:8080/pipelines --data @- <<'JSON' } ] ] -} +}' ``` ## Development @@ -126,7 +133,7 @@ apt install cmake -y [centos] yum install cmake -y -2. compiling +2. compiling git clone -b v1.3.0 https://github.com/libgit2/libgit2.git && cd libgit2 mkdir build && cd build && cmake .. make && make install @@ -142,25 +149,26 @@ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib #### Troubleshooting (Linux) -> Q: # pkg-config --cflags -- libgit2 Package libgit2 was not found in the pkg-config search path. -Perhaps you should add the directory containing `libgit2.pc` to the PKG_CONFIG_PATH environment variable -No package 'libgit2' found pkg-config: exit status 1 +> Q: # pkg-config --cflags -- libgit2 Package libgit2 was not found in the pkg-config search path. +> Perhaps you should add the directory containing `libgit2.pc` to the PKG_CONFIG_PATH environment variable +> No package 'libgit2' found pkg-config: exit status 1 > A: > Make sure your pkg config path covers the installation: > if your libgit2.pc in `/usr/local/lib64/pkgconfig`(like centos) -> +> > `export > PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib64:/usr/local/lib64/pkgconfig` -> +> > else if your libgit2.pc in `/usr/local/lib/pkgconfig`(like ubuntu) -> +> > `export > PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib:/usr/local/lib/pkgconfig` -> +> > else consider install pkgconfig or rebuild the libgit2 ### MacOS NOTE: **Do NOT** install libgit2 via `MacPorts` or `homebrew`, install from source instead. + ``` brew install cmake git clone https://github.com/libgit2/libgit2.git @@ -178,11 +186,12 @@ make install > Q: I got an error saying: `pkg-config: exec: "pkg-config": executable file > not found in $PATH` > A: +> > 1. Make sure you have pkg-config installed: > > `brew install pkg-config` > > 2. Make sure your pkg config path covers the installation: -> `export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib:/usr/local/lib/pkgconfig` +> `export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:/usr/local/lib:/usr/local/lib/pkgconfig` <br/><br/><br/>
