From d20162b0700c345fe6489c103da00b44471080a7 Mon Sep 17 00:00:00 2001 From: Laura Barcziova Date: Mon, 26 Feb 2024 13:26:43 +0100 Subject: [PATCH] Restructure both upstream and downstream guides - add manual TOCs with most important section links - make the structure consistent - link the downstream one more visibly from upstream one --- docs/configuration/downstream/koji_build.md | 3 + .../downstream/pull_from_upstream.md | 2 +- .../dist-git-onboarding.md | 206 +++++++++++------- docs/fedora-releases-guide/index.md | 6 +- docs/guide.md | 70 +++--- 5 files changed, 185 insertions(+), 102 deletions(-) diff --git a/docs/configuration/downstream/koji_build.md b/docs/configuration/downstream/koji_build.md index ec653f4ad4..0bc17d631b 100644 --- a/docs/configuration/downstream/koji_build.md +++ b/docs/configuration/downstream/koji_build.md @@ -78,6 +78,9 @@ Packit dist-git configuration. * **require.label** - you can specify labels that have to be present/absent on a pull request in order to trigger the build when it is merged. See configuration details [here](/docs/configuration#require). + +## Processing of dist-git events from Pagure + :::info Processing of dist-git events from Pagure ```mermaid diff --git a/docs/configuration/downstream/pull_from_upstream.md b/docs/configuration/downstream/pull_from_upstream.md index fffbfbb032..c504342ea1 100644 --- a/docs/configuration/downstream/pull_from_upstream.md +++ b/docs/configuration/downstream/pull_from_upstream.md @@ -44,7 +44,7 @@ Packit dist-git configuration. repository (`rawhide`). Packit configs on other branches are ignored. * Upstream release monitoring is active for the package. [The monitoring status](https://docs.fedoraproject.org/en-US/package-maintainers/Upstream_Release_Monitoring/) - in dist-git should be set to `Monitoring`). + in dist-git should be set to `Monitoring`. * [`upstream_project_url`](/docs/configuration#upstream_project_url) pointing to a Git repository is defined in the configuration. ## First setup diff --git a/docs/fedora-releases-guide/dist-git-onboarding.md b/docs/fedora-releases-guide/dist-git-onboarding.md index 95285d249f..0c17d2720a 100644 --- a/docs/fedora-releases-guide/dist-git-onboarding.md +++ b/docs/fedora-releases-guide/dist-git-onboarding.md @@ -1,22 +1,69 @@ --- title: Dist-git repository onboarding -sidebar_position: 8 +sidebar_position: 6 --- # Dist-git repository onboarding -Doing Fedora releases with Packit in dist-git only means having configuration placed only in the -dist-git repository in the default (`rawhide`) branch and defining these jobs: +## Table of contents +- [Setup](#setup) + - [1. Configuration file](#configuration-file) + - [2. Monitoring](#monitoring-of-the-package) + - [How to try that for real](#how-to-try-that-for-real) +- [UI](#ui) +- [Retriggering](#retriggering) +- [Full example of a configuration](#full-example-of-a-dist-git-only-configuration) + +## Setup + +To start using Packit in dist-git, you only need: +1. a configuration file +2. enable the monitoring for your package + + +### 1. Configuration file +To start using Packit for automating your Fedora releases with setup **only** in dist-git, +the main thing you need is to create a configuration file and place it +in the default (`rawhide`) branch of your dist-git repository. + +As a format, it uses YAML and here are all the valid names: +* `.packit.yaml` +* `.packit.yml` +* `packit.yaml` +* `packit.yml` + +In your configuration file, you can define these jobs: 1. [`pull_from_upstream`](#pull-from-upstream-job) 2. [`koji_build`](#koji-build-job) 3. [`bodhi_update`](#bodhi-update-job) -You can check an example of such configuration [in the section below](#full-example-of-a-dist-git-only-configuration). +:::tip Downstream configuration template + +You can use our [downstream configuration template](/docs/configuration/downstream_configuration_template) +for creating your Packit configuration in dist-git repository. + +::: + +:::tip Automate the setup + +You can also use [packit dist-git init](/docs/cli/dist-git/init.md) CLI command to create your +Packit dist-git configuration. + +::: + +:::tip Configuration validation -## Pull from upstream job +For validation of the configuration, you can utilise +Packit CLI command [`validate-config`](/docs/cli/validate-config) or our +[pre-commit hooks](/posts/pre-commit-hooks#validate-config). + +::: + + +#### Jobs + +##### Pull from upstream job When a new upstream release happens and [release-monitoring.org](https://release-monitoring.org/) detects it, you'll -get dist-git pull requests with it automatically. There needs to be a mapping to your Fedora package -in [Anitya](todo) and on the left side in htpps://src.fedoraproject.org/rpms/your-repo, you need to set -`Monitoring status` to `Monitoring` so that Packit can react to these events. +get dist-git pull requests with it automatically. Bodhi updates created by the [`bodhi_update` job](/docs/configuration/downstream/pull_from_upstream) as well as [automatic Bodhi updates](https://fedora-infra.github.io/bodhi/6.0/user/automatic_updates.html) will close the Bugzilla opened by the Upstream Release Monitoring automatically when they reach stable. @@ -35,7 +82,6 @@ It is necessary to set the [`upstream_project_url`](/docs/configuration/#upstrea ::: -#### Customization You can check the other customization options [here](./index.md#customization). :::info Divergent dist-git branches @@ -43,9 +89,64 @@ Current default behaviour of the release syncing results in having divergent dis please see the details [here](/docs/fedora-releases-guide#keeping-dist-git-branches-non-divergent). ::: -### First setup -If you are interested in this functionality and want to try it out, we recommend triggering the job -first time from a dist-git pull request to make sure Packit is correctly configured. + +##### Koji build job +You can configure Packit to react to the new commits in your dist-git repository and create +Koji builds by including a `koji_build` job in the configuration. +Then, if Packit is informed (via fedora-messaging bus) about a new commit in the configured dist-git branch, it submits a new build in Koji +like maintainers usually do. (The commits without any spec file change are skipped.) + +By default, only merged pull requests created by Packit are being acted upon, but +you can override this behaviour by specifying +`allowed_pr_authors` and/or `allowed_committers` in the [job configuration](/docs/configuration/downstream/koji_build). + +The [koji_build job](/docs/configuration/downstream/koji_build) can be configured like this: + +```yaml +jobs: +- job: koji_build + trigger: commit + dist_git_branches: + - fedora-all +``` + +##### Bodhi update job +You can configure Packit to react to successful Koji builds and create +Bodhi updates by including a `bodhi_update` job in the configuration. +Once Packit is informed (via fedora-messaging bus) about the successful Koji build for the configured branch, +it creates a new update for that branch in Bodhi for you. + +The [bodhi_update job](/docs/configuration/downstream/bodhi_update) can be configured like this: + +```yaml +jobs: +- job: bodhi_update + trigger: commit + dist_git_branches: + - fedora-branched # rawhide updates are created automatically +``` + +#### Actions +Actions are a way how to redefine or tweak the Packit's workflows. +These are user-defined commands that can replace a part of Packit's job (e.g. to get version, or to create a tarball) +or are run in a particular step as a hook (with no action run by default). + +Take a look at the tables [here](/docs/configuration/actions/) to know what actions are available for each job. + +### 2. Monitoring of the package +Besides the configuration file, if you use the [`pull_from_upstream` job](#pull-from-upstream-job), you also need +to have your package monitored by Upstream Release Monitoring: +1. make sure there is Fedora mapping for the upstream project in https://release-monitoring.org/projects/ +2. make sure `Monitoring status` on the left side at https://src.fedoraproject.org/rpms/your-package is set to `Monitoring` + + +You can check an example of a configuration file [in the section below](#full-example-of-a-dist-git-only-configuration). + +### How to try that for real +#### Release syncing +If you are interested in the functionality of syncing the release ([`pull_from_upstream` job](#pull-from-upstream-job)) +and want to try it out, we recommend triggering the job +first time from a dist-git pull request to make sure Packit is correctly configured (see the following sections). #### If there is a pending release If there is a new release pending for your package (bugzilla has been opened by [release-monitoring.org](https://release-monitoring.org/) but no rebase done in dist-git yet), do the following: @@ -81,47 +182,24 @@ When triggering via comment, the version is retrieved from the latest upstream p :::tip Reproducing from CLI To reproduce the Packit Service behaviour with your credentials from CLI, -you can use a [`packit pull-from-upstream`](/docs/cli/#TODO-create) command. +you can use a [`packit pull-from-upstream`](/docs/cli/pull-from-upstream) command. It creates dist-git pull requests with the content of the release and the Packit config taken from a local clone. ::: +#### Koji builds and Bodhi updates +The Koji builds are triggered for dist-git pushes to configured branches that contain specfile change +and meet other requirements (see [the schema](/docs/configuration/downstream/koji_build#processing-of-dist-git-events-from-pagure)). +The Bodhi updates are then created when Packit successfuly builds in Koji. +You can trigger both of them manually as well, see [Retriggering section](#retriggering). -## Koji build job -You can configure Packit to react to the new commits in your dist-git repository and create -Koji builds by including a `koji_build` job in the configuration. -Then, if Packit is informed (via fedora-messaging bus) about a new commit in the configured dist-git branch, it submits a new build in Koji -like maintainers usually do. (The commits without any spec file change are skipped.) - -By default, only merged pull requests created by Packit are being acted upon, but -you can override this behaviour by specifying -`allowed_pr_authors` and/or `allowed_committers` in the [job configuration](/docs/configuration/downstream/koji_build). - -The [koji_build job](/docs/configuration/downstream/koji_build) can be configured like this: - -```yaml -jobs: -- job: koji_build - trigger: commit - dist_git_branches: - - fedora-all -``` - -## Bodhi update job -You can configure Packit to react to successful Koji builds and create -Bodhi updates by including a `bodhi_update` job in the configuration. -Once Packit is informed (via fedora-messaging bus) about the successful Koji build for the configured branch, -it creates a new update for that branch in Bodhi for you. +:::tip Reproducing from CLI -The [bodhi_update job](/docs/configuration/downstream/bodhi_update) can be configured like this: +To reproduce the Packit Service behaviour with your credentials from CLI, +you can use again Packit commands [`packit build in-koji`](/docs/cli/build/in-koji) and +[`packit create-update`](/docs/cli/create-update). -```yaml -jobs: -- job: bodhi_update - trigger: commit - dist_git_branches: - - fedora-branched # rawhide updates are created automatically -``` +::: ## UI @@ -151,23 +229,22 @@ This will take the Packit configuration file from the default branch of the dist ### koji_build -You can retrigger a build by a comment in a dist-git pull request: +Packagers can retrigger a build by a comment in a dist-git pull request: /packit koji-build The build will be triggered for the target branch of the pull request using the most recent commit on the target branch -(NOT the HEAD commit of the pull request). The user who posts this comment needs to be a packager. +(NOT the HEAD commit of the pull request). If Packit created an issue in the configured `issue_repository`, you can place the same comment in that issue to retrigger the builds (see [`issue_repository`](/docs/configuration#issue_repository) for details). ### bodhi_update -You can retrigger an update by a comment in a dist-git pull request: +Packagers with write access to the dist-git repository can retrigger an update by a comment in a dist-git pull request: /packit create-update -The update will be triggered for the target branch of the pull request. The user who -posts this comment needs to be a packager and have write access to the dist-git repository. +The update will be triggered for the target branch of the pull request. If Packit created an issue in the configured `issue_repository`, you can place the same comment in that issue to retrigger the updates (see [`issue_repository`](/docs/configuration#issue_repository) for details). @@ -178,27 +255,6 @@ issue to retrigger the updates (see [`issue_repository`](/docs/configuration#iss Let's take a look how the configuration file can look like when you define all three steps. It's quite simple, isn't it? -:::tip Downstream configuration template - -You can use our [downstream configuration template](/docs/configuration/downstream_configuration_template) -for creating your Packit configuration in dist-git repository. - -::: - -:::tip Automate the setup - -You can also use [packit dist-git init](/docs/cli/dist-git/init.md) CLI command to create your -Packit dist-git configuration. - -::: - -:::tip Configuration validation - -For validation of the configuration, you can utilise -Packit CLI command [`validate-config`](/docs/cli/validate-config) or our -[pre-commit hooks](/posts/pre-commit-hooks#validate-config). - -::: ```yaml upstream_project_url: https://github.com/upstream/package @@ -209,8 +265,12 @@ jobs: dist_git_branches: - fedora-rawhide actions: + commit-message: + - bash -c 'echo "Update to ${PACKIT_PROJECT_VERSION}"' + - bash -c '[ -z "$PACKIT_RESOLVED_BUGS" ] || echo ${PACKIT_RESOLVED_BUGS} | tr " " "\n" | sed "s/^/- Resolves /"' changelog-entry: - - bash -c 'echo "- New release ${PACKIT_PROJECT_VERSION}"' + - bash -c 'echo "- Update to ${PACKIT_PROJECT_VERSION}"' + - bash -c '[ -z "$PACKIT_RESOLVED_BUGS" ] || echo ${PACKIT_RESOLVED_BUGS} | tr " " "\n" | sed "s/^/- Resolves /"' - job: koji_build trigger: commit diff --git a/docs/fedora-releases-guide/index.md b/docs/fedora-releases-guide/index.md index 50c30a79f3..c46e4aa5fb 100644 --- a/docs/fedora-releases-guide/index.md +++ b/docs/fedora-releases-guide/index.md @@ -1,6 +1,6 @@ --- title: How to do Fedora releases with Packit -sidebar_position: 8 +sidebar_position: 5 --- # How to do Fedora releases with Packit @@ -21,8 +21,8 @@ Every job takes care of a different part of the release process. :::tip In this page, you can find all the details of the release process automation covered by Packit. -If you are a downstream package maintainer and would like to see the information -on how to onboard to using Packit in dist-git, see [dist-git onboarding](./dist-git-onboarding.md) directly. +If you are a **downstream package maintainer** and would like to see the information on how to onboard to using +Packit in dist-git, see [dist-git onboarding guide](dist-git-onboarding.md) directly. ::: diff --git a/docs/guide.md b/docs/guide.md index c4bd0d37bf..c5fcaf180f 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -1,20 +1,44 @@ --- -title: Packit Onboarding Guide +title: Packit Upstream Onboarding Guide sidebar_position: 2 --- -# Packit Onboarding Guide +# Packit Upstream Onboarding Guide -Let's take a look on how to start using Packit and how to get the most out of it. +Let's take a look on how to start using Packit if you are an upstream maintainer +and how to get the most out of it. + +:::tip Dist-git onboarding guide + +If you are a **downstream package maintainer** and would like to see the information on how to onboard to using +Packit in dist-git, see [dist-git onboarding guide](./fedora-releases-guide/dist-git-onboarding.md) directly. + +::: + +:::tip CLI tool This guide is focused on the service use-case, but Packit is also available as a [CLI tool](https://github.com/packit/packit/blob/main/README.md), so you can always [try things locally](/docs/cli/) on your own. Note that running tests in Testing farm infrastructure is not currently supported with the CLI tool. Unlike the service, CLI uses your own identities when connecting to other service like [Copr](https://copr.fedorainfracloud.org/) or [Fedora dist-git](https://src.fedoraproject.org/). -Packit CLI is **NOT** a client of the Packit GitHub app, -`packit` command directly interacts with the services. +Packit CLI is **NOT** a client of the Packit GitHub app, `packit` command directly interacts with the services. +::: + +## Table of contents +- [Setup](#setup) + - [1. Set up Packit integration](#1-set-up-packit-integration) + - [GitHub](#github) + - [GitLab](#gitlab) + - [Pagure](#pagure) + - [2. Approval](#2-approval) + - [3. Configuration](#3-configuration) + - [How to try that for real](#how-to-try-that-for-real) +- [Check that Packit works](#check-that-packit-works) +- [Retriggering](#retriggering) + +## Setup To start using Packit, you need to do three things: 1. set up integration (so Packit is notified about your activities and can provide feedback) @@ -22,7 +46,8 @@ To start using Packit, you need to do three things: 3. configure the wanted features -## 1. Set up Packit integration + +### 1. Set up Packit integration The integration is dependent on the service the upstream project is hosted on. In case you want to use Packit on your downstream repository for downstream jobs @@ -32,14 +57,14 @@ Just place your config file into the dist-git repository. Here are the supported git-forges: -### GitHub +#### GitHub The majority of Packit users host their projects on GitHub, therefore we focus mainly on supporting the GitHub App. All of our workflows are supported and tested on GitHub. We utilize the majority of new GitHub features that can be used in GitHub Apps. -#### How to set up Packit on GitHub +##### How to set up Packit on GitHub 1. Navigate to the ["Packit-as-a-Service" GitHub application](https://github.com/marketplace/packit-as-a-service). @@ -57,7 +82,7 @@ project settings. In the left sidebar, click "Integration & services" and you will see the application displayed there. -#### Staging instance +##### Staging instance [Packit-as-a-Service-stg](https://github.com/apps/packit-as-a-service-stg) GitHub App runs the latest code. It can be used to verify the latest changes until they get @@ -90,7 +115,7 @@ install the app [here](https://github.com/apps/packit-as-a-service-stg). Thank y ![Packit GitHub application: Staging instance](img/guide/guide_github_app_stg.png) -### GitLab +#### GitLab GitLab support is mainly experimental and is influenced by the presence of CentOS Stream source-git workflow. **We do not verify** the functionality of the GitLab support on a day-to-day basis as we do with the GitHub App. @@ -103,7 +128,7 @@ You can use Packit on any GitLab instance, if: but let us know if you need any other instance to be supported.) -#### How to set up Packit on GitLab +##### How to set up Packit on GitLab GitLab doesn't have an app functionality, and we don't use the [Integrations](https://docs.gitlab.com/ee/user/project/integrations/overview.html) @@ -150,7 +175,7 @@ srpm_build: expire_in: 1 week ``` -### Pagure +#### Pagure We have rudimentary support for the Pagure instances since they are used in the downstream workflow. Packit cannot be set up as a CI (in the same sense as on GitHub or GitLab) on Pagure instances, @@ -159,7 +184,7 @@ The differences between GitHub/GitLab and Pagure APIs would result in many worka You can track the progress in the [related issue](https://github.com/packit/packit-service/issues/556) on GitHub. -## 2. Approval +### 2. Approval As a next step, you need to have a valid [Fedora Account System](https://fedoraproject.org/wiki/Account_System) account to be able to start using Packit Service in an upstream project. @@ -200,7 +225,7 @@ Besides that: you need to have write access to the repository. -## 3. Configuration +### 3. Configuration Packit uses a configuration file to let Packit know what to do, when to do it and how. As a format, it uses YAML and here are all the valid names: @@ -232,7 +257,7 @@ In the following parts, we will cover some basic concepts used in the Packit con More details can be found on a dedicated [configuration page](/docs/configuration/). -### Basic configuration +#### Basic configuration You need to provide some basic information to let Packit understand your project and package. You can use `packit init` command (when [running Packit locally](/docs/cli/)) to get a basic structure. @@ -260,7 +285,7 @@ We know that every project is a bit different and Packit can't guess everything so you can (re)define various other options. The full list can be found [here](/docs/configuration/#top-level-keys). -#### Version handling +##### Version handling There are a few version-related config options you might need to set: * [`upstream_tag_template`](/docs/configuration/#upstream_tag_template): @@ -272,7 +297,7 @@ There are a few version-related config options you might need to set: * [`update_release`](/docs/configuration/#update_release): Whether to modify release when creating SRPM. -### Jobs +#### Jobs Packit's feature set is really wide and does not need to be used as a whole pipeline. To let user decide what and when should run, Packit uses concept of so-called `jobs`. @@ -309,7 +334,7 @@ Another useful feature are [aliases](/docs/configuration/#aliases) used to avoid hardcoded values that changes when there is a new distribution release. -### Available jobs +#### Available jobs * [`copr_build`](/docs/configuration/upstream/copr_build): An RPM build triggered for pull-requests, new branch commits or releases. (Can be used to verify that package is buildable, @@ -327,7 +352,7 @@ hardcoded values that changes when there is a new distribution release. More about the jobs and how to tweak them can be found on a [configuration page](/docs/configuration#jobs). -### Actions +#### Actions Actions are a way how to redefine or tweak the Packit's workflows. These are user-defined commands that can replace a part of Packit's job (e.g. to get version, or to create a tarball) @@ -336,7 +361,7 @@ or are run in a particular step as a hook (with no action run by default). Take a look at the tables [here](/docs/configuration/actions/) to know what actions are available for each job. -### Users +#### Users Packit checks if the user has sufficient permissions to complete a job (this depends on the job type). For this reason the profile of a Packit user has to be accessible. @@ -504,11 +529,6 @@ The button is available only for users with write permissions to the repository. ### Comments for downstream jobs See [Retriggering](./fedora-releases-guide/dist-git-onboarding#retriggering) in Dist-git repository onboarding. -## Packit handles Fedora updates for you. - -So you already have a `jobs` section in your config. Let's extend it with another -jobs that will handle the Fedora updates: `propose_downstream`/`pull_from_upstream`, `koji_build` and `bodhi_udpate`. -These are explained in detail in our [release guide](/docs/fedora-releases-guide). And that's about it. Now you should be able to use the core features of the Packit. If you have any questions, feel free to [reach out to us](/#contact).