Skip to content

Commit

Permalink
Restructure both upstream and downstream guides
Browse files Browse the repository at this point in the history 
- add manual TOCs with most important section links
- make the structure consistent
- link the downstream one more visibly from upstream one
  • Loading branch information
@lbarcziova
lbarcziova committed Feb 27, 2024
1 parent 7ee37b5 commit d20162b
Show file tree
Hide file tree
Showing 5 changed files with 185 additions and 102 deletions.
3 changes: 3 additions & 0 deletions docs/configuration/downstream/koji_build.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/configuration/downstream/pull_from_upstream.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
206 changes: 133 additions & 73 deletions docs/fedora-releases-guide/dist-git-onboarding.md
View file
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -35,17 +82,71 @@ 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
Current default behaviour of the release syncing results in having divergent dist-git branches. If you want to avoid this,
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:
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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).
Expand All @@ -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
Expand All @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/fedora-releases-guide/index.md
View file
Original file line number Diff line number Diff line change
@@ -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

Expand All @@ -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.

:::

Expand Down
Loading

0 comments on commit d20162b

Please sign in to comment.