Metadata-Version: 2.4
Name: mrhlpr
Version: 1.10.0
Summary: postmarketOS tools for interacting with gitlab MRs
Author-email: postmarketOS Developers <info@postmarketos.org>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://www.postmarketos.org
Keywords: postmarketos,gitlab
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: completion
Requires-Dist: argcomplete; extra == "completion"
Provides-Extra: api
Requires-Dist: python-gitlab>=4.0.0; extra == "api"
Dynamic: license-file

This repository holds two programs, mrhlpr and mrtest. The mrhlpr program is
described below, information about mrtest can be found in the
[postmarketOS wiki](https://wiki.postmarketos.org/wiki/Mrtest).

> The mrtest program must be run on pmOS or alpine device in order to work correctly.

# mrhlpr - merge request helper

Lightweight script to support maintainers of postmarketOS in the merge workflow on GitLab.

After installing mrhlpr (see below) and [configuring a gpg key](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) to use with git, this is the basic workflow. Further below is a full example session with example output.

0. Use `cd` to enter a locally cloned git repository (e.g. `pmaports.git`).
1. Checkout the merge request locally (`mrhlpr checkout 123`).
2. Rebase on latest main (`git rebase main`).
3. Add the MR-ID to all commit messages and sign them (`mrhlpr fixmsg`).
4. Optionally squash all commits (`git rebase -i main`).
5. Check if everything is fine (`mrhlpr status`).
6. Choose one of:
   1. Finish things automatically following the instructions (`mrhlpr finish`). You will need to have the environment variable `GITLAB_TOKEN` set in your environment containing a [Personal Access Token](https://gitlab.postmarketos.org/-/user_settings/personal_access_tokens) with the "api" scope.
   2. Manually push and merge:
      1. If everything looks good force push (`git push --force`).
      2. In the GitLab web UI: wait for CI, then merge.

## Installation
Same as for pmbootstrap: clone the repo, create a symlink to `mrhlpr.py` in your `PATH`. Optionally set up autocompletion with argcomplete. See pmbootstrap's [manual installation instructions](https://wiki.postmarketos.org/wiki/Installing_pmbootstrap#Installing_Manually) for details.

## Example Session

Start with `mrhlpr checkout` and the MR-ID. The built-in checklist will tell the next steps. All API requests get cached on disk.

```shell-session
$ cd ~/code/pmbootstrap/aports
$ mrhlpr checkout 81
Download https://gitlab.postmarketos.org/api/v4/projects/postmarketOS%2Fpmaports/merge_requests/81
Download https://gitlab.postmarketos.org/api/v4/projects/8065375
Checkout feature/abuild-sign-noinclude from postmarketOS/feature/abuild-sign-noinclude
https://gitlab.postmarketos.org/postmarketOS/pmaports/merge_requests/81

"main/abuild-sign-noinclude: new aport" (!81)
10 commits from postmarketOS/feature/abuild-sign-noinclude

[OK ] Changes allowed
[OK ] Clean worktree
[NOK] Rebase on main
[NOK] MR-ID in commit msgs
[NOK] Commits are signed

Checklist:
* 10 commits: consider squashing ('git rebase -i origin/main')
* Rebase on main ('git rebase origin/main')
* Check again ('mrhlpr status')
```

```shell-session
$ git rebase -i main
$ mrhlpr status
https://gitlab.postmarketos.org/postmarketOS/pmaports/merge_requests/81

"main/abuild-sign-noinclude: new aport" (!81)
1 commit from postmarketOS/feature/abuild-sign-noinclude

[OK ] Changes allowed
[OK ] Clean worktree
[OK ] Rebase on main
[NOK] MR-ID in commit msgs
[NOK] Commits are signed

Checklist:
* Add the MR-ID to all commits and sign them ('mrhlpr fixmsg')
* Pretty 'git log -1 --pretty'? (consider copying MR desc)
* Finish the MR: push, approve, merge, comment ('mrhlpr finish')
```

```shell-session
$ mrhlpr fixmsg
Appending ' (!81)' to all commits...
https://gitlab.postmarketos.org/postmarketOS/pmaports/merge_requests/81

"main/abuild-sign-noinclude: new aport" (!81)
1 commit from postmarketOS/feature/abuild-sign-noinclude

[OK ] Changes allowed
[OK ] Clean worktree
[OK ] Rebase on main
[OK ] MR-ID in commit msgs
[OK ] Commits are signed

Checklist:
* Pretty 'git log -1 --pretty'? (consider copying MR desc)
* Finish the MR: push, approve, merge, comment ('mrhlpr finish')
```

### Status descriptions

| Status | Description                  |
| ------ | ---------------------------- |
| [OK ]  | Everything is OK             |
| [NOK]  | Something is wrong           |
| [???]  | Seems OK, but manually check |

### mrhlpr.json

Optionally you can add a `.mrhlpr.json` file to your repository, this contains extra verification rules specific to your repository. An example file:

```json
{
    "subject_format": {
        "pass": [
            "^[a-z]+/[a-z-0-9*{}]+: new aport(s|)( \\(!\\d+\\)|)$",
            "^[a-z]+/[a-z-0-9*{}]+: pkgrel bump( \\(!\\d+\\)|)$",
            "^[a-z-0-9*{}]+: new device \\([^\\)]+\\)( \\(!\\d+\\)|)",
            "^[a-z]+/[a-z-0-9*{}]+: upgrade to [0-9\\.a-z\\-_]+( \\(!\\d+\\)|)$"
        ],
        "unknown": [
            "^[a-z-0-9*{}\\/]+: [a-z\\-0-9*{}\\(\\)\\._ ]+( \\(!\\d+\\)|)$"
        ]
    }
}
```


### Portability

This script is not postmarketOS specific, it should work with any GitLab repository. Right now, only gitlab.postmarketos.org is detected - but detecting any GitLab servers could be added in `mrhlpr/gitlab.py:parse_git_origin()` if desired.


### Troubleshooting

`mrhlpr -v` displays debug log messages, such as all git commands and their output, as well as the locations of all http cache files.
