From 2f39fc9836ecb8ab7dc25b2b80d9848cf9dcad5feda94901753c7c6a2f442619 Mon Sep 17 00:00:00 2001 From: Antonello Tartamo Date: Wed, 14 Jan 2026 15:36:01 +0100 Subject: [PATCH] initial documentation review --- group-review/README.md | 53 +++++++------ obs-staging-bot/README.md | 62 ++++++++++----- workflow-direct/README.md | 37 +++++---- workflow-pr/README.md | 153 ++++++++++++++++++++++++-------------- 4 files changed, 195 insertions(+), 110 deletions(-) diff --git a/group-review/README.md b/group-review/README.md index d8644a1..fb66325 100644 --- a/group-review/README.md +++ b/group-review/README.md @@ -1,43 +1,54 @@ Group Review Bot ================ -Areas of responsibility ------------------------ +This workaround is mainly needed because Gitea does not track which team member performed a review on behalf of a team. -1. Is used to handle reviews associated with groups defined in the - ProjectGit. +Main Tasks +---------- -2. Assumes: workflow-pr needs to associate and define the PR set from - which the groups.json is read (Base of the PrjGit PR) +Awaits a comment in the format “@groupreviewbot-name: approve”, then approves the PR with the comment “ approved a review on behalf of .” Target Usage ------------ Projects where policy reviews are required. -Configiuration +Configuration -------------- -Groups are defined in the workflow.config inside the project git. They take following options, +The bot is configured via the `ReviewGroups` field in the `workflow.config` file, located in the ProjectGit repository. +See `ReviewGroups` in the [workflow-pr configuration](../workflow-pr/README.md#config-file). + +```json { -... -ReviewGroups: [ - { - "Name": "name of the group user", - "Reviewers": ["members", "of", "group"], - "Silent": (true, false) -- if true, do not explicitly require review requests of group members - }, -], -... + ... + "ReviewGroups": [ + { + "Name": "name of the group user", + "Reviewers": ["members", "of", "group"], + "Silent": "(true, false) -- if true, do not explicitly require review requests of group members" + } + ], + ... } +``` + +Server configuration +-------------------------- + +**Configuration file:** + +| Field | Type | Notes | +| ----- | ----- | ----- | +| root | Array of string | Format **org/repo\#branch** | Requirements ------------ - * Gitea token to: - + R/W PullRequest - + R/W Notification - + R User +Gitea token with following permissions: +- R/W PullRequest +- R/W Notification +- R User Env Variables ------------- diff --git a/obs-staging-bot/README.md b/obs-staging-bot/README.md index 2bd2d38..727ce42 100644 --- a/obs-staging-bot/README.md +++ b/obs-staging-bot/README.md @@ -4,11 +4,15 @@ OBS Staging Bot Build a PR against a ProjectGit, if review is requested. -Areas of Responsibility ------------------------ +Main Tasks +---------- -* Monitors Notification API in Gitea for review requests -* Reviews Package build results in OBS for all changed packages in ProjectGit PR +* A build in OBS is initiated when a review for this bot is requested. +* The overall build status is reported: + * Build successful + * Build failed +* It checks the build status only for the involved packages compared to the last state of the project for all architectures and all flavors. +* It adds an svg with detailed building status. Target Usage @@ -21,22 +25,46 @@ Configuration File ------------------ Bot reads `staging.config` from the project git or the PR to the project git. -It's a JSON file with following syntax +It's a JSON file with following syntax: -``` +```json { - "ObsProject": "home:foo:project", - "StagingProject": "home:foo:project:staging", - "QA": [ - { - "Name": "ProjectBuild", - "Origin": "home:foo:product:images" - } - ] + "ObsProject": "SUSE:SLFO:1.2", + "StagingProject": "SUSE:SLFO:1.2:PullRequest", + "QA": [ + { + "Name": "SLES", + "Origin": "SUSE:SLFO:Products:SLES:16.0" + } + ] } ``` -* ObsProject: (**required**) Project where the base project is built. Builds in this project will be used to compare to builds based on sources from the PR -* StagingProject: template project that will be used as template for the staging project. Omitting this will use the ObsProject repositories to create the staging. Staging project will be created under the template, or in the bot's home directory if not specified. -* QA: set of projects to build ontop of the binaries built in staging. +| Field name | Details | Mandatory | Type | Allowed Values | Default | +| ----- | ----- | ----- | ----- | ----- | ----- | +| *ObsProject* | Product OBS project. Builds in this project will be used to compare to builds based on sources from the PR. | yes | string | `[a-zA-Z0-9-_:]+` | | +| *StagingProject* | Used both as base project and prefix for all OBS staging projects. Upon being added as a reviewer to a PrjGit PR, this bot automatically generates an OBS project named *StagingProject:*. It must be a sub-project of the *ObsProject*. | yes | string | `[a-zA-Z0-9-_:]+` | | +| *QA* | Crucial for generating a product build (such as an ISO or FTP tree) that incorporates the packages. | no | array of objects | | | +| *QA > Name* | Suffix for the QA OBS staging project. The project is named *StagingProject::Name*. | no | string | | | +| *QA > Origin* | OBS reference project | no | string | | | + + +Details +------- + +* **OBS staging projects are deleted** when the relative PrjGit PR is closed or merged. + +* **PrjGit PR - staging project** + * The OBS staging project utilizes an **scmsync** tag, configured with the `onlybuild` flag, to exclusively build packages associated with this specific PrjGit PR. + * The **build config** is inherited from the PrjGit PR config file (even if unchanged). + * The **project meta** creates a standard repository following the StagingProject as a project path. + * The base *StagingProject* has the macro **FromScratch:** set in its config, which prevents inheriting the configuration from the included project paths. + * The bot copies the project maintainers from *StagingProject* to the specific staging project (*StagingProject:*). + * The bot reports “Build successful” only if the build is successful for all repositories and all architectures. + +* **PrjGit PR - QA staging project** + * The QA staging project is meant for building the product; the relative build config is inherited from the `QA > Origin` project. + * In this case, the **scmsync** tag is inherited from the `QA > Origin` project. + + diff --git a/workflow-direct/README.md b/workflow-direct/README.md index 8a6f739..3bbdd4f 100644 --- a/workflow-direct/README.md +++ b/workflow-direct/README.md @@ -1,29 +1,41 @@ Direct Workflow bot =================== +The project submodule is automatically updated by the direct bot whenever a branch is updated in a package repository. +This bot can coexist with the Workflow PR bot, which is instead triggered by a new package PR. + +Target Usage +------------ + +Devel project, where direct pushes to package git are possible. + Areas of responsibility ----------------------- 1. Keep ProjectGit in sync with packages in the organization - * on pushes to package, updates the submodule commit id - to the default branch HEAD (as configured in Gitea) - * on repository adds, creates a new submodule (if non empty) - * on repository removal, removes the submodule + * **On pushes to package**: updates the submodule commit ID to the default branch HEAD (as configured in Gitea). + * **On repository adds**: creates a new submodule (if non-empty). + * **On repository removal**: removes the submodule. + +**Note:** If you want to revert a change in a package, you need to do that manually in the project git. Configuration ------------- -Uses `workflow.config` for configuration. Parameters +Uses `workflow.config` for configuration. -* _Workflows_: ["direct"] -- direct entry enables direct workflow. **Mandatory** -* _Organization_: organization that holds all the packages. **Mandatory** -* _Branch_: branch updated in repo's, or blank for default package branch -* _GitProjectName_: package in above org, or `org/package#branch` for PrjGit. By default assumes `_ObsPrj` with default branch and in the `Organization` +| Field name | Details | Mandatory | Type | Allowed Values | Default | +| ----- | ----- | ----- | ----- | ----- | ----- | +| *Workflows* | Type of workflow | yes | string | “direct” | | +| *Organization* | The organization that holds all the packages | yes | string | | | +| *Branch* | The designated branch for packages | no | string | | blank (default package branch) | +| *GitProjectName* | Repository and branch where the ProjectGit lives. | no | string | **Format**: `org/project_repo#branch` | By default assumes `_ObsPrj` with default branch in the *Organization* | NOTE: `-rm`, `-removed`, `-deleted` are all removed suffixes used to indicate current branch is a placeholder for previously existing package. These branches will be ignored by the bot, and if default, the package will be removed and will not be added to the project. -Running + +Environment Variables ------- * `GITEA_TOKEN` (required) @@ -37,8 +49,3 @@ Running * `AUTOGITS_REPO_PATH` - default is temporary directory * `AUTOGITS_IDENTITY_FILE` - in case where we need explicit identify path for ssh specified -Target Usage ------------- - -Devel project, where direct pushes to package git are possible - diff --git a/workflow-pr/README.md b/workflow-pr/README.md index 0612c2b..312b43f 100644 --- a/workflow-pr/README.md +++ b/workflow-pr/README.md @@ -1,55 +1,65 @@ Workflow-PR bot =============== -Keeps ProjectGit PR in-sync with a PackageGit PR - - -Areas of Responsibility ------------------------ - -* Detects a PackageGit PR creation against a package and creates a coresponsing PR against the ProjectGit -* When a PackageGit PR is updated, the corresponding PR against the ProjectGit is updated -* Stores reference to the PackageGit PR in the headers of the ProjectGit PR comments, for later reference - * this allows ProjectGit PR to be merged to seperated later (via another tool, for example) -* Initiates all staging workflows via review requests - +Keeps ProjectGit PRs in-sync with the relative PackageGit PRs. Target Usage ------------ -Any project (devel, etc) that accepts PR +Any project (devel, codestream, product, etc.) that accepts PRs. +Main Tasks +---------- + +* **Synchronization**: + * When a **PackageGit PR** is created for a package on a specific project branch, a corresponding PR is automatically generated in **ProjectGit**. + * When a PackageGit PR is updated, the corresponding PR against the ProjectGit is updated. + * A link to the PackageGit PR is stored in the body of the ProjectGit PR comments in the following format: + * `PR: organization/package_name!pull_request_number` + * Example: `PR: pool/curl!4` + * It closes an empty ProjectGit PR (e.g., if a PR was initially created for a single package but later integrated into a larger ProjectGit PR). + * It forwards the Work In Progress (WIP) flag to the ProjectGit PR. If the ProjectGit PR references multiple Package PRs, triggering the WIP flag on the ProjectGit PR side only requires a single WIP package PR. + +* **Reviewer Management**: + * It adds required reviewers in the ProjectGit PR. + * It adds required reviewers in the PackageGit PR. + * If new commits are added to a PackageGit PR, reviewers who have already approved it will be re-added. + +* **Merge Management**: + * Manages PR merges based on configuration flags (`ManualMergeOnly`, `ManualMergeProject`). + * In general, merge only happens if all mandatory reviews are completed. + * **ManualMergeProject** is stricter than **ManualMergeOnly** and has higher priority. + + | Flag | Value | Behavior | + | ----- | ----- | ----- | + | ManualMergeProject | true | Both ProjectGit and PackageGit PRs are merged upon an allowed project maintainer commenting "merge ok” in the ProjectGit PR. | + | ManualMergeOnly | true | Both PackageGit PR and ProjectGit PR are merged upon an allowed package maintainer or project maintainer commenting “merge ok” in the PackageGit PR. | + | ManualMergeOnly and ManualMergeProject | false | Both ProjectGit and PackageGit PRs are merged as soon as all reviews are completed in both PrjGit and PkgGit PRs. | + Config file ----------- -JSON -* _Workflows_: ["pr"] -- pr entry enables pr workflow. **Mandatory** -* _Organization_: organization that holds all the packages **Mandatory** -* _Branch_: branch updated in repo's **Mandatory** -* _GitProjectName_: package in above org, or `org/package#branch` for PrjGit. By default assumes `_ObsPrj` with default branch and in the `Organization` -* _Reviewers_: accounts associated with mandatory reviews for PrjGit. Can trigger additional - review requests for PrjGit or associated PkgGit repos. Only when all reviews are - satisfied, will the PrjGit PR be merged. See Reviewers below. -* _ManualMergeOnly_: (true, false) only merge if "merge ok" comment/review by package or project maintainers or reviewers -* _ManualMergeProject_: (true, false) only merge if "merge ok" by project maintainers or reviewers -* _ReviewRequired_: (true, false) ignores that submitter is a maintainer and require a review from other maintainer IFF available -* _NoProjectGitPR_: (true, false) do not create PrjGit PRs, but still process reviews, etc. -* _Permissions_: permissions and associated accounts/groups. See below. -* _Labels_: (string, string) Labels for PRs. See below. -NOTE: `-rm`, `-removed`, `-deleted` are all removed suffixes used to indicate current branch is a placeholder for previously existing package. These branches will be ignored by the bot, and if default, the package will be removed and will not be added to the project. -example: +* Filename: `workflow.config` +* Location: ProjectGit +* Format: non-standard JSON (comments allowed) + +| Field name | Details | Mandatory | Type | Allowed Values | Default | +| ----- | ----- | ----- | ----- | ----- | ----- | +| *Workflows* | Type of workflow | yes | string | “pr” | | +| *Organization* | The organization where PackageGit PRs are expected to occur | yes | string | | | +| *Branch* | The designated branch for PackageGit PRs | yes | string | | | +| *GitProjectName* | Repository and branch where the ProjectGit lives. | no | string | **Format**: `org/project_repo#branch` | By default assumes `_ObsPrj` with default branch in the *Organization* | +| *ManualMergeOnly* | Merges are permitted only upon receiving a "merge ok" comment from designated maintainers in the PkgGit PR. | no | bool | true, false | false | +| *ManualMergeProject* | Merges are permitted only upon receiving a "merge ok" comment in the ProjectGit PR from project maintainers. | no | bool | true, false | false | +| *ReviewRequired* | (NOT IMPLEMENTED) If submitter is a maintainer, require review from another maintainer if available. | no | bool | true, false | false | +| *NoProjectGitPR* | Do not create PrjGit PR, but still perform other tasks. | no | bool | true, false | false | +| *Reviewers* | PrjGit reviewers. Additional review requests are triggered for associated PkgGit PRs. PrjGit PR is merged only when all reviews are complete. | no | array of strings | | `[]` | +| *ReviewGroups* | If a group is specified in Reviewers, its members are listed here. | no | array of objects | | `[]` | +| *ReviewGroups > Name* | Name of the group | no | string | | | +| *ReviewGroups > Reviewers* | Members of the group | no | array of strings | | | +| *ReviewGroups > Silent* | Add members for notifications. If true, members are not explicitly requested to review. If one member approves, others are removed. | no | bool | true, false | false | - [ - { - "Workflows": ["pr", "direct"], - "Organization": "autogits", - "GitProjectName": "HiddenPrj", - "Branch": "hidden", - "Reviewers": [] - }, - ... - ] Reviewers --------- @@ -58,21 +68,30 @@ Reviews is a list of accounts that need to review package and/or project. They h [~][*|-|+]username -General prefix of ~ indicates advisory reviewer. They will be requested, but ignored otherwise. +A tilde (`~`) before a prefix signifies an advisory reviewer. Their input is requested, but their review status will not otherwise affect the process. Other prefixes indicate project or package association of the reviewer: + * `*` indicates project *and* package * `-` indicates project-only reviewer * `+` indicates package-only reviewer -`+` is implied. For example +`+` is implied. - `[foo, -bar, ~*moo]` +For example: `[foo, -bar, ~*moo]` results in: +* foo: package reviews +* bar: project reviews +* moo: package and project reviews, but ignored -results in -* foo -> package reviews -* bar -> project reviews -* moo -> package and project reviews, but ignored +Package Deletion Requests +------------------------- +(NOT YET IMPLEMENTED) + +* **Removing a Package:** + To remove a package from a project, submit a ProjectGit Pull Request (PR) that removes the corresponding submodule. The bot will then rename the project branch in the pool by appending "-removed" to its name. + +* **Adding a Package Again:** + If you wish to re-add a package, create a new PrjGit PR which adds again the submodule on the branch that has the "-removed" suffix. The bot will automatically remove this suffix from the project branch in the pool. Labels @@ -83,26 +102,38 @@ The following labels are used, when defined in Repo/Org. | Label Config Entry | Default label | Description |--------------------|----------------|---------------------------------------- | StagingAuto | staging/Auto | Assigned to Project Git PRs when first staged -| ReviewPending | review/Pending | Assigned to PR when reviews are still pending -| ReviewDone | review/Done | Assigned to PR when reviews are complete on this particular PR +| ReviewPending | review/Pending | Assigned to Project Git PR when package reviews are still pending +| ReviewDone | review/Done | Assigned to Project Git PR when reviews are complete on all package PRs Maintainership -------------- -Maintainership information is defined per project. For reviews, package maintainers are coalesced -with project maintainers. A review by any of the maintainers is acceptable. +Filename: \_maintainership.json +Location: ProjectGit +Format: JSON +Fields: -example: +| Key | Value | Notes | +| ----- | ----- | ----- | +| package name | array of strings representing the package maintainers | List of package maintainers | +| “” (empty string) | array of strings representing the project maintainers | List of project maintainers | - { - "package1": [ "reviewer", "reviewer2"], - "package2": [], +Maintainership information is defined per project. For PackageGit PR reviews, package maintainers are combined with project maintainers. A review by any of these maintainers is acceptable. - // "project" maintainer - "": ["reviewer3", "reviewer4"] - } +If the submitter is a maintainer it will not get a review requested. +Example: + +``` +{ + "package1": [ "reviewer", "reviewer2"], + "package2": [], + + // "project" maintainer + "": ["reviewer3", "reviewer4"] +} +``` Permissions ----------- @@ -122,3 +153,11 @@ the `workflow.config`. NOTE: Project Maintainers have these permissions automatically. +Server configuration +-------------------------- + +**Configuration file:** + +| Field | Type | Notes | +| ----- | ----- | ----- | +| root | Array of string | Format **org/repo\#branch** | \ No newline at end of file -- 2.51.1