`cml pr` needs more docs and/or diagrams
- Dominant language
- TypeScript
- Stars
- 13
- Forks
- 22
- PR merge metrics
- No merged PRs in 30d
Description
Coming from [here](https://github.com/iterative/cml/pull/1035#pullrequestreview-992278127)
## From discussion:
> `cml pr --merge` then:
>
> 1. CI runs on the new branch created (let's call it `cml-branch-1`), generating in turn a new branch `cml-branch-2`, etc.
> 2. once the branch `cml-branch-1` is automatically merged into the original branch (typically a feature branch), CI will run again, which will again create a new branch `cml-branch-1b`. This branch will in turn generate a new look as in 1.
I don't follow (branch names are confusing). Do you mean "2. once `cml-branch-2` is automatically merged into `cml-branch-1` ..." instead? If so, the flow would be:
```mermaid
flowchart LR
M(main) -->|1. branch| F(feat) -->|2. branch| C1(cml-branch-1) -->|3. CI: cml pr --merge| C2(cml-branch-2)
C2 -->|4. CI: auto merge| C1 -->|5. CI: cml pr --merge| C1b(cml-branch-1b) -->|CI: infinite loop| C1
```
If so, this makes sense. And you ideally would like `cml-branch-1b` never to be created, right?
> `cml pr` (without the auto-merge), then:
>
> 1. CI will not run on the branch `cml-branch-1`. So far so good!
I don't follow.
> 2. Once I will manually merge `cml-branch-1` back in the feature branch, if I don't manually add "[ci skip]" to the commit message, CI will run again on the feature branch, generating `cml-branch-1b`.
```mermaid
flowchart LR
M(main) -->|1. branch| F(feat) -->|2. branch| C1(cml-branch-1) -->|3. CI: cml pr| C2(cml-branch-2)
C2 -->|"4. manual merge, entering [skip ci] into message"| C1
```
Anyway there are many work-arounds:
1. > deterministic runs [not opening PRs because of] diff being empty.
2. > feature request: make "[skip ci]" [appear in] all commit message of branches/PR created via `cml pr`
3. feature request:
```mermaid
flowchart LR
M(main) -->|1. branch| F(feat) -->|2. branch| C1(cml-branch-1) -->|3. CI: cml pr --merge --skip-ci| C2("cml-branch-2 with commit containing [skip ci]")
C2 -->|"4. auto merge without any CI tests running"| C1
```
4. [feature request](https://github.com/iterative/cml/issues/1023#issuecomment-1141277204):
```mermaid
flowchart LR
M(main) -->|1. branch| F(feat) -->|2. branch| C1(cml-branch-1) -->|3. CI: cml pr --merge --skip-ci| C2(cml-branch-2)
C2 -->|"4. auto merge, inserting [skip ci] into the merge commit message"| C1
```
So basically the problem with this PR currently is "auto merge without any CI tests running" right? Work-around (3) is broken? So we should do work-around (4)?
Contributor guide
Assessment
This issue has not been assessed yet.