From 9da19632de33edf9f7eb6b691624a0721fc04544 Mon Sep 17 00:00:00 2001 From: Freya Gustavsson Date: Sep 16 2025 11:53:43 +0000 Subject: [PATCH 1/4] fix: AsciiDoc headers Changes all HTML headers one level higher to ensure that there is always one h1 header at the top of the pages. Fixes: - Strange horizontal line at the top of each page - Browser tab showing "Untitled" - Table of contents indentation Signed-off-by: Freya Gustavsson --- diff --git a/modules/developer_guide/pages/auth.adoc b/modules/developer_guide/pages/auth.adoc index 2f82950..6f97806 100644 --- a/modules/developer_guide/pages/auth.adoc +++ b/modules/developer_guide/pages/auth.adoc @@ -1,4 +1,4 @@ -== Authentication += Authentication :figure-caption!: Fedora applications that require authentication should support @@ -10,7 +10,7 @@ https://github.com/fedora-infra/fasjson/[fasjson] as read-only API, https://openid.net/connect/[OpenID Connect], https://tools.ietf.org/html/rfc6749[OAuth 2.0], and more. -=== Authentication +== Authentication All new applications should use OpenID Connect for user authentication. @@ -42,9 +42,9 @@ that the "openid" scope is requested]. Failing to do so will result in undefined behavior. ==== -=== Libraries +== Libraries -==== Authlib +=== Authlib https://authlib.org/[Authlib] is a Python library to build OAuth and OpenID Connect servers and clients. It has integration layers for Flask @@ -53,13 +53,13 @@ layers for Requests, HTTPX, Starlette and FastAPI. As a client app authenticating with OpenID Connect, it is most useful if several authentication providers are to be supported (such as social networks). -==== Flask-OIDC +=== Flask-OIDC https://github.com/fedora-infra/flask-oidc/[Flask-OIDC] is a Flask extension that makes using Authlib easier when using Flask with only one authentication provider (such as Fedora's identity provider). -==== OAuthLib +=== OAuthLib https://oauthlib.readthedocs.io/[OAuthLib] is a low-level implementation of OAuth 2.0 with OpenID Connect support. It does not tie itself to a @@ -70,7 +70,7 @@ interested in the https://oauthlib.readthedocs.io/en/latest/oauth2/clients/client.html[OAuth client] sub-package. -==== Requests-OAuthlib +=== Requests-OAuthlib https://requests-oauthlib.readthedocs.io/[Requests-OAuthlib] uses the http://docs.python-requests.org/[Requests] library with OAuthLib to @@ -78,7 +78,7 @@ provide an easy-to-use interface for OAuth 2.0 clients. If you need to add support to an application that doesn't have an extension for OAuthLib, you should use this library. -==== Flask-OAuthlib +=== Flask-OAuthlib https://flask-oauthlib.readthedocs.io/en/latest/[Flask-OAuthlib] is a Flask extension that builds on top of Requests-OAuthlib. It comes with @@ -88,20 +88,20 @@ directory of the repository. Flask applications within Fedora Infrastructure should use this extension unless there is a good reason not to (and that reason is documented here). -==== Pyramid-OAuthLib +=== Pyramid-OAuthLib https://github.com/tilgovi/pyramid-oauthlib[Pyramid-OAuthLib] is a Pyramid extension that uses OAuthlib. It does not appear to be actively maintained, but it is a reasonable starting point for our few Pyramid applications. -==== Mozilla-Django-OIDC +=== Mozilla-Django-OIDC https://github.com/mozilla/mozilla-django-oidc[Mozilla-Django-OIDC] is a Django extension for OpenID Connect. -=== Flow +== Flow This is a schema of a classic OpenID Connect authentication flow. @@ -109,7 +109,7 @@ This is a schema of a classic OpenID Connect authentication flow. image::AAA-Flow.svg[OIDC authentication flow] -=== FASJSON +== FASJSON The account data is stored in FreeIPA, but it is made available to users and applications through http://fasjson.fedoraproject.org[FASJSON] as a REST API diff --git a/modules/developer_guide/pages/ci.adoc b/modules/developer_guide/pages/ci.adoc index 22a1f90..bdff45f 100644 --- a/modules/developer_guide/pages/ci.adoc +++ b/modules/developer_guide/pages/ci.adoc @@ -1,4 +1,4 @@ -== CI (Continuous Integration) += CI (Continuous Integration) CI is an important part of development and it helps to keep the project maintainable. Fedora infra is using https://fedora.softwarefactory-project.io/zuul/status[Fedora CI]. @@ -7,15 +7,15 @@ This CI is hosted by Fedora and open to any Fedora project. Fedora Infra also maintains their own https://pagure.io/fedora-infra/zuul[zuul jobs repository]. This repository is open to contributions and every project in Fedora can use these jobs. -=== Setting up CI for new project +== Setting up CI for new project -==== Pagure +=== Pagure There is an https://fedoraproject.org/wiki/Zuul-based-ci#How_to_attach_a_Pagure_repository_on_Zuul[official guide] for new repositories that want to be added https://fedora.softwarefactory-project.io/zuul/status[Fedora CI]. -==== Github +=== Github https://github.com/fedora-infra[Fedora Infra organization] on Github already has the corresponding application installed. To have it enabled for the project you need to diff --git a/modules/developer_guide/pages/code-style.adoc b/modules/developer_guide/pages/code-style.adoc index 7b3b6e5..a526b96 100644 --- a/modules/developer_guide/pages/code-style.adoc +++ b/modules/developer_guide/pages/code-style.adoc @@ -1,10 +1,10 @@ -== Code Style += Code Style We attempt to maintain a consistent coding style across projects so contributors do not have to keep dozens of different styles in their head as they move from project to project. -=== Python +== Python We follow the https://www.python.org/dev/peps/pep-0008/[PEP8] style guide for Python. Projects should make it easy to check new code for @@ -21,7 +21,7 @@ example, the maximum line length might vary. The test suite should enforce this. ==== -==== Linting +=== Linting Ruff is capable of running a lot of rules to lint the source code. The categories of rules to be run can be selecting by @@ -34,7 +34,7 @@ https://github.com/fedora-infra/cookiecutter-python-app/blob/main/%7B%7B%20cooki file. -==== Auto formatting +=== Auto formatting The https://black.readthedocs.io/[Black] tool is an automatic code formatter for Python. From the website: @@ -56,12 +56,12 @@ saving. The documentation has instructions to set it up in Vim and in VS Code (and in Emacs). -==== Enforcement +=== Enforcement Projects should automatically enforce code style. How a project does so is up to the maintainers, but several good options are documented here. -===== Tox +==== Tox https://tox.wiki[Tox] is an excellent way to test style. For example, adding the following snippet to your `tox.ini` file will run `ruff` as @@ -85,7 +85,7 @@ commands = Remember to add `lint` and `format` to your Tox `envlist`. -===== Pre-Commit +==== Pre-Commit https://pre-commit.com/[Pre-commit] is a git hook that will run before Git stores a commit. It has the ability to run a set of tools against the files @@ -106,7 +106,7 @@ https://github.com/fedora-infra/cookiecutter-python-app/blob/5ad9adb75600ac13fc6 file. -=== Javascript +== Javascript Javascript files should be formatted using the https://prettier.io/[prettier] code formatter. It has support for many diff --git a/modules/developer_guide/pages/db.adoc b/modules/developer_guide/pages/db.adoc index 6837aa7..4ecb106 100644 --- a/modules/developer_guide/pages/db.adoc +++ b/modules/developer_guide/pages/db.adoc @@ -1,8 +1,8 @@ -== Databases += Databases We use PostgreSQL throughout Fedora Infrastructure. -=== Bi-directional Replication +== Bi-directional Replication https://www.enterprisedb.com/docs/bdr/latest/[Bi-directional replication] (BDR) is a project that adds asynchronous multi-master @@ -16,11 +16,11 @@ system administrators. Applications need to take several things into account when considering whether or not to use BDR. -==== Primary Keys +=== Primary Keys All tables need to have primary keys. -==== Conflicts +=== Conflicts BDR does not use any consensus algorithm or locking between nodes so writing to multiple masters can result in @@ -30,7 +30,7 @@ carefully consider each one and be prepared to handle them. Some conflicts are handled automatically, while others can result in a deadlock that requires manual intervention. -==== Global DDL Lock +=== Global DDL Lock BDR uses a https://www.enterprisedb.com/docs/bdr/latest/ddl/[global DDL @@ -56,7 +56,7 @@ def run_migrations_offline(): # If the configuration indicates this script is for a Postgres-BDR database, # then we need to acquire the global DDL lock before migrating. postgres_bdr = config.get_main_option('offline_postgres_bdr') - if postgres_bdr is not None and postgres_bdr.strip().lower() == 'true': + if postgres_bdr is not None and postgres_bdr.strip().lower() = 'true': _log.info('Emitting SQL to allow for global DDL locking with BDR') context.execute('SET LOCAL bdr.permit_ddl_locking = true') context.run_migrations() @@ -100,7 +100,7 @@ Be aware that long-running migrations will hold the global lock for the entire migration and while the global lock is held by a node, no other nodes may perform any DDL or make any changes to rows. -==== DDL Restrictions +=== DDL Restrictions BDR has a set of https://www.enterprisedb.com/docs/bdr/latest/ddl/#bdr-ddl-command-handling-matrix=[DDL diff --git a/modules/developer_guide/pages/dev-environment.adoc b/modules/developer_guide/pages/dev-environment.adoc index b78c29b..6f8f610 100644 --- a/modules/developer_guide/pages/dev-environment.adoc +++ b/modules/developer_guide/pages/dev-environment.adoc @@ -1,4 +1,4 @@ -== Development Environment += Development Environment In order to make contributing easy, all projects should have an automated way to create a development environment. This might be as @@ -6,14 +6,14 @@ simple as a Python virtual environment, or it could be a virtual machine or container. This document provides guidelines for setting up development environments. -=== Ansible +== Ansible https://www.ansible.com/[Ansible] is used throughout Fedora Infrastructure to automate tasks. If the project requires anything more than a Python virtual environment to be set up, you should use Ansible to automate the setup. -=== Vagrant +== Vagrant https://vagrantup.com/[Vagrant] is a tool to provision virtual machines. It allows you to define a base image (called a "box"), virtual machine @@ -44,7 +44,7 @@ https://docs.ansible.com/ansible/latest/user_guide/playbooks_reuse_roles.html[An documentation. ==== -Below is a Vagrantfile that provisions a Fedora 34 virtual machine, updates it, +Below is a Vagrantfile that provisions a Fedora 34 virtual machine, updates it, mounts the current folder as `/home/vagrant/devel`, and runs an Ansible playbook from `devel/ansible` on it. You can place it in the root of your repository as `Vagrantfile.example` and instruct users to diff --git a/modules/developer_guide/pages/documentation.adoc b/modules/developer_guide/pages/documentation.adoc index dc9f524..7dab58f 100644 --- a/modules/developer_guide/pages/documentation.adoc +++ b/modules/developer_guide/pages/documentation.adoc @@ -1,4 +1,4 @@ -== Documentation += Documentation Since Fedora contributors live around the world and don't often have the opportunity to meet in person, it's important to maintain up-to-date @@ -25,7 +25,7 @@ When adding new documentation or cleaning up existing documentation, please follow the guidelines below. ==== -=== Style +== Style Sphinx supports three different documentation styles. By default, Sphinx expects ReStructuredText. However, it has included an extension to @@ -36,13 +36,13 @@ style] since version 1.3. The style of the documentation blocks is left up to the individual project, but it should document the choice and be consistent. -=== Introduction +== Introduction The project introduction should be easy to find - preferably it should be the documentation's index page. It should provide an overview of the project and should be easy for a complete new-comer to understand. -=== User Guide +== User Guide Have a clear user guide that covers most, if not all, features of the project as well as potential use cases. Keep in mind that your users may @@ -51,18 +51,18 @@ project's web interface, while others are interested in the API and the documentation should make it easy for both types of users to find the documentation for them. -=== Contributor Guide +== Contributor Guide Documenting how to start contributing makes it much easier for new contributors to get involved. This is a good place to cover the expectations about code style, documentation, tests, etc. -=== API Documentation +== API Documentation All APIs should be documented. Users should never have to consult the source code to use the project's API. -==== Python +=== Python Python API documentation is easily generated by using the http://www.sphinx-doc.org/en/stable/tutorial.html#autodoc[autodoc] @@ -83,7 +83,7 @@ arguments, and example usage if appropriate. http://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-python-objects[cross-referencing] feature. This will generate links between objects in the documentation. -==== HTTP APIs +=== HTTP APIs Many projects provide an HTTP-based API. Use https://sphinxcontrib-httpdomain.readthedocs.io/en/stable/[sphinxcontrib-httpdomain] @@ -98,7 +98,7 @@ Flask endpoints. After that, all you need to do is use the `autoflask` ReStructuredText directive. -=== Release Notes and ChangeLog +== Release Notes and ChangeLog The release notes (or the changelog) can be managed using https://pypi.org/project/towncrier/[towncrier]. It can build a release diff --git a/modules/developer_guide/pages/frameworks.adoc b/modules/developer_guide/pages/frameworks.adoc index 633e7ab..ee1d190 100644 --- a/modules/developer_guide/pages/frameworks.adoc +++ b/modules/developer_guide/pages/frameworks.adoc @@ -1,12 +1,12 @@ -== Frameworks and Tools += Frameworks and Tools We attempt to use the same set of frameworks and tools across projects to minimize the number of frameworks developers must keep in their heads. -=== Python +== Python -==== Flask +=== Flask http://flask.pocoo.org/[Flask] is a web microframework for Python based on http://werkzeug.pocoo.org/[Werkzeug] and @@ -26,20 +26,20 @@ Flask is designed to be extensible, so it's common to use extensions with the core flask library. A few common extensions are documented below. -===== Flask-SQLAlchemy +==== Flask-SQLAlchemy http://flask-sqlalchemy.pocoo.org/[Flask-SQLAlchemy] integrates Flask with SQLAlchemy. It will configure a scoped session for you, set up a declarative base class, and provide a convenient `flask_sqlalchemy.BaseQuery` sub-class for you. -===== SQLAlchemy Helpers +==== SQLAlchemy Helpers https://github.com/fedora-infra/sqlalchemy-helpers/[SQLAlchemy-Helpers] is an alternative to using Flask-SQLAlchemy if you need your models to be usable from outside Flask. -==== SQLAlchemy +=== SQLAlchemy http://www.sqlalchemy.org/[SQLAlchemy] is an SQL toolkit and Object Relational Mapper. It provides a core set of tools (surprisingly called diff --git a/modules/developer_guide/pages/getting-started.adoc b/modules/developer_guide/pages/getting-started.adoc index 475cda1..42b95ee 100644 --- a/modules/developer_guide/pages/getting-started.adoc +++ b/modules/developer_guide/pages/getting-started.adoc @@ -1,4 +1,4 @@ -== Getting Started += Getting Started :toc: right This document is intended to guide you through your first contribution @@ -6,7 +6,7 @@ to a Fedora Infrastructure project. It assumes you are already familiar with the https://git-scm.com/[git] version control system and the https://www.python.org/[Python] programming language. -=== Development Environment +== Development Environment The Fedora Infrastructure team uses https://www.ansible.com/[Ansible] and https://vagrantup.com/[Vagrant] to set up development environments @@ -37,7 +37,7 @@ the latest updates, and then SSH into the virtual machine. Individual projects will provide detailed instructions for their particular setup. -=== Finding a Project +== Finding a Project Fedora Infrastructure applications are either on https://github.com/[GitHub] in the diff --git a/modules/developer_guide/pages/messaging.adoc b/modules/developer_guide/pages/messaging.adoc index 2508708..512cc4f 100644 --- a/modules/developer_guide/pages/messaging.adoc +++ b/modules/developer_guide/pages/messaging.adoc @@ -1,4 +1,4 @@ -== Messaging += Messaging Fedora uses many event-driven services triggered by messages. In the past, this was done with ZeroMQ and @@ -9,7 +9,7 @@ Python applications. This documentation outlines the policies for sending and receiving messages. To learn how to send and receive messages, see the https://fedora-messaging.readthedocs.io/en/latest[fedora-messaging documentation]. -=== Broker URLs +== Broker URLs The broker consists of multiple RabbitMQ nodes. They are available through the proxies at `amqps://rabbitmq.fedoraproject.org` for @@ -19,7 +19,7 @@ VPN, but users outside need to use a separate virtual host. Consult the https://fedora-messaging.readthedocs.io/en/latest/user-guide/quick-start.html#fedora-s-public-broker[fedora-messaging documentation] for details on how to connect externally. -=== Identity +== Identity In order to help with debugging, clients must configure the https://fedora-messaging.readthedocs.io/en/latest/user-guide/configuration.html#client-properties[client_properties] @@ -27,7 +27,7 @@ option to include their application name under the `app` key. Clients should include the application version, if possible, in the `app_version` key. -=== Authentication +== Authentication When applications are deployed, clients must authenticate with the message broker over a TLS connection using x509 certificates. There are @@ -43,7 +43,7 @@ and must match the name of the user you create in AMQP. Consult the Authorization section below for details on creating users, queues, and bindings. -=== Authorization +== Authorization The message broker can use https://www.rabbitmq.com/vhosts.html[virtual hosts] to allow multiple applications to use the broker. The general @@ -52,7 +52,7 @@ authorization policy outlined below. If your application is using a different virtual host for private messaging (for example, your application uses Celery), different authorization rules apply. -==== pubsub Virtual Host +=== pubsub Virtual Host AMQP clients do not have permission to create exchanges, queues, or bindings. However, they can and should declare the exchanges, queues, @@ -109,7 +109,7 @@ you want the username to match in staging too, you should use: username: "bodhi{{ env_suffix}}" .... -===== Bindings +==== Bindings Messages from AMQP publishers are sent to the `amq.topic` exchange. Messages from ZeroMQ publishers are sent to the `zmq.topic` exchange. In diff --git a/modules/developer_guide/pages/openshift.adoc b/modules/developer_guide/pages/openshift.adoc index 2ad5890..686558f 100644 --- a/modules/developer_guide/pages/openshift.adoc +++ b/modules/developer_guide/pages/openshift.adoc @@ -1,4 +1,4 @@ -== OpenShift += OpenShift OpenShift is a Kubernetes-based platform for running containers. The upstream project, https://www.openshift.org/[OpenShift Origin], is what @@ -6,7 +6,7 @@ Red Hat bases the https://www.openshift.com/[OpenShift Container Platform] product on. Fedora runs OpenShift Container Platform rather than OpenShift Origin. -=== Getting Started +== Getting Started If you've never used OpenShift before a good place to start is with https://www.openshift.org/minishift/[MiniShift], which deploys OpenShift @@ -14,7 +14,7 @@ Origin in a virtual machine. See the following for some: xref:openshift_bestpractices.adoc[Openshift Best Practices] -=== OpenShift in Fedora Infrastructure +== OpenShift in Fedora Infrastructure Fedora has two OpenShift deployments: https://console-openshift-console.apps.ocp.stg.fedoraproject.org/[Staging OpenShift] and @@ -28,13 +28,13 @@ mainly due to the lack of HTTP/2 support (at the time of this writing). Additionally, users are not allowed to alter configuration, roll out new deployments, run builds, etc. in the web UI or CLI. -==== Web User Interface +=== Web User Interface Some of the web user interface is currently non-functional since it requires HTTP/2. The rest is locked down to be read-only, making it of limited usefulness. -==== Command-line Interface +=== Command-line Interface Although the CLI is also locked down to be read only, it is possible to view logs and request debugging containers from os-control01 or your local machine. For @@ -51,7 +51,7 @@ librariesio2fedmsg-28-bfj52 1/1 Running 522 28d $ oc logs librariesio2fedmsg-28-bfj52 .... -==== Deploying Your Application +=== Deploying Your Application Applications are deployed to OpenShift using https://pagure.io/fedora-infra/ansible/blob/main/f/playbooks/openshift-apps[Ansible @@ -119,5 +119,3 @@ spec: storageClassName: 'ocs-storagecluster-cephfs' volumeMode: Filesystem ---- - - diff --git a/modules/developer_guide/pages/openshift_bestpractices.adoc b/modules/developer_guide/pages/openshift_bestpractices.adoc index 2467c61..989d22f 100644 --- a/modules/developer_guide/pages/openshift_bestpractices.adoc +++ b/modules/developer_guide/pages/openshift_bestpractices.adoc @@ -1,10 +1,10 @@ -== Fedora Infra Openshift Best Practices += Fedora Infra Openshift Best Practices This document aims to encourage the use of best practices related to application development and deployment of containerised applications on Kubernetes/Openshift. NOTE: Its a large topic, can't possibly cover every element in detail, but should be enough to act as a primer. NOTE: Should these best practices be something maintained by the kube-sig? If so should we attempt to resurrect it? -=== References/Resources/Further Reading +== References/Resources/Further Reading - [1] Fedora Infra Flock Hackfest https://hackmd.io/HxpzTNpITfu0OYmOGRApiw - [2] Kubernetes health checks https://blog.kubecost.com/blog/kubernetes-health-check/ - [3] Prometheus metrics format https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md#text-based-format @@ -20,7 +20,7 @@ NOTE: Should these best practices be something maintained by the kube-sig? If so - [13] Enabling monitoring for user defined projects: https://docs.openshift.com/container-platform/4.8/monitoring/enabling-monitoring-for-user-defined-projects.html -=== Fedora Infra Clusters +== Fedora Infra Clusters Fedora Infra currently manages the following three Openshift clusters: - Staging (Self Hosted in RDU3, deploy apps via ansible): https://console-openshift-console.apps.ocp.stg.fedoraproject.org/ @@ -30,7 +30,7 @@ Fedora Infra currently manages the following three Openshift clusters: Access to the clusters is managed via the Fedora account system (FAS). All Fedora users may authenticate, but access to each project is managed on an app per app basis. Open a ticket at [7] requesting access to a particular app, but ensure you first get approval from the existing app owners. -=== Building containers +== Building containers - Use Podman over Docker when developing locally. - How containers are currently built and updated inside Fedora Infra? Since the retirement of OSBS, they arn't automated iirc? - Use a service to build the containers Konflux?, Imagebuilder?, quay.io? iirc, the plan is that we will use Konflux to do our container building going forward, we're starting off looking at configuring the Konflux instance to build artifacts. @@ -68,31 +68,31 @@ RUN rm -f 2 \ - Limit container privileges. By default containers which run as root cannot run in Openshift without elevated privileges and will not start the container without these privileges in place for the ServiceAccount. If you need root access, don't run this part of the application in Openshift at all (if possible). -=== ImageStream +== ImageStream - Changes to an image which the imagestream points to will automatically cause a roll out to applications which use this imagestream. - This provides a single change to the base fedora image, to cause a roll out of all applications on the clusters to the latest image. -=== Handling Dependencies +== Handling Dependencies - All application dependencies should be version pinned and locked within the container to aid reaching reproducible builds. Make use of a dependency management system as per the language best practices. - If a container image is vital to Fedora, perhaps dependencies could also be stored in a local pip/gem/nodejs/whatever/rpm repository to enable building? -=== DeploymentConfig migration to Deployments +== DeploymentConfig migration to Deployments - DeploymentConfig is depreciated and is being phased out (very) soonish, we should replace all DeploymentConfigs with Deployments. - This is being tracked with a board on pagure: https://pagure.io/fedora-infrastructure/issue/12142 - We should consider breaking this epic up into smaller tickets and creating individual tickets to track each instance of DeploymentConfig deployed app in Fedora Infra. -=== Deploy/use ACS (redhat product) that looks inside containers and tells you what's in it and what the security issues are. +== Deploy/use ACS (redhat product) that looks inside containers and tells you what's in it and what the security issues are. - The registry quay.io has such features already, perhaps use this instead? One less service we need to run and maintain. -=== Security +== Security - Do secure access to application using something like the `oauth-proxy` [5] especially if working with user data. - When hosting an app within Openshift, using the oauth-proxy might be a better way to secure the app rather than using systems like flask-oidc. -=== Monitoring applications +== Monitoring applications - Do expose endpoints in the application to aid in monitoring [2]. -- Liveness probes to detect a non-responsive application -- Readiness probes to ensure that a service is ready to receive traffic @@ -145,14 +145,14 @@ spec: - Hook into the Openshift monitoring [13] stack and then use prometheus exporters to push metrics and alerts to zabbix maybe (blocked until Zabbix is more widely used within Fedora Infra). -=== Preferred source control managers +== Preferred source control managers - github - pagure - gitlab - forgejo -=== Preferred methods of deploying applications within Fedora Infra +== Preferred methods of deploying applications within Fedora Infra - Fedora Infra uses ansible playbooks/roles as the primary means to deploy applications. - An ansible role should be developed to deploy the app within Fedora Infra. - Private variables should be stored in the ansible-private repo. @@ -160,7 +160,7 @@ spec: - Alternative is to perhaps develop a Helm chart or Ansible based Kubernetes Operator [11] to do this work. -=== Limits, requests +== Limits, requests - When deploying the application, ensure to add resource requests and limits to the Deployment [10] see example: ``` apiVersion: apps/v1 @@ -199,9 +199,8 @@ spec: - If a Container exceeds its memory request, it is likely that its Pod will be evicted whenever the node runs out of memory. -=== Scaling +== Scaling - When designing an app ensure the following: -- It is capable of recovering from a restart/crash. (eg: killed, moved and or crashed containers) -- Add ability to scale app in the architecture and design eg: multiple instances behind a load balancer. In Kubernetes Deployments: `replicas: 1` -- Ensure the app includes high availability in its design, eg: 3 instances ensuring the application stays up even if one instance is down. - diff --git a/modules/developer_guide/pages/security_policy.adoc b/modules/developer_guide/pages/security_policy.adoc index a275a11..b620dcc 100644 --- a/modules/developer_guide/pages/security_policy.adoc +++ b/modules/developer_guide/pages/security_policy.adoc @@ -1,4 +1,4 @@ -== Fedora Infrastructure Application Security Policy += Fedora Infrastructure Application Security Policy This document sets out the security requirements applications must meet at a minimum to pass the security audit, and as such run in Fedora @@ -6,7 +6,7 @@ Infrastructure. This is by no means a comprehensive list, but it is a minimum set. -=== General +== General The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this diff --git a/modules/developer_guide/pages/sops.adoc b/modules/developer_guide/pages/sops.adoc index d83a0af..396ae2c 100644 --- a/modules/developer_guide/pages/sops.adoc +++ b/modules/developer_guide/pages/sops.adoc @@ -1,5 +1,5 @@ [[develop-sops]] -== Developing Standard Operating Procedures += Developing Standard Operating Procedures When a new application is deployed in Fedora, it is critical that you add a standard operating procedure (SOP) for it. This documents how the @@ -11,7 +11,7 @@ You can modify this documentation or any of the current `sops` by making a https://docs.pagure.org/pagure/usage/pull_requests.html[pull request] to the https://pagure.io/infra-docs-fpo[Pagure project]. -=== Adding a Standard Operating Procedure +== Adding a Standard Operating Procedure To add a standard operating procedure, create a new https://asciidoc-py.github.io/userguide.html[AsciiDoc] file in @@ -24,7 +24,7 @@ file]. SOP text file names should use lowercase with dashes. Describe the service and end the page name with ".rst". -=== Stuff every SOP should have +== Stuff every SOP should have Here's the template for adding a new SOP: @@ -60,7 +60,7 @@ You can even have sub-sections. If a current SOP does not follow this general template, it should be updated to do so. -=== SOP Formatting +== SOP Formatting SOPs are written in https://asciidoc-py.github.io/userguide.html[AsciiDoc]. To learn about the spec, read: @@ -75,7 +75,7 @@ The format is somewhat simple if you remember a few key points: * Sections are prefixed by "=". The convention is that the number of "=" corresponds to level of section starting with title with only one. * Block like `Note` are delimited by "...." bellow and above the text that -should be in the note. +should be in the note. * Use literal blocks for code and command sections. Add "...." above and bellow the block. The "...." is not the only delimiter you can use, diff --git a/modules/developer_guide/pages/source_control.adoc b/modules/developer_guide/pages/source_control.adoc index dd68c1a..232d20d 100644 --- a/modules/developer_guide/pages/source_control.adoc +++ b/modules/developer_guide/pages/source_control.adoc @@ -1,6 +1,6 @@ -== Source Control += Source Control -=== Pagure +== Pagure If your project is hosted on Pagure, you should go to the project settings and set "Project tags" to have `fedora-infra` in it. This way diff --git a/modules/developer_guide/pages/writing-tests.adoc b/modules/developer_guide/pages/writing-tests.adoc index 93ac9fa..7864ea6 100644 --- a/modules/developer_guide/pages/writing-tests.adoc +++ b/modules/developer_guide/pages/writing-tests.adoc @@ -1,4 +1,4 @@ -== Tests += Tests Tests make development easier for both veteran project contributors and newcomers alike. Most projects use the @@ -18,7 +18,7 @@ the feature or bugfix works. This makes the review process much easier since it allows the reviewer to run your code with very little effort, and it lets developers know when they break your code. -=== Test Organization +== Test Organization Having a standard test layout makes it easy to find tests. When adding new tests, follow the following guidelines: @@ -47,7 +47,7 @@ here and follow the established conventions for that project until that happens. ==== -=== Test Runners +== Test Runners Projects should include a way to run the tests with ease locally and the steps to run the tests should be documented. This should be the same way @@ -77,7 +77,7 @@ http://nose2.readthedocs.io/en/latest/[nose2]. ==== [[tox-config]] -=== Tox +== Tox https://pypi.python.org/pypi/tox[Tox] is an easy way to run your project's tests (using a Python test runner) using multiple Python @@ -93,7 +93,7 @@ forbidden licenses, and builds the documentation with the `warnings treated as errors` Sphinx flag enabled. -=== Coverage +== Coverage https://pypi.python.org/pypi/coverage/[coverage] is a good way to collect test coverage statistics. @@ -144,7 +144,7 @@ it from your coverage report. Remember to leave a comment explaining why it's excluded! ==== -=== Licenses +== Licenses The https://pypi.org/project/liccheck/[liccheck] checker can verify that every dependency in your project has an acceptable license. The @@ -167,7 +167,7 @@ against https://github.com/fedora-infra/shared[the shared repo]. You can automate the license check by running the shell script in Tox. -=== Security +== Security The https://pypi.org/project/bandit/[bandit] checker is designed to find common security issues in Python code. diff --git a/modules/release_guide/pages/architecture.adoc b/modules/release_guide/pages/architecture.adoc index 5cb2ca0..08c190e 100644 --- a/modules/release_guide/pages/architecture.adoc +++ b/modules/release_guide/pages/architecture.adoc @@ -1,5 +1,5 @@ [[architecture]] -== Fedora Release Engineering Architecture += Fedora Release Engineering Architecture Here you will find an index of documentation that describes the Fedora Release Engineering Architecture. The goal of this is to provide an @@ -7,6 +7,6 @@ overview of the environment and various systems that are used to build it as a reference to members of the Fedora Community as well as materials to help prospective Release Engineering Community members. -=== Architecture Documents +== Architecture Documents layered_image_build_service workflow_automation diff --git a/modules/release_guide/pages/contributing.adoc b/modules/release_guide/pages/contributing.adoc index 2ba4b57..285134c 100644 --- a/modules/release_guide/pages/contributing.adoc +++ b/modules/release_guide/pages/contributing.adoc @@ -1,4 +1,4 @@ -== Fedora Release Engineering Contributing Guide += Fedora Release Engineering Contributing Guide Fedora Release Engineering works with many different utilities that are maintained in respective upstream locations. Fedora Release Engineering @@ -14,7 +14,7 @@ https://pagure.io/pagure[Pagure]. If you would like to contribute to something in this repository, please reference the `contributing-to-releng` section. -=== Contributing to releng +== Contributing to releng In order to contribute to the releng http://www.git-scm.com[git] repository (where the source reStructured Text version of these docs @@ -43,7 +43,7 @@ visit git's upstream and familiarize yourself. http://www.git-scm.com/ ==== -==== RelEng Developer Workflow +=== RelEng Developer Workflow There are many options for developer workflow, but the recommended workflow for Fedora releng repository is known as a @@ -109,13 +109,13 @@ $ git push origin my-topic-branch * Open a pull request in Rel Eng Pagure. https://pagure.io/releng/pull-requests -==== Developer Workflow Tips and Tricks +=== Developer Workflow Tips and Tricks Below are some Fedora Release Engineering Developer Workflow Tips and Tricks used by current members of the team in order to help assist with development. -===== pullupstream +==== pullupstream The following is an useful shell function to place in your `~/.bashrc` to help automate certain aspects of the developer workflow. It will @@ -169,7 +169,7 @@ $ git rebase main Current branch docs is up to date. .... -=== RelEng Upstream Tools +== RelEng Upstream Tools Fedora Release Engineering uses many tools that exist in their own upstream project space. These are tools that every Fedora Release @@ -178,9 +178,9 @@ feature needed, we should participate in the respective upstream to resolve the issue first before considering carrying a Fedora specific patch. -==== Tools List +=== Tools List -===== Tools Release Engineering is actively involved with upstream +==== Tools Release Engineering is actively involved with upstream Below are a set of tools that are centric to the Release Engineering team and our processes. We actively engage with upstreams of these @@ -197,7 +197,7 @@ product metadata * https://github.com/release-engineering/koji-containerbuild[koji-containerbuild] -Koji plugin to integrate OSBS with koji -===== Tools Release Engineering is actively mostly consumers of +==== Tools Release Engineering is actively mostly consumers of Below are the set of tools that the Release Engineering team either consumes directly or as the side effect of other tools in the Release diff --git a/modules/release_guide/pages/layered_image_build_service.adoc b/modules/release_guide/pages/layered_image_build_service.adoc index 9ea59eb..6a68813 100644 --- a/modules/release_guide/pages/layered_image_build_service.adoc +++ b/modules/release_guide/pages/layered_image_build_service.adoc @@ -1,4 +1,4 @@ -== Fedora Layered Image Build System += Fedora Layered Image Build System The Fedora Layered Image Build System aims to provide an new type of official binary artifact produced by Fedora. Currently, we produce two @@ -10,7 +10,7 @@ Base Image. This change introduces a new type of image, a https://github.com/docker/docker/[Docker] Layered Image, which is created from a Dockerfile and builds on top of that base image. -=== Layered Image Build Service Architecture +== Layered Image Build Service Architecture .... +------------------------------+ @@ -101,7 +101,7 @@ created from a Dockerfile and builds on top of that base image. [------------------------------------------------------------------------] .... -=== Layered Image Build System Components +== Layered Image Build System Components The main aspects of the Layered Image Build System are: @@ -155,11 +155,11 @@ process as the image will be tagged from the candidate docker registry into the production docker registry in order to "graduate" the image to stable. -==== Koji +=== Koji https://fedoraproject.org/wiki/Koji[Koji] is the Fedora Build System. -==== koji-containerbuild plugin +=== koji-containerbuild plugin The https://github.com/release-engineering/koji-containerbuild[koji-containerbuild] @@ -167,7 +167,7 @@ plugin integrates Koji and OSBS so that builds can be scheduled by koji and integrated into the build system with imports of metadata, logs, build data, and build artifacts. -==== OpenShift Origin v3 +=== OpenShift Origin v3 https://www.openshift.org/[OpenShift Origin v3] is an open source Container Platform, built on top of http://kubernetes.io/[kubernetes] @@ -176,7 +176,7 @@ aspects of the system needed including a build pipeline for Docker images with custom build profiles, image streams, and triggers based on events within the system. -==== Atomic Reactor +=== Atomic Reactor https://github.com/projectatomic/atomic-reactor[Atomic Reactor] is an utility which allows for the building of containers from within other @@ -184,14 +184,14 @@ containers providing hooks to trigger automation of builds as well as plugins providing automatic integration many other utilities and services. -==== osbs-client tools +=== osbs-client tools https://github.com/projectatomic/osbs-client[osbs-client] tools allow for users to access the build functionality of https://www.openshift.org/[OpenShift Origin v3] using a simple set of command line utilities. -==== docker-registry +=== docker-registry A https://docs.docker.com/registry/[docker-registry] is a stateless, highly scalable server side application that stores and lets you @@ -200,14 +200,14 @@ distribute Docker images. There are many different implementations of docker-registries, two main ones are supported by the Fedora Layered Image Build System. -===== docker-distribution +==== docker-distribution The https://github.com/docker/distribution/[docker-distribution] registry is considered the Docker upstream "v2 registry" such that it was used by upstream to implement the new version 2 specification of the docker-registry. -===== Fedora Production Registry +==== Fedora Production Registry Implementation details of this are still unknown at the time of this writing and will be updated at a later date. For the current status and @@ -215,7 +215,7 @@ implementation notes please visit the https://fedoraproject.org/wiki/Changes/FedoraDockerRegistry[FedoraDockerRegistry] page. -==== Taskotron +=== Taskotron https://taskotron.fedoraproject.org/[Taskotron] is an automated task execution framework, written on top of http://buildbot.net/[buildbot] @@ -223,7 +223,7 @@ that currently executes many Fedora automated QA tasks and we will be adding the Layered Image automated QA tasks. The tests themselves will be held in DistGit and maintained by the Layered Image maintainers. -==== RelEng Automation +=== RelEng Automation https://pagure.io/releng-automation[RelEng Automation] is an ongoing effort to automate as much of the RelEng process as possible by using @@ -232,20 +232,20 @@ https://fedora-messaging.readthedocs.io/en/stable/[Fedora messaging] via https://github.com/maxamillion/loopabull[Loopabull] to execute Ansible Playbooks based on Fedora messaging events. -==== Robosignatory +=== Robosignatory https://pagure.io/robosignatory[Robosignatory] is a Fedora messaging consumer that automatically signs artifacts and will be used to automatically sign docker layered images for verification by client tools as well as end users. -==== Future Integrations +=== Future Integrations In the future various other components of the https://fedoraproject.org/wiki/Infrastructure[Fedora Infrastructure] will likely be incorporated. -===== The New Hotness +==== The New Hotness https://github.com/fedora-infra/the-new-hotness[The New Hotness] is a https://fedora-messaging.readthedocs.io/en/stable/[Fedora messaging] consumer diff --git a/modules/release_guide/pages/overview.adoc b/modules/release_guide/pages/overview.adoc index 4a26351..25ab996 100644 --- a/modules/release_guide/pages/overview.adoc +++ b/modules/release_guide/pages/overview.adoc @@ -1,8 +1,8 @@ [[overview]] -== Fedora Release Engineering Overview += Fedora Release Engineering Overview [[overview-intro]] -=== Introduction +== Introduction The development of Fedora is a very open process, involving over a thousand package maintainers (along with testers, translators, @@ -56,26 +56,26 @@ exception bug process] * The https://fedoraproject.org/wiki/Bugs_and_feature_requests[Bugzilla system] -=== Final Release Checklist +== Final Release Checklist Various tasks need to be accomplished prior to a final Fedora release. Release Engineering is responsible for many of them, as outlined here. -==== Release Announcement +=== Release Announcement The https://fedoraproject.org/wiki/Docs_Project[Fedora Documentation Project] prepares release announcements for the final releases. A https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora%20Documentation&op_sys=Linux&target_milestone=---&bug_status=NEW&version=devel&component=release-notes&rep_platform=All&priority=normal&bug_severity=normal&assigned_to=relnotes%40fedoraproject.org&cc=&estimated_time_presets=0.0&estimated_time=0.0&bug_file_loc=http%3A%2F%2F&short_desc=RELNOTES%20-%20Summarize%20the%20release%20note%20suggestion%2Fcontent&comment=Provide%20details%20here.%20%20Do%20not%20change%20the%20blocking%20bug.&status_whiteboard=&keywords=&issuetrackers=&dependson=&blocked=151189&ext_bz_id=0&ext_bz_bug_id=&data=&description=&contenttypemethod=list&contenttypeselection=text%2Fplain&contenttypeentry=&maketemplate=Remember%20values%20as%20bookmarkable%20template&form_name=enter_bug[bug needs to be filed] for this two weeks before the final release date. -==== Mirror List Files +=== Mirror List Files A new set of mirror list files need to be created for the new release. Email mailto:mirror-admin@fedoraproject.org[Fedora Mirror Admins] to have these files created. These should be created at the Final Freeze point but may redirect to Rawhide until final bits have been staged. -=== Release Composing +== Release Composing Fedora “releases” can be built by anyone with a fast machine of proper arch and access to a package repository. All of the tools necessary to @@ -93,7 +93,7 @@ There is work currently being done to replace livecd-creator with https://github.com/rhinstaller/lorax/blob/master/src/sbin/livemedia-creator[livemedia-creator]. ==== -==== Pungi +=== Pungi https://pagure.io/pungi[Pungi] is the tool used to compose Fedora releases. It requires being ran in a chroot of the package set that it @@ -104,7 +104,7 @@ https://fedoraproject.org/wiki/Koji[Koji] build system provides a way to run tasks within chroots on the various arches, as well as the ability to produce yum repos of packages from specific collections. -==== Livecd-creator +=== Livecd-creator Livecd-creator is part of the https://fedoraproject.org/wiki/FedoraLiveCD[livecd-tools] package in @@ -112,7 +112,7 @@ Fedora and it is used to compose the live images as part of the Fedora release. It is also used to compose many of the custom https://spins.fedoraproject.org[Spins] or variants of Fedora. -=== Distribution +== Distribution Once a compose has been completed, the composed tree of release media, installation trees, and frozen @@ -121,19 +121,19 @@ synchronized with the Fedora mirror system. [[MirrorManager]] has some more details on the mirror system. Many of the images are also offered via BitTorrent as an alternative method of downloading. -==== Download Mirrors +=== Download Mirrors Depends on the Fedora Mirror System and infrastructure to populate them privately. -==== BitTorrent +=== BitTorrent BitTorrent is currently served by http://torrent.fedoraproject.org. Images are added to the system via this https://infrastructure.fedoraproject.org/infra/docs/docs/sysadmin-guide/sops/torrentrelease.rst[Standard Operating Procedure]. -=== Acknowledgements +== Acknowledgements This document was influenced by http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html[release diff --git a/modules/release_guide/pages/philosophy.adoc b/modules/release_guide/pages/philosophy.adoc index 5968c96..35fb9bc 100644 --- a/modules/release_guide/pages/philosophy.adoc +++ b/modules/release_guide/pages/philosophy.adoc @@ -1,7 +1,7 @@ [[philosophy]] -== Fedora Release Engineering Philosophy += Fedora Release Engineering Philosophy -=== Spirit of the Document +== Spirit of the Document Being an official part of Fedora means that it is composed and supported by Fedora Release Engineering (`releng`). Release Engineering bestows this status on @@ -16,7 +16,7 @@ terms, why they are important, and how we guarantee them. All parts of Fedora should strive to be meet all parts of being official at all times. -=== Open +== Open It goes without saying that Fedora is built on https://docs.fedoraproject.org/en-US/project/[the four F's]. @@ -31,7 +31,7 @@ re-composing. At any time anyone should be able to see how Fedora is put together and put together their own version of Fedora. -=== Integrated +== Integrated Fedora is a huge project with a massive number of ever-growing deliverables. This means when we add new deliverables we need to have @@ -44,7 +44,7 @@ it works.* The tooling has to ensure that the output is `Reproducible`, `Auditable`, `Definable` so that it can be `Deliverable`. -=== Reproducible +== Reproducible A `reproducible` component is one we can rebuild from scratch at any time with less than a day's worth of effort. It implies we can look up all of @@ -72,7 +72,7 @@ https://src.fedoraproject.org[dist-git system] and `Koji` archives details about the build environment, the tools used, logs, and of course the binaries themselves. -=== Auditable +== Auditable Fedora and Red Hat expect `auditable` output too, which means Release Engineering knows who built what, when, and where (and how, but that is `Reproducibility`). @@ -104,7 +104,7 @@ and enhancements associated with the content and actually does the delivery. `Bodhi` maintains records of what was shipped when and where, and who pushed it. -=== Definable +== Definable The ability to `define` and predict content is necessary as well. It is important to know exactly what was included in a release. It helps @@ -128,7 +128,7 @@ https://src.fedoraproject.org[`dist-git`], https://bodhi.fedoraproject.org[`Bodhi`], and https://qa.fedoraproject.org/blockerbugs[`Blocker Bugs`]. -=== Deliverable +== Deliverable Official parts of Fedora are eligible to be `delivered` to `/pub/fedora/` or `/pub/alt/releases/` on https://dl.fedoraproject.org/pub/[Fedora diff --git a/modules/release_guide/pages/sop_beta_RC_compose.adoc b/modules/release_guide/pages/sop_beta_RC_compose.adoc index 022116b..729f0e6 100644 --- a/modules/release_guide/pages/sop_beta_RC_compose.adoc +++ b/modules/release_guide/pages/sop_beta_RC_compose.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Beta Release candidate When Quality Engineering (QE) requests a Release Candidate (RC) they do @@ -152,4 +151,3 @@ compose directory with `mkdir /mnt/koji/compose/{branched}` The method for verifying a compose has completed is checking `/mnt/koji/compose/{branched}/[compose_dir]/STATUS`. Any status other than DOOMED is OK. - diff --git a/modules/release_guide/pages/sop_beta_freeze.adoc b/modules/release_guide/pages/sop_beta_freeze.adoc index a841f7d..4d70449 100644 --- a/modules/release_guide/pages/sop_beta_freeze.adoc +++ b/modules/release_guide/pages/sop_beta_freeze.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Beta freeze and updates-testing activation point == Description diff --git a/modules/release_guide/pages/sop_beta_release.adoc b/modules/release_guide/pages/sop_beta_release.adoc index 47d5e7c..7ba544b 100644 --- a/modules/release_guide/pages/sop_beta_release.adoc +++ b/modules/release_guide/pages/sop_beta_release.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Fedora Beta Release Based on the GO/NOGO meeting if the currnet compose is GO. The following steps need to be taken. diff --git a/modules/release_guide/pages/sop_create_release_signing_key.adoc b/modules/release_guide/pages/sop_create_release_signing_key.adoc index e056e0c..f022ecf 100644 --- a/modules/release_guide/pages/sop_create_release_signing_key.adoc +++ b/modules/release_guide/pages/sop_create_release_signing_key.adoc @@ -1,7 +1,5 @@ = Create Release Signing Key -== Description - At the beginning of each release under development, a new package signing key is created. This key is used to prove the authenticity of packages built by Fedora and distributed by Fedora. This key will be used to sign all packages for the public test and final releases. == Action @@ -153,7 +151,7 @@ because it's signed by our CA. === fedora-repos -The `fedora-repos` package houses a copy of the public key information. This is used by RPM to verify the signature on files encountered. Currently, the `fedora-repos` package has a single key file named after the version of the key and the arch the key is for. +The `fedora-repos` package houses a copy of the public key information. This is used by RPM to verify the signature on files encountered. Currently, the `fedora-repos` package has a single key file named after the version of the key and the arch the key is for. To continue our example, the file would be named `RPM-GPG-KEY-fedora-27-primary`, which is the primary arch key for Fedora 27. To create this file, use the `get-public-key` command from sigul: diff --git a/modules/release_guide/pages/sop_epel_minor_mass_branching.adoc b/modules/release_guide/pages/sop_epel_minor_mass_branching.adoc index 0041f37..a7e18f8 100644 --- a/modules/release_guide/pages/sop_epel_minor_mass_branching.adoc +++ b/modules/release_guide/pages/sop_epel_minor_mass_branching.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = EPEL Minor Version Mass Branching == Description @@ -13,7 +12,7 @@ new koji builds for EPEL are disabled. === Remove Targets -In Fedora it is recommended to https://docs.fedoraproject.org/en-US/infra/release_guide/sop_mass_branching/#_disable_rawhide_builds_in_koji[stop connections to koji through firewall]. +In Fedora it is recommended to https://docs.fedoraproject.org/en-US/infra/release_guide/sop_mass_branching/#_disable_rawhide_builds_in_koji[stop connections to koji through firewall]. But it was https://pagure.io/infra-docs-fpo/pull-request/357[decided not to require it] for this process. In the case of EPEL, just removing the targets is enough to disable it's usage for the time being while the branching process it's being done. @@ -64,7 +63,7 @@ On `pkgs01.stg` (for testing) or `pkgs02` (for production), run: [source,bash,subs="attributes"] ---- -$ sudo -u pagure python /usr/local/bin/mass-branching-git.py --branch-from epel{epel_major} epel{epel_current} components_epel{epel_major}.txt +$ sudo -u pagure python /usr/local/bin/mass-branching-git.py --branch-from epel{epel_major} epel{epel_current} components_epel{epel_major}.txt ---- The first argument is the new epel version and the @@ -100,7 +99,7 @@ change between minor versions ==== Add new SLA to the toddlers App -Make sure that the SLAs are added. Check https://pagure.io/fedora-infra/ansible/pull-request/2190#request_diff[this PR] +Make sure that the SLAs are added. Check https://pagure.io/fedora-infra/ansible/pull-request/2190#request_diff[this PR] for reference on what needs to be available. === Koji hub diff --git a/modules/release_guide/pages/sop_final_RC_compose.adoc b/modules/release_guide/pages/sop_final_RC_compose.adoc index 2b30bea..fcb9c9d 100644 --- a/modules/release_guide/pages/sop_final_RC_compose.adoc +++ b/modules/release_guide/pages/sop_final_RC_compose.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Final Release candidate When Quality Engineering (QE) requests a Release Candidate (RC) they do @@ -152,4 +151,3 @@ compose directory with `mkdir /mnt/koji/compose/{branched}` The method for verifying a compose has completed is checking `/mnt/koji/compose/{branched}/[compose_dir]/STATUS`. Any status other than DOOMED is OK. - diff --git a/modules/release_guide/pages/sop_final_freeze.adoc b/modules/release_guide/pages/sop_final_freeze.adoc index edcbd9e..7bd8b8c 100644 --- a/modules/release_guide/pages/sop_final_freeze.adoc +++ b/modules/release_guide/pages/sop_final_freeze.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Fedora Final Freeze @@ -61,10 +60,10 @@ For the reference, you can refer generic https://pagure.io/releng/blob/main/f/ma [source,subs="attributes+"] .... Hi all, - + Today, YYYY-MM-DD, is an important day on the Fedora Linux {branched} schedule [1], with significant cut-offs. - + Today we have the Final Freeze [2] which starts at 14:00 UTC. This means that only packages which fix accepted blocker or freeze exception bugs [3][4][5] will be marked as 'stable' and included in the Final composes. @@ -72,10 +71,10 @@ Other builds will remain in updates-testing until the Final release is approved, at which point the Final freeze is lifted and packages can move to the 'updates' repository. Pending updates will be pushed before final release as zero day updates. - + Regards, Fedora Release Engineering - + [1] https://fedorapeople.org/groups/schedule/f-{branched}/f-{branched}-key-tasks.html [2] https://fedoraproject.org/wiki/Milestone_freezes [3] https://fedoraproject.org/wiki/QA:SOP_blocker_bug_process @@ -97,4 +96,3 @@ During freezes we need to push updates that fix blocker and freeze exception issues to stable when requested. QA will file a ticket with the updates to push, which will include the appropriate command(s). Verify the command(s) and run them. - diff --git a/modules/release_guide/pages/sop_final_release.adoc b/modules/release_guide/pages/sop_final_release.adoc index a728e3c..60aee6e 100644 --- a/modules/release_guide/pages/sop_final_release.adoc +++ b/modules/release_guide/pages/sop_final_release.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Fedora Final Release == Koji changes diff --git a/modules/release_guide/pages/sop_mass_branching.adoc b/modules/release_guide/pages/sop_mass_branching.adoc index b2e80a2..b87765f 100644 --- a/modules/release_guide/pages/sop_mass_branching.adoc +++ b/modules/release_guide/pages/sop_mass_branching.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Mass Branching == Description @@ -58,7 +57,7 @@ On branching day, remove the robosignatory config for this resigning. [NOTE] ==== The OpenH264 packages are **not included** in the general mass resigning -process, since they live outside the main `f{rawhide}` tag. +process, since they live outside the main `f{rawhide}` tag. These must be handled separately, please check with section below, and with the infrastructure folks. ==== @@ -163,8 +162,8 @@ Now we need to update dist-git in two steps: * Create the new branch in git * Update the `gitolite.conf` to allow users to push to this new branch -For both of these actions, we need a file listing all **active** packages. -Previously, this was generated by **PDC**, but since **PDC is decommissioned**, +For both of these actions, we need a file listing all **active** packages. +Previously, this was generated by **PDC**, but since **PDC is decommissioned**, we now use a script to fetch active packages by filtering out retired and never-imported ones. === Generate the Active Package List @@ -723,7 +722,7 @@ Once, this is done, update the fullfiletimelist as well, this sometime take time [%sidebar] ==== **Note:** A related issue was recently opened: -- *Issue #12880* — missing Fedora 44 openh264 repo after branching. +- *Issue #12880* — missing Fedora 44 openh264 repo after branching. After F43 was branched, the openh264 Rawhide repo still points to F43's GPG key, causing signature errors. We now need an `f44` repo and to update MirrorManager accordingly. --See issue #12880 for details. Remove once the process becomes normal or have a fix. ==== diff --git a/modules/release_guide/pages/sop_mass_branching_checklist.adoc b/modules/release_guide/pages/sop_mass_branching_checklist.adoc index 4910a6a..090f069 100644 --- a/modules/release_guide/pages/sop_mass_branching_checklist.adoc +++ b/modules/release_guide/pages/sop_mass_branching_checklist.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Mass Branching Checklist // Merge things from google document to finalize the checklist diff --git a/modules/release_guide/pages/sop_mass_rebuild.adoc b/modules/release_guide/pages/sop_mass_rebuild.adoc index beb019d..74eb7ba 100644 --- a/modules/release_guide/pages/sop_mass_rebuild.adoc +++ b/modules/release_guide/pages/sop_mass_rebuild.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Mass Rebuild == Description @@ -258,7 +257,7 @@ email) . Clone or checkout the latest copy of the https://pagure.io/releng[releng git repository] . Run the `mass-tag.py` script (requires koji kerberos authentication) -. Remove the koji target for the rebuild: +. Remove the koji target for the rebuild: $ koji remove-target f{rawhide}-rebuild + ____ @@ -274,4 +273,4 @@ _devel-announce@lists.fedoraproject.org_ list ____ For the contents use this https://pagure.io/releng/blob/main/f/mail-templates/02-mass-rebuild-finished.txt[template]. ____ -===== \ No newline at end of file +===== diff --git a/modules/release_guide/pages/sop_post-release_cleanup.adoc b/modules/release_guide/pages/sop_post-release_cleanup.adoc index 007b0e6..b432e1e 100644 --- a/modules/release_guide/pages/sop_post-release_cleanup.adoc +++ b/modules/release_guide/pages/sop_post-release_cleanup.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = Post-Release Clean-up Documentation :page-description: Steps to clean up resources after a Fedora final release, including removing outdated content, updating configurations, and closing issues. diff --git a/modules/release_guide/pages/sop_release_eol.adoc b/modules/release_guide/pages/sop_release_eol.adoc index bde5ec9..670ae92 100644 --- a/modules/release_guide/pages/sop_release_eol.adoc +++ b/modules/release_guide/pages/sop_release_eol.adoc @@ -1,5 +1,4 @@ include::_partials/attributes.adoc[] - = End Of Life == Description diff --git a/modules/release_guide/pages/sop_retire_orphaned_packages.adoc b/modules/release_guide/pages/sop_retire_orphaned_packages.adoc index 8dac570..01891c4 100644 --- a/modules/release_guide/pages/sop_retire_orphaned_packages.adoc +++ b/modules/release_guide/pages/sop_retire_orphaned_packages.adoc @@ -1,8 +1,7 @@ include::_partials/attributes.adoc[] += Retire Orphaned Packages -== Retire Orphaned Packages - -=== Description +== Description Every release prior to the https://fedoraproject.org/wiki/Schedule[Feature Freeze/Branching] @@ -11,7 +10,7 @@ https://fedoraproject.org/wiki/Orphaned_package_that_need_new_maintainers[orphan packages]. This keeps out unowned software and prevents future problems down the road. -=== Action +== Action The orphan process takes place in stages: @@ -21,7 +20,7 @@ if the orphans are removed. for community review and removal from the orphan list. . Retriring packages nobody wants to adopt. -==== Detecting Orphans +=== Detecting Orphans A script called `find_unblocked_orphans.py` assists in the detection process. It should be run on a machine that has `koji` and @@ -31,7 +30,7 @@ complete. `find_unblocked_orphans.py` is available in the https://pagure.io/releng[Release Engineering git repository] -==== Announcing Packages to be retired +=== Announcing Packages to be retired `find_unblocked_orphans.py` outputs text to stdout on the command line in a form suitable for the body of an email message. @@ -46,21 +45,21 @@ freeze, send mails with updated lists as necessary. This gives maintainers an opportunity to pick up orphans that are important to them or are required by other packages. -==== Retiring Orphans +=== Retiring Orphans Once maintainers have been given an opportunity to pick up orphaned packages, the remaining https://fedoraproject.org/wiki/How_to_remove_a_package_at_end_of_life[packages are retired] -===== Bugs +==== Bugs This procedure probably leaves open bugs for the retired packages behind. It is not within the scope of release engineering to take care of these. If bugs are closed, only bugs targeted at Rawhide should be affected, since other branches might still be maintained. -=== Verification +== Verification To verify that the packages were blocked correctly we can use the `latest-pkg` `koji` action. @@ -72,7 +71,7 @@ $ koji latest-pkg dist-f{branched} wdm This should return nothing, as the `wdm` package is blocked. -=== Consider Before Running +== Consider Before Running Generally we retire anything that doesn't leave broken dependencies. If there are orphans whose removal would result in broken dependencies a diff --git a/modules/release_guide/pages/sop_torrent_releases.adoc b/modules/release_guide/pages/sop_torrent_releases.adoc index 49a8c3c..63d32f7 100644 --- a/modules/release_guide/pages/sop_torrent_releases.adoc +++ b/modules/release_guide/pages/sop_torrent_releases.adoc @@ -1,10 +1,8 @@ = Torrent Releases Infrastructure SOP - http://torrent.fedoraproject.org/ is our master torrent server for Fedora distribution. It runs out of ibiblio. - == Contact Information Owner:: diff --git a/modules/releng_misc_guide/pages/index.adoc b/modules/releng_misc_guide/pages/index.adoc index e57e260..5ec08a0 100644 --- a/modules/releng_misc_guide/pages/index.adoc +++ b/modules/releng_misc_guide/pages/index.adoc @@ -1,6 +1,4 @@ -== Fedora Release Engineering Miscellaneous Guide - -== Introduction == += Fedora Release Engineering Miscellaneous Guide The Fedora Release Engineering team is responsible for ensuring the timely and successful release of Fedora Linux distributions. While many of the team's tasks are well-defined and documented, there are also miscellaneous tasks that arise from time to time that may not fit neatly into established release processes. @@ -8,7 +6,7 @@ This guide serves as a reference for those miscellaneous tasks. While these task Whether you're a member of the Fedora Release Engineering team, a contributor to Fedora, or simply interested in the release process, we hope you find this guide informative and useful. -== List of Miscellaneous Tasks == +== List of Miscellaneous Tasks Here are some of the miscellaneous tasks performed by the Fedora Release Engineering team: @@ -29,6 +27,6 @@ Here are some of the miscellaneous tasks performed by the Fedora Release Enginee * link:sop_package_blocking[Package Blocking] * link:sop_sigul_client_setup[Sigul Client Setup] -== Conclusion == +== Conclusion This concludes the Fedora Release Engineering Miscellaneous Guide. diff --git a/modules/releng_misc_guide/pages/overview.adoc b/modules/releng_misc_guide/pages/overview.adoc index 46cc1f2..9f96ebc 100644 --- a/modules/releng_misc_guide/pages/overview.adoc +++ b/modules/releng_misc_guide/pages/overview.adoc @@ -1,8 +1,8 @@ [[overview]] -== Fedora Release Engineering Overview += Fedora Release Engineering Overview [[overview-intro]] -=== Introduction +== Introduction The development of Fedora is a very open process, involving over a thousand package maintainers (along with testers, translators, @@ -56,26 +56,26 @@ exception bug process] * The https://fedoraproject.org/wiki/Bugs_and_feature_requests[Bugzilla system] -=== Final Release Checklist +== Final Release Checklist Various tasks need to be accomplished prior to a final Fedora release. Release Engineering is responsible for many of them, as outlined here. -==== Release Announcement +=== Release Announcement The https://fedoraproject.org/wiki/Docs_Project[Fedora Documentation Project] prepares release announcements for the final releases. A https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora%20Documentation&op_sys=Linux&target_milestone=---&bug_status=NEW&version=devel&component=release-notes&rep_platform=All&priority=normal&bug_severity=normal&assigned_to=relnotes%40fedoraproject.org&cc=&estimated_time_presets=0.0&estimated_time=0.0&bug_file_loc=http%3A%2F%2F&short_desc=RELNOTES%20-%20Summarize%20the%20release%20note%20suggestion%2Fcontent&comment=Provide%20details%20here.%20%20Do%20not%20change%20the%20blocking%20bug.&status_whiteboard=&keywords=&issuetrackers=&dependson=&blocked=151189&ext_bz_id=0&ext_bz_bug_id=&data=&description=&contenttypemethod=list&contenttypeselection=text%2Fplain&contenttypeentry=&maketemplate=Remember%20values%20as%20bookmarkable%20template&form_name=enter_bug[bug needs to be filed] for this two weeks before the final release date. -==== Mirror List Files +=== Mirror List Files A new set of mirror list files need to be created for the new release. Email mailto:mirror-admin@fedoraproject.org[Fedora Mirror Admins] to have these files created. These should be created at the Final Freeze point but may redirect to Rawhide until final bits have been staged. -=== Release Composing +== Release Composing Fedora “releases” can be built by anyone with a fast machine of proper arch and access to a package repository. All of the tools necessary to @@ -94,7 +94,7 @@ There is work currently being done to replace livecd-creator with https://github.com/rhinstaller/lorax/blob/master/src/sbin/livemedia-creator[livemedia-creator]. ==== -==== Pungi +=== Pungi https://pagure.io/pungi[Pungi] is the tool used to compose Fedora releases. It requires being ran in a chroot of the package set that it @@ -105,7 +105,7 @@ https://fedoraproject.org/wiki/Koji[Koji] build system provides a way to run tasks within chroots on the various arches, as well as the ability to produce yum repos of packages from specific collections. -==== Livecd-creator +=== Livecd-creator Livecd-creator is part of the https://fedoraproject.org/wiki/FedoraLiveCD[livecd-tools] package in @@ -113,7 +113,7 @@ Fedora and it is used to compose the live images as part of the Fedora release. It is also used to compose many of the custom https://spins.fedoraproject.org[Spins] or variants of Fedora. -=== Distribution +== Distribution Once a compose has been completed, the composed tree of release media, installation trees, and frozen @@ -122,19 +122,19 @@ synchronized with the Fedora mirror system. [[MirrorManager]] has some more details on the mirror system. Many of the images are also offered via BitTorrent as an alternative method of downloading. -==== Download Mirrors +=== Download Mirrors Depends on the Fedora Mirror System and infrastructure to populate them privately. -==== BitTorrent +=== BitTorrent BitTorrent is currently served by http://torrent.fedoraproject.org. Images are added to the system via this https://infrastructure.fedoraproject.org/infra/docs/docs/sysadmin-guide/sops/torrentrelease.rst[Standard Operating Procedure]. -=== Acknowledgements +== Acknowledgements This document was influenced by http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html[release diff --git a/modules/releng_misc_guide/pages/sop_clean_amis.adoc b/modules/releng_misc_guide/pages/sop_clean_amis.adoc index 0be1e5e..af17010 100644 --- a/modules/releng_misc_guide/pages/sop_clean_amis.adoc +++ b/modules/releng_misc_guide/pages/sop_clean_amis.adoc @@ -1,6 +1,6 @@ -== Clean AMIs Process += Clean AMIs Process -=== Description +== Description The Fedora AMIs are uploaded on a daily basis to Amazon Web Services. Over time the number of AMIs piles up and have to be removed manually. @@ -11,7 +11,7 @@ The goal of the script is to automate the process and continue regular removal of the AMIs. The report of the script is pushed to a https://pagure.io/ami-purge-report[Pagure repo] -=== Action +== Action There is a script in the https://pagure.io/releng[Fedora RelEng repo] named `clean-amis.py` under the `scripts` directory. diff --git a/modules/releng_misc_guide/pages/sop_eol_change.adoc b/modules/releng_misc_guide/pages/sop_eol_change.adoc index d225b4e..aa10d80 100644 --- a/modules/releng_misc_guide/pages/sop_eol_change.adoc +++ b/modules/releng_misc_guide/pages/sop_eol_change.adoc @@ -1,4 +1,4 @@ -== Adjust EOLs and SLs on branches += Adjust EOLs and SLs on branches [NOTE] .Note @@ -9,7 +9,7 @@ you won't find information on that here. See the unretirement SOP for more info there. ==== -=== Description +== Description With "arbitrary branching", modules can include streams for an RPM that are not directly associated with a Fedora release. Modules _themselves_ @@ -26,7 +26,7 @@ branch, they need to file a https://pagure.io/releng/issues[releng ticket] requesting it. They have no way to do it on their own. Releng must review the request, and then process it. -=== Policy +== Policy Here are some _policy_ guidelines to help you (releng) make decisions about these tickets @@ -62,7 +62,7 @@ the maintainers, but also introduces complexity. If a maintainer requests piecemeal SL EOLs, ask to make sure they really want this kind of complexity. -=== Action +== Action We have a script in the releng repo: diff --git a/modules/releng_misc_guide/pages/sop_fedora_media_writer.adoc b/modules/releng_misc_guide/pages/sop_fedora_media_writer.adoc index f06ed36..be644c3 100644 --- a/modules/releng_misc_guide/pages/sop_fedora_media_writer.adoc +++ b/modules/releng_misc_guide/pages/sop_fedora_media_writer.adoc @@ -1,13 +1,13 @@ -== Fedora Media Writer Building and Signing += Fedora Media Writer Building and Signing -=== Description +== Description Whenever a new version of Fedora Media Writer is available, it is required to build and code sign it. -=== Action +== Action -==== Windows +=== Windows {empty}#. Get a windows code signing key from private ansible repository. It is in the ansible-private/files/code-signing/ directory @@ -42,14 +42,14 @@ that contains the password used in creating .pvk file. $ ./build.sh .... -=== Verification +== Verification The FedoraMediaWriter-win32-.exe is located under dist/win/ directory. -==== OS X: +=== OS X: -==== Build: +=== Build: . install xcode 8.1 from apple store. . {blank} @@ -68,7 +68,7 @@ install qt for mac from::: Writer.app" -executable="Fedora Media Writer.app/Contents/MacOS/helper" -qmldir="../../app" -==== Prepare certificates +=== Prepare certificates This only needs to happen once per build machine, and prepares the certificates by requesting them from Apple. @@ -86,7 +86,7 @@ certificates by requesting them from Apple. . Wait until the button disappears . Done -==== Sign and DMG +=== Sign and DMG . Open a terminal . cd to the root directory of the FMW project @@ -126,29 +126,29 @@ hdiutil create -srcfolder "Fedora Media Writer.app" -format UDCO -imagekey zlib .... ____ -==== Account Email(OS X) +=== Account Email(OS X) ____ :::: releng@fedoraproject.org ____ -==== Account Holders(OS X) +=== Account Holders(OS X) . Primary: Dennis Gilmore(ausil) . Backup: Kevin Fenzi(kevin) . Manager/bill-payer: Paul Frields(pfrields) -=== Sync binaries to the web +== Sync binaries to the web copy both files to /srv/web/fmw on sundries01 create symlinks to the FedoraMediaWriter-win32-latest.exe and FedoraMediaWriter-osx-latest.dmg -=== Consider Before Running +== Consider Before Running Nothing yet. -=== Issue with signing +== Issue with signing If the build is done but it is not signed then try editing the `build.sh` and add -askpass argument for all the osslsigncode commands diff --git a/modules/releng_misc_guide/pages/sop_find_module_info.adoc b/modules/releng_misc_guide/pages/sop_find_module_info.adoc index 9965eb8..065abae 100644 --- a/modules/releng_misc_guide/pages/sop_find_module_info.adoc +++ b/modules/releng_misc_guide/pages/sop_find_module_info.adoc @@ -1,17 +1,17 @@ -== Finding Module Information += Finding Module Information -=== Description +== Description When users submit builds to the Module Build Service (MBS), it in turn submits builds to Koji. Sometimes, you are looking at a koji build, and you want to know what module-build it is a part of. -=== Caveat +== Caveat It requires that the build has been completed and has been tagged, until https://pagure.io/fm-orchestrator/issue/375 is complete. -=== Setup +== Setup Run the following: @@ -19,7 +19,7 @@ Run the following: $ sudo dnf install python-arrow python-requests koji .... -=== Action +== Action Run the following: diff --git a/modules/releng_misc_guide/pages/sop_package_blocking.adoc b/modules/releng_misc_guide/pages/sop_package_blocking.adoc index dfa0fb9..0af424f 100644 --- a/modules/releng_misc_guide/pages/sop_package_blocking.adoc +++ b/modules/releng_misc_guide/pages/sop_package_blocking.adoc @@ -1,6 +1,6 @@ -== Package Blocking += Package Blocking -=== Description +== Description If a https://fedoraproject.org/wiki/How_to_remove_a_package_at_end_of_life[package @@ -10,7 +10,7 @@ builds and distribution of built RPMs. Packages are blocked in the listing of `tags`, due to inheritance it is enough to block packages at the oldest tag will make it unavailable also in upstream tags. -=== Action +== Action The blocking of retired packages is done by the https://pagure.io/releng/blob/master/f/scripts/block_retired.py[block_retired.py] diff --git a/modules/releng_misc_guide/pages/sop_package_unblocking.adoc b/modules/releng_misc_guide/pages/sop_package_unblocking.adoc index d2e3ed5..c32bfb8 100644 --- a/modules/releng_misc_guide/pages/sop_package_unblocking.adoc +++ b/modules/releng_misc_guide/pages/sop_package_unblocking.adoc @@ -1,24 +1,24 @@ -== Package Unblocking += Package Unblocking -=== Description +== Description Packages are sometimes unblocked from Fedora, usually when a package had been orphaned and now has a new owner. When this happens, release engineering needs to "unblock" the package from koji tags. -=== Action +== Action -==== Find Unblock requests +=== Find Unblock requests Unblock requests are usually reported in the https://pagure.io/releng/issues[rel-eng issue tracker]. -==== Perform the unblocking +=== Perform the unblocking First assign the ticket to yourself to show, that you are handling the request. -===== Discover proper place to unblock +==== Discover proper place to unblock The ticket should tell you which Fedora releases to unblock the package in. Typically it'll say "Fedora 13" or "F14". This means we need to @@ -53,11 +53,11 @@ do: .... $ koji list-pkgs --package python-psyco --show-blocked -Package Tag Extra Arches Owner +Package Tag Extra Arches Owner ----------------------- ----------------------- ---------------- --------------- python-psyco dist-f14 konradm [BLOCKED] -python-psyco olpc2-ship2 shahms -python-psyco olpc2-trial3 shahms +python-psyco olpc2-ship2 shahms +python-psyco olpc2-trial3 shahms ... .... @@ -67,7 +67,7 @@ to unblock. However if they want it unblocked after f14, we would use the earliest dist-f?? tag the user wants, such as dist-f15 if the user asked for it to be unblocked in Fedora 15+ -===== Performing the unblock +==== Performing the unblock To unblock a package for a tag, use the `unblock-pkg` method of Koji. @@ -89,7 +89,7 @@ $ koji unblock-pkg dist-f14 python-psyco Now the ticket can be closed. -=== Verification +== Verification To verify that the package was successfully unblocked use the `list-pkgs` koji command: @@ -101,20 +101,20 @@ $ koji list-pkgs --package python-psyco --show-blocked We should see the package listed as not blocked at dist-f14 or above: .... -Package Tag Extra Arches Owner +Package Tag Extra Arches Owner ----------------------- ----------------------- ---------------- --------------- -python-psyco olpc2-trial3 jkeating -python-psyco olpc2-ship2 jkeating -python-psyco olpc2-update1 jkeating -python-psyco trashcan jkeating -python-psyco f8-final jkeating +python-psyco olpc2-trial3 jkeating +python-psyco olpc2-ship2 jkeating +python-psyco olpc2-update1 jkeating +python-psyco trashcan jkeating +python-psyco f8-final jkeating ... .... We should not see it listed as blocked in dist-f14 or any later Fedora tags. -=== Consider Before Running +== Consider Before Running * Watch the next day's rawhide/branched/whatever report for a slew of broken deps related to the package. We may have to re-block the package diff --git a/modules/releng_misc_guide/pages/sop_process_dist_git_requests.adoc b/modules/releng_misc_guide/pages/sop_process_dist_git_requests.adoc index 729c1b9..5c81b52 100644 --- a/modules/releng_misc_guide/pages/sop_process_dist_git_requests.adoc +++ b/modules/releng_misc_guide/pages/sop_process_dist_git_requests.adoc @@ -1,6 +1,6 @@ -== Process fedora-scm-requests tickets += Process fedora-scm-requests tickets -=== Description +== Description When a packager wants a new package added to Fedora or a new dist-git branch blessed, they need to go through the new package process and, @@ -11,7 +11,7 @@ https://pagure.io/releng/fedora-scm-requests[fedora-scm-requests queue]. Periodically, (daily?) release engineering will need to review and process this queue using the [.title-ref]#fedrepo-req-admin# tool. -=== Setup +== Setup A release engineering will need to have several values set locally as well as sufficient permissions in a number of server-side systems. @@ -24,7 +24,7 @@ Ask @pingou how to get one. If doing this yourself, go to pkgs01 and run admin-token create -h# for more info. . pdc token. See the PDC SOP for getting one of these. -=== Action +== Action . Run [.title-ref]#fedrepo-req-admin list# to list all open requests. . Run [.title-ref]#fedrepo-req-admin process N# to process a particular diff --git a/modules/releng_misc_guide/pages/sop_pushing_updates.adoc b/modules/releng_misc_guide/pages/sop_pushing_updates.adoc index 982596d..29d499f 100644 --- a/modules/releng_misc_guide/pages/sop_pushing_updates.adoc +++ b/modules/releng_misc_guide/pages/sop_pushing_updates.adoc @@ -1,11 +1,11 @@ -== Pushing Updates += Pushing Updates -=== Description +== Description Fedora updates are typically pushed once a day. This SOP covers the steps involved. -==== Coordinate +=== Coordinate Releng has a rotation of who pushes updates when. Please coordinate and only push updates when you are expected to or have notified other releng @@ -14,13 +14,13 @@ https://apps.fedoraproject.org/calendar/release-engineering/ for the list or on irc you can run `.pushduty` in any channel with zodbot to see who is on duty this week. -==== Login to machine to sign updates +=== Login to machine to sign updates Login to a machine that is configured for sigul client support and has the bodhi client installed. Currently, this machine is: `bodhi-backend01.phx2.fedoraproject.org` -==== Decide what releases you're going to push. +=== Decide what releases you're going to push. * If there is a Freeze ongoing, you SHOULD NOT push all stable requests for a branched release, only specific blocker or freeze exception @@ -31,7 +31,7 @@ releases at the same time if you wish. can only push those if requested. Note however that bodhi2 will automatically push branches with security updates before others. -==== Get a list of packages to push +=== Get a list of packages to push .... $ sudo -u apache bodhi-push --releases 'f26,f25,f24,epel-7,EL-6' --username @@ -84,7 +84,7 @@ bodhi so that updates now hit the -updates tag (e.g. f26-updates). Once we have cloned the tag or locked the tag and adjusted bodhi we are free to push stable updates again. -==== Pushing Stable updates during freeze +=== Pushing Stable updates during freeze During feezes we need to push to stable builds included in the compose. QA will file a ticket with the nvrs to push. @@ -103,7 +103,7 @@ listed individually. $ sudo -u apache bodhi-push --builds ',,...' --username .... -===== There are no updates to push. +==== There are no updates to push. If you are getting the message `There are no updates to push.` or the list of packages you are seeing to push out for the Stable updates @@ -130,11 +130,11 @@ this by running the following on one of the bodhi-backend systems: bodhi updates request stable .... -==== Perform the bodhi push +=== Perform the bodhi push Say 'y' to push for the above command. -=== Verification +== Verification . Monitor Bodhi's composes with `bodhi-monitor-composes` + @@ -175,7 +175,7 @@ sudo journalctl --since=yesterday -o short -u fedmsg-hub | grep dist-6E-epel (or if any have security updates, those branches will be started first. It will then fire off threads (up to 3 at a time) and do the rest. -=== Consider Before Running +== Consider Before Running Pushes often fall over due to tagging issues or unsigned packages. Be prepared to work through the failures and restart pushes from time to @@ -187,7 +187,7 @@ $ sudo -u apache bodhi-push --resume Bodhi will ask you which push(es) you want to resume. -=== Common issues / problems with pushes +== Common issues / problems with pushes * When the push fails due to new unsigned packages that were added after you started the process. re-run step 4a or 4b with just the package diff --git a/modules/releng_misc_guide/pages/sop_request_an_automation_user.adoc b/modules/releng_misc_guide/pages/sop_request_an_automation_user.adoc index a11ceb3..c34a561 100644 --- a/modules/releng_misc_guide/pages/sop_request_an_automation_user.adoc +++ b/modules/releng_misc_guide/pages/sop_request_an_automation_user.adoc @@ -1,16 +1,16 @@ -== Request an Automation User += Request an Automation User [[sop_requesting_task_automation_user]] -=== Description +== Description When performing automated Release Engineering tasks using `RelEng Automation <_releng-automation>` you will sometimes find that you need to perform an action in the Infrastructure with `sudo` that does not yet have an automation user associated with it. -=== Actions +== Actions -==== Request a new loopabull user +=== Request a new loopabull user File a ticket with https://pagure.io/fedora-infrastructure/[Fedora Infrastructure] making sure to satisfy the following requirements: diff --git a/modules/releng_misc_guide/pages/sop_signing_builds.adoc b/modules/releng_misc_guide/pages/sop_signing_builds.adoc index 874f3e8..38e9ad9 100644 --- a/modules/releng_misc_guide/pages/sop_signing_builds.adoc +++ b/modules/releng_misc_guide/pages/sop_signing_builds.adoc @@ -1,6 +1,5 @@ include::_partials/attributes.adoc[] - -== Sign the packages += Sign the packages * This doc explains how to sign builds in the release(s). * Manual signing should rarely ever be needed anymore. Just make sure diff --git a/modules/releng_misc_guide/pages/sop_sigul_client_setup.adoc b/modules/releng_misc_guide/pages/sop_sigul_client_setup.adoc index 28bcb0f..00a4912 100644 --- a/modules/releng_misc_guide/pages/sop_sigul_client_setup.adoc +++ b/modules/releng_misc_guide/pages/sop_sigul_client_setup.adoc @@ -1,9 +1,9 @@ -== Sigul Client Setup += Sigul Client Setup This document describes how to configure a sigul client. For more information on sigul, please see link:User-Mitr[User:Mitr] -=== Prerequisites +== Prerequisites . Install `sigul` and its dependencies. It is available in both Fedora and EPEL: @@ -27,7 +27,7 @@ from at the following locations: * `~/.fedora-upload-ca.cert` . Admin privileges on koji are required to write signatures. -=== Configuration +== Configuration . Run `sigul_setup_client` . Choose a password for your NSS database. By default this will be @@ -46,7 +46,7 @@ bridge-hostname: sign-bridge.phx2.fedoraproject.org server-hostname: sign-vault.phx2.fedoraproject.org .... -=== Updating your Fedora certificate +== Updating your Fedora certificate When your Fedora certificate expires, after updating it run the following commands: diff --git a/modules/releng_misc_guide/pages/sop_template.adoc b/modules/releng_misc_guide/pages/sop_template.adoc index e4912a4..7e15185 100644 --- a/modules/releng_misc_guide/pages/sop_template.adoc +++ b/modules/releng_misc_guide/pages/sop_template.adoc @@ -1,4 +1,4 @@ -== Standard Operating Procedure Template += Standard Operating Procedure Template [NOTE] .Note @@ -10,10 +10,10 @@ New SOP documents should be added to the appropriate place in this repo - if the These documents are formatted using AsciiDoc, for markup reference please see: xref:fedora-docs:contributing-docs/asciidoc-markup.adoc[these docs] ==== -=== Description +== Description -=== Action +== Action -=== Verification +== Verification -=== Consider Before Running +== Consider Before Running diff --git a/modules/releng_misc_guide/pages/sop_troubleshooting.adoc b/modules/releng_misc_guide/pages/sop_troubleshooting.adoc index 68e7bda..5f5fcb0 100644 --- a/modules/releng_misc_guide/pages/sop_troubleshooting.adoc +++ b/modules/releng_misc_guide/pages/sop_troubleshooting.adoc @@ -1,4 +1,4 @@ -== Fedora Release Engineering Troubleshooting Guide += Fedora Release Engineering Troubleshooting Guide Fedora Release Engineering consists of many different systems, many different code bases and multiple tools. Needless to say, things can get @@ -14,19 +14,19 @@ in the systems that could go wrong but hopefully over time this document will stand as a proper knowledge base for reference and educational purposes on the topics listed below. -=== Compose +== Compose If something with a compose has gone wrong, there's a number of places to find information. Each of these are discussed below. -==== releng-cron list +=== releng-cron list The compose output logs are emailed to the releng-cron mailing list. It is good practice to check the https://lists.fedoraproject.org/archives/list/releng-cron@lists.fedoraproject.org/[releng-cron mailing list archives] and find the latest output and give it a look. -==== compose machines +=== compose machines If the https://lists.fedoraproject.org/archives/list/releng-cron@lists.fedoraproject.org/[releng-cron @@ -76,7 +76,7 @@ $ ls /etc/mock/*compose* /etc/mock/fedora-23-compose-x86_64.cfg /etc/mock/fedora-rawhide-compose-x86_64.cfg .... -==== running the compose yourself +=== running the compose yourself If you happen to strike out there and are still in need of debugging, it might be time to just go ahead and run the compose yourself. The exact @@ -115,7 +115,7 @@ see output in a while. This should provide you all the infromation needed to debug and/or diagnose further. When in doubt, as in `#fedora-releng` on `irc.libera.chat`. -=== Docker Layered Image Build Service +== Docker Layered Image Build Service The https://fedoraproject.org/wiki/Changes/Layered_Docker_Image_Build_Service[Docker @@ -135,7 +135,7 @@ hopefully shed light on some of the terminology and commands used below. There are a few "common" scenarios in which build may fail or hang that will need some sort of inspection of the build system. -==== Build Appears to stall after being scheduled +=== Build Appears to stall after being scheduled In the event that a build scheduled through koji appears to be stalled and is not in a `free` state (i.e. - has been scheduled). An @@ -164,7 +164,7 @@ $ oc logs build/cockpit-f24-9 The information found in the commands above will generally identify the issue. -==== Build fails but there's no log output in the Koji Task +=== Build fails but there's no log output in the Koji Task Sometimes there is a communications issue between Koji and OSBS which cause for a failure to be listed in Koji but without all the logs. These @@ -204,7 +204,7 @@ example you would first check `buildvm-02.stg`, then move on to machine, and again move on to the koji hub if neither of the builder machines involved provided useful log information. -==== Build fails because it can't get to a network resource +=== Build fails because it can't get to a network resource Sometimes there is a situation where the firewall rules get messed up on one of the OpenShift Nodes in the environment. This can cause output diff --git a/modules/releng_misc_guide/pages/sop_update_critpath.adoc b/modules/releng_misc_guide/pages/sop_update_critpath.adoc index efe958e..6ffc39a 100644 --- a/modules/releng_misc_guide/pages/sop_update_critpath.adoc +++ b/modules/releng_misc_guide/pages/sop_update_critpath.adoc @@ -1,4 +1,4 @@ -== Update Critpath += Update Critpath [NOTE] .Note @@ -8,7 +8,7 @@ Critpath = "Critical Path" This is a collection of packages deemed "critical" to Fedora ==== -=== Description +== Description Bodhi has information about which packages are critpath and which are not. A script that reads the dnf repodata (critpath groups in comps, and the @@ -17,7 +17,7 @@ events, an OpenShift cron job (called fedora-bodhi-critpathcron) updates this information daily, and no manual intervention is needed, but the steps to update it manually are documented here in case of need. -=== Action +== Action . The release engineering script for updating critpath lives in the https://pagure.io/releng[releng git repository]. Check this out. From d79888f9ac00c094356d62a6150d36c1ccaab656 Mon Sep 17 00:00:00 2001 From: Freya Gustavsson Date: Sep 16 2025 11:55:04 +0000 Subject: [PATCH 2/4] fix: Remove toc for dev guide's Getting Started With the new indentation the `:toc: right` now displays, which it didn't previously. With it now working it displays two table of contents instead of just one. Lets remove the docs own toc declaration and rely on Fedora's toc instead. Signed-off-by: Freya Gustavsson --- diff --git a/modules/developer_guide/pages/getting-started.adoc b/modules/developer_guide/pages/getting-started.adoc index 42b95ee..977c1b5 100644 --- a/modules/developer_guide/pages/getting-started.adoc +++ b/modules/developer_guide/pages/getting-started.adoc @@ -1,5 +1,4 @@ = Getting Started -:toc: right This document is intended to guide you through your first contribution to a Fedora Infrastructure project. It assumes you are already familiar From f2412ffeb721a54037d9d051c019047ba3f5cc1f Mon Sep 17 00:00:00 2001 From: Freya Gustavsson Date: Sep 16 2025 12:29:43 +0000 Subject: [PATCH 3/4] fix: Remove empty pages and their links Had no content in them Signed-off-by: Freya Gustavsson --- diff --git a/modules/ROOT/nav.adoc b/modules/ROOT/nav.adoc index 7f248d2..4cfcd26 100644 --- a/modules/ROOT/nav.adoc +++ b/modules/ROOT/nav.adoc @@ -40,11 +40,9 @@ *** xref:release_guide:sop_mass_rebuild.adoc[Mass Rebuild] *** xref:release_guide:sop_file_ftbfs.adoc[File FTBFS Bugs] *** xref:release_guide:sop_create_release_signing_key.adoc[Create Release Signing Keys] -*** xref:release_guide:re-sign_rawhide_content.adoc[Re-Sign Rawhide Content With Rawhide+1 Key] *** xref:release_guide:sop_retire_orphaned_packages.adoc[Retire Orphaned and Long-Time FTBFS Rawhide Packages] *** xref:release_guide:sop_mass_branching_checklist.adoc[Mass Branching Checklist] *** xref:release_guide:sop_mass_branching.adoc[Mass Branching] -*** xref:release_guide:sop_post-branch_freeze.adoc[Post-Branch Freeze] *** xref:release_guide:sop_epel_minor_mass_branching.adoc[EPEL Minor Version Mass Branching] *** xref:release_guide:sop_beta_freeze.adoc[Beta Freeze] *** xref:release_guide:sop_beta_RC_compose.adoc[Beta RC Compose] diff --git a/modules/release_guide/pages/re-sign_rawhide_content.adoc b/modules/release_guide/pages/re-sign_rawhide_content.adoc deleted file mode 100644 index e69de29..0000000 --- a/modules/release_guide/pages/re-sign_rawhide_content.adoc +++ /dev/null diff --git a/modules/release_guide/pages/sop_post-branch_freeze.adoc b/modules/release_guide/pages/sop_post-branch_freeze.adoc deleted file mode 100644 index e69de29..0000000 --- a/modules/release_guide/pages/sop_post-branch_freeze.adoc +++ /dev/null From d68ea09f973f4d81af6b8dba3b7726cafbcc9e85 Mon Sep 17 00:00:00 2001 From: Freya Gustavsson Date: Sep 16 2025 12:30:13 +0000 Subject: [PATCH 4/4] fix: Change the formatting of xref module link Should hopefully now work as intended going to fedora-docs root module instead of trying to do something within the current page. Signed-off-by: Freya Gustavsson --- diff --git a/modules/releng_misc_guide/pages/sop_template.adoc b/modules/releng_misc_guide/pages/sop_template.adoc index 7e15185..2c71a73 100644 --- a/modules/releng_misc_guide/pages/sop_template.adoc +++ b/modules/releng_misc_guide/pages/sop_template.adoc @@ -7,11 +7,9 @@ This is a template file, this can be copied to a new filename in order to start New SOP documents should be added to the appropriate place in this repo - if they do not fit anywhere else, they go in this releng_misc_guide, linked from pages/index.adoc and nav.adoc. -These documents are formatted using AsciiDoc, for markup reference please see: xref:fedora-docs:contributing-docs/asciidoc-markup.adoc[these docs] +These documents are formatted using AsciiDoc, for markup reference please see: xref:fedora-docs::contributing-docs/asciidoc-markup.adoc[these docs]. ==== -== Description - == Action == Verification