package-maintainer-docs/content/en-US/old/package-update-howto.adoc

= package update howto
This document shows how to submit an update for a package you maintain
in Fedora. It assumes you already have a package in the Fedora
repositories. It is not a guide to using the Fedora package source
control system: see the link:Package maintenance guide[Package
maintenance guide] for that.

* For details of the policy on requirements for updates at various
stages of the link:Fedora Release Life Cycle[Fedora Release Life Cycle],
refer to link:Updates Policy[Updates Policy].

[[overview]]
== Overview

This page is intended for new and existing package maintainers. Testers
and regular users may be interested in the
QA:Updates_Testing[updates-testing] repository and the
QA:Update_feedback_guidelines[update feedback guidelines]. This page
specifically covers the update submission process.

There are two significantly different package update submission
workflows in Fedora:

* link:Releases/Rawhide[Rawhide], and link:Releases/Branched[Branched]
up to the link:Updates Policy#Bodhi_enabling[Bodhi enabling point]
* link:Releases/Branched[Branched] releases after the Alpha change
deadline, and stable releases

The repository layouts differ somewhat for Rawhide, Branched and stable
releases, but the update workflows split up as described above.

[[rawhide-and-early-branched]]
== Rawhide and early Branched

The package update workflow for Rawhide and Branched before the _Bodhi
enabling point_ is simple:

1.  Build the package with (see the
link:Package maintenance guide[Package maintenance guide] for more
details)

This is all you need to do. Your package will appear in the next daily
compose of Rawhide or Branched and will be used in any image composes
built from that tree.

[[later-branched-and-stable-releases]]
== Later Branched and stable releases

At the link:Updates Policy#Bodhi_enabling[Bodhi enabling point], the
Bodhi update feedback system is enabled by
link:ReleaseEngineering[Release Engineering] and builds submitted with
are no longer automatically sent to any official
link:Repositories[repository]. The update workflow for releases of this
type is:

1.  Build the package with
2.  Submit an update for the package with , the
https://admin.fedoraproject.org/updates/[Bodhi web interface], or the
https://fedorahosted.org/bodhi/wiki/CLI[Bodhi CLI tool]. This causes the
package to be sent to the
link:Repositories#updates-testing[_updates-testing_] repository
3.  Monitor the update's status and the feedback you receive via the web
interface or the emails that are sent to you, and modify it with updated
or additional builds if necessary
4.  After the update meets the criteria in the
link:Updates Policy[Updates Policy] and you are satisfied it should be
released as a stable update, submit the update to
_link:Repositories#stable[stable]_ with or the web interface

[[update-attributes]]
=== Update attributes

At the time you submit the update, you will be asked for several
attributes. The type of the update should be fairly self-explanatory:
either it fixes bugs, adds new features, or is a new package.

If you are asked whether you want to send the update to
_updates-testing_ or _stable_, this is a no-op: all updates now go
through _updates-testing_. It does not matter what you choose.

There are several schools of thought on filling out the update
description. Some would suggest you consider the target audience: for a
stable release, in particular, many Fedora users will see this text, and
many of them may not be particularly familiar with your package.
Consider not simply describing literally the changes in the update, but
explaining as if to an outsider why your are updating the package, what
benefits it will bring to them (if any), and anything they may want to
note in order to have a smooth update experience.

If you associate one or more bug reports with your update, Bodhi will
post comments into Bugzilla to alert those following the bug reports
that an update is available. If you mark your update as fixing the
bug(s), Bodhi will move the report(s) through the *MODIFIED*, *ON_QA*
and *CLOSED ERRATA* states of the link:BugZappers/BugStatusWorkFlow[bug
workflow] as your update reaches various points in the process. Using
this mechanism can be very useful both for you and for users of your
package.

You may set a _karma_ (feedback) level at which the update will
automatically be submitted to _stable_. This is optional. If you choose
to use it, please carefully consider an appropriate feedback level. For
a relatively obscure package which is quite stable, 1 or 2 may be an
appropriate value. For a popular, sensitive and complex package such as
or the , the default of 3 may be insufficient and a choice of 5 or even
10 may be appropriate.

[[who-will-receive-your-update-when]]
=== Who will receive your update, when?

When a release is in Branched state, the _updates-testing_ repository is
enabled by default so most users will see the package, but only packages
from the stable _fedora_ repository are used in building milestone
releases (Alpha, Beta and Final) and nightly images.

Where a package goes when it is marked as _stable_ differs between
Branched and stable releases. In Branched releases, _stable_ packages
are pushed to the base _fedora_ repository. In stable releases, _stable_
packages are pushed to the _updates_ repository. However, from the point
of view of the packager, this is an insignificant implementation detail.
For more details, see Repositories.

When a release is in stable state, the _updates-testing_ repository is
disabled by default, but QA team members and others run with it enabled
in order to provide testing and Bodhi feedback. The main user population
will see your update only when it passes Bodhi, is marked as _stable_
and reaches the _updates_ repository.

[[updating-inter-dependent-packages]]
=== Updating inter-dependent packages

If an update you wish to submit would cause a dependency issue of any
kind (a strict package dependency error, or simply another package
failing to operate correctly) if updated alone, you must not submit the
package as a single-package update. You must always collect all
inter-dependent or related packages together into a single multi-package
update, such that no user will face problems if they install all the
packages in the update together.

For example: if you maintain a package _libfoo_ which the package _bar_
depends on, and you need to update _libfoo_, you should check that _bar_
continues to function correctly with the updated version of _libfoo_. If
it does not, you must ensure the appropriate changes are made to _bar_,
and include the updated _bar_ in your update along with the updated
_libfoo_.

The _fedpkg_ tool does not handle multi-package updates. You can add
multiple packages to an update using the
https://admin.fedoraproject.org/updates/[Bodhi web application], or the
command line tool. You can pass as many package names as you like to the
to create a new multi-package update, or use to edit an existing update.

It is possible you will run into problems with permissions when trying
to add builds of packages you do not have commit privileges for to an
update, or trying to add a build for a package you do have privileges
for to someone else's update. If you encounter a situation like this,
you should contact the link:ReleaseEngineering[release engineering] team
or a proven packager for help.

You may need a _buildroot override_ to complete a multi-package update
successfully. For instance in the case described above, you may need to
rebuild _bar_ against the new _libfoo_ package and submit both packages
together as a multi-package update. However, in the normal course of
events, you would not be able to build another package against your new
_libfoo_ build until it reached the link:Repositories#stable[_stable_]
state. To resolve this dilemma, you can request a buildroot override,
which causes the _libfoo_ build to be included in the buildroot for a
short time in order to get the _bar_ package build done.

You can request a buildroot override with bodhi: This would submit a
buildroot override with a duration of two days. Buildroot overrides are
usually granted within 15-30 minutes of submission. If you submit an
override request with the bodhi tool, it will suggest a command that
will let you monitor when the package appears in the buildroot, so you
can fire your dependent build at the appropriate time.

You can also request buildroot overrides from the
https://admin.fedoraproject.org/updates/[Bodhi web application].

The link:Bodhi/BuildRootOverrides[buildroot override instructions]
explain the buildroot override process in more detail.

[[handling-feedback-from-automated-tests]]
=== Handling feedback from automated tests

Fedora's automated testing systems, Taskotron and OpenQA, may run
automated tests on your update. Several of the Taskotron/Tasks are
documented. The openQA tests are functional tests of some critical
Workstation and Server features.

In the Bodhi web interface, updates have a _Automated Tests_ tab which
displays the results of all automated tests. Tests shown with a red
background failed. The tests are not all 100% accurate, but they are
fairly often correct. If you see a failure, it is a very good idea to
click on the result (which will take you to a detailed log) and
investigate the issue. If you are unsure what the test indicates, you
can contact the QA team for help.

[[waive-a-result]]
==== Waive a result

At present, a failure of the _dist.rpmdeplint_, _dist.abicheck_, or
_org.centos.prod.ci.pipeline.complete_ tests will prevent your update
from being released. On the update's _Details_ page in the Bodhi web
interface, the *Test Gating Status* will be shown as _N of N required
tests failed_. If you are sure such a failure is a false one, you can
'waive' the result using the tool, from the package (there is
https://github.com/fedora-infra/bodhi/pull/2095[work pending] to be able
to waiver more easily, directly from the Bodhi UI).

You can submit a waiver for a failing result with specifying the and the
:

  waiverdb-cli -t YOUR_TESTCASE_HERE \
     -s '{"item": "this-is-the-subject", "type": "also-this-is-part-of-the-subject"}'
     -p "fedora-26" -c "This is fine"

Example:

  waiverdb-cli -t dist.rpmdeplint \
     -s '{"item": "python-requests-1.2.3-1.fc26", "type": "koji_build"}' 
     -p "fedora-26" -c "This is fine"

You can also waive a failing result by result's id, which you can
retrieve from resultsdb with curl. To do that, you'll need the name and
the . For example:

  curl "https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0/results?testcases=dist.python-versions&item=python-alembic-0.9.7-1.fc27" | jq ".data[0].id"

This should print out the of the failing result. You can then submit a
waiver for this failing result with

  waiverdb-cli -p fedora-27 -r YOUR_ID_HERE -c "This is fine."

Also, if you enabled automatic stable push at a karma threshold, this
will be disabled if any automated test fails. If you have examined the
result and you are sure it is a false one and there is no problem with
the package, you may re-enable the automatic push mechanism or submit
the package to _stable_ manually once it meets the other requirements of
the link:Updates Policy[Updates Policy].

[[waive-the-absence-of-a-result]]
==== Waive the absence of a result

Submitting a waiver using subject/testcase allows to waive the absence
of a result (eg. the test never ran for some reason, so there is no
result item).

If which testcase you should be specified it is not clear/known, it is
possible to run this python script, chainging it with the corrects
parameter:

  #!/usr/bin/env python
  """ Ask a question of greenwave.  """
  # Usage: either modify and set PRODUCT_VERSION and NVR_LIST and run, 
  # or pass version as first arg and then NVRs as further args
  import pprint
  import requests
  import sys
  PRODUCT_VERSION = 'fedora-27' if len(sys.argv) == 1 else sys.argv[1]
  NVR_LIST = [] or sys.argv[2:]  # Insert your NVRs here, or pass them via command line args
  for nvr in NVR_LIST:
      url = (
          'https://greenwave-web-greenwave.app.os.fedoraproject.org/'
          'api/v1.0/decision')
      payload = dict(
          #verbose=True,
          decision_context='bodhi_update_push_stable',
          product_version=PRODUCT_VERSION,
          subject=[{'item': nvr, 'type': 'koji_build'}],
      )
      response = requests.post(url, json=payload)
      print("-" * 40)
      print(nvr, response, response.status_code)
      data = response.json()
      print(pprint.pformat(data))

The output will show that Greenwave is requiring a specific testcase to
run, but it cannot find a result for it (neither pass nor failure). So
now it is possible to submit a waiver with the specified testcase in the
output and the subject already known.

[[troubleshooting]]
==== Troubleshooting

If you run the tool and it gives you the following error:

  Error: The config option "resultsdb_api_url" is required

Edit and add the following line:

  resultsdb_api_url=`https://taskotron.fedoraproject.org/resultsdb_api/api/v2.0

[[branched-milestone-freezes]]
=== Branched milestone freezes

For a short period before each milestone release, the stable
link:Repositories#fedora[_fedora_] repository is frozen. These periods
are shown as the link:Milestone freezes[Milestone freezes] (Beta Freeze,
Final Freeze) on schedules. During these periods, builds will not be
marked _stable_ and pushed from
link:Repositories#updates-testing[_updates-testing_] to _fedora_ even
after being submitted manually or automatically. In the normal course of
events, they will be pushed after the milestone release is approved at a
Go_No_Go_Meeting. If you believe your update deserves to break a
milestone freeze, a _freeze exception_ may be granted through the
QA:SOP_freeze_exception_bug_process[freeze exception process]. Accepted
release blocking bugs are granted the same status through the
QA:SOP_blocker_bug_process[blocker bug process].

For more on the Fedora development process, see
link:Fedora Release Life Cycle[Fedora Release Life Cycle].

[[security-updates]]
== Security updates

There is an additional process that layers over the regular update
process for bugs identified as security issues. If a bug is assigned to
you that blocks a link:Security Tracking Bugs[security tracking bug],
you must follow that process in addition to this one.

[[new-package-submissions]]
== New package submissions

If you want to build a new package, but you aren't sure which releases
to send it to:

* New packages should always be built for Rawhide
* New packages can be built for Branched and stable releases if adding
them would provide value to users of those releases without significant
risk of causing harm

The submission process for new packages, after they have passed the
Package_Review_Process and been link:Package_SCM_admin_requests[given an
SCM repository], is exactly the same as that for package updates.

[[consider-creating-a-package-test-plan]]
== Consider creating a package test plan

If you QA:SOP_test_case_creation[create test cases] for your package,
and QA:SOP_package_test_plan_creation[categorize them appropriately],
they will be automatically linked in Bodhi, so that testers will have
some guidance for planned update testing.

Category:Package Maintainers[Category:Package Maintainers]