From Fedora Project Wiki

(Simplifed explanation and removed anecdotal comments.)
Line 112: Line 112:
= Enhancement suggestions =
= Enhancement suggestions =


We should add a section or subsection about how to ensure that a
Proposed addition to New on the need and steps for ensuring that a package
package and its dependencies are pushed together as one unit.
and its dependencies are pushed together as one unit.


There is the case where a package depends on one or more other packages.
There are cases where a package depends on one or more other packages and
One must ensure that the package along with the packages it depends on
one must ensure that the package along with the packages it depends on
are pushed to stable (or testing) as a unit. Otherwise, if the dependent
are pushed to stable, or testing, as one unit. If the dependent package
package gets pushed ahead of the others this will cause considerable grief
gets pushed ahead of the others this would cause unresolved dependencies
on users and the packager will never hear the end of it.  
at update time.  


To give a concrete example: nss was split into multiple packages.  
To give a concrete example: nss was split into three stand-alone packages,
We now have nss which depends on nss-softokn. Both nss and nss-soktokn  
nss, nss-util, and nssutil. nss depends on nss-softokn and both nss and  
depend on nss-util. They all depend on nspr. The nss-softokn is updated
nss-soktokn depend on nss-util. They all in turn depend on nspr. nss-softokn
independently of, and less frequently than, nss whereas the nss-util
is updated independently of, and less frequently than, nss whereas the nss-util
package is usually updated in synchrony with nss. If several of these are
package is usually updated in synchrony with nss. If several of these are
updated they must be pushed as a unit.
updated they must be pushed as a unit.


Via the Bodhi Web interface at the point of adding our package
Via the Bodhi Web interface: At the point of adding our package build to the
build we must add the builds of all the packages this one depends on (and
update, add also any rebuilds of packages this one depends on. This ensures
which have been updated) to the update. This way the package and its  
that the package and its dependencies are submitted as one unit.  
dependencies are submitted as a unit.


Is it possible to submit multiple build as a unit this via the command line
Via the command line interface: is is not clear from the documentation how
interface?
to to accomplish am update as a unit or that one can do it at all.
 
Note: I'm using nss as an example because I wished I had known this when
I pushed nss 3.12.6 out. It went out to stable before its dependencies did.
This caused users a lot of of grief and I still haven't heard of it.

Revision as of 16:06, 15 March 2010

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

Scope of this document

This document gives an introduction on what Bodhi is and its uses in real-time.This is a work in progress and hence the document currently targets end-users, however this document would be updated periodically to target everyone.


Targeted Audience

This document is targeted towards end users and people part of the engineering team.


What is Bodhi

Bodhi pronounced as bo-dee is a buddhist term for the wisdom by which one attains enlightenment. Bodhi is a modular web based system that facilitates the process of publishing package updates for fedora-based software distribution. Bodhi is currently used to send out package updates for Fedora. Bodhi is a system internal to Red Hat.It maintains a single stage of repositories by adding/updating/removing packages.

Advantages of Bodhi

  • Provides an intuitive interface for developers and release engineers to manage pushing out package updates for multiple version releases.
  • Helps in delivering quality packages and repository sustainment with automated testing.
  • Helps Community testers to get involved in testing of the package updates and provide quality feedback which would reach the packagers/developers.
  • Provides a modular framework that will allow future integrations to various other QA and developer tools.
  • New packages entering the collection can be announced to users.
  • The reasons for an update can be communicated to end users.
  • Bodhi generates extended update metadata which is parsed client-side by yum.
  • Security updates can be seen by users as a separate channel, with links to the security advisories.
  • Automated testing can be done on updates before they are released.
  • End users and QA folks who wish to can test updates before they are released.


Workflow

First you must build your package in the Koji buildsystem. See the relative guide.

It is always recommended that you test your package locally to the best of your ability before pushing it into a release.

Packages must then move through the following states in Bodhi. Koji.

Package States

Once submitted to Bodhi, packages move through the following states:

  • NEW - This is when your update request is being submitted.
  • PENDING - Your update has not yet been submitted to the RelEng team for pushing.
  • TESTING - Your package is in the updates-testing repository for people to test.
  • STABLE - Your package has been released to the main updates repository.
  • OBSOLETE - Your package has been obsoleted by a different update

New

Once built, a package will enter the New state once it is submitted to Bodhi in one of two ways:

$ bodhi -n -r F7 -t bugfix bodhi-0.4.2-1.fc7

You can see a menu on the left:

Select New Update for the appropriate release and type the name of the package that you would like to update. A list should appear with all of the possible builds for this package, if not then you can type the full name-version-release manually. Select the build that is going to be a potential update. You will be able to specify if the package is bugfix, an enhancement, or a security update. You can also specify any bugzilla bugs related to this update and provide any end user notes. By default, bodhi will close all associated bugs when the update is marked as stable, which can be toggled upon creation.

Bodhi will perform some sanity checks on your update request. Is your package built and available in koji? Is it tagged as an updates candidate for the release you wish to make it available for? The update path for your package will also be checked at this point to make sure you don't release a newer version of a package on an older release. Your update must not break the upgrade path or it will be rejected.

Your packages is now in the New state until you proceed.

Pending

When you are satisfied with the details of your update, you then choose "Push to Testing". Alternatively "Push to Stable" may be selected to skip the testing state.

The signing process is currently done by a human, so you will be notified by email when your update has been signed and pushed, and a package update notification will also be sent to fedora-package-announce or fedora-test-list depending on its status.

Testing

While in the updates-testing repository you may get feedback, both positive and negative. Once enough feedback is generated, you can use the bodhi interface to release your update by clicking 'Mark as Stable', or to remove it click 'Delete'. If your update achieves a karma of 3, it will automatically be pushed to stable, and will be unpushed if it reaches -3.

Stable

After your package is marked as stable, a request will get sent to the RelEng team and it will be signed and pushed out to the main released updates repository. Note that signing is a manual process and is done as time permits. Upon completion bodhi will optionally close all associated bugs, send out update notices to the appropriate mailing lists, and will notify everyone associated with the update.

Obsolete

Your update must be unpushed before it can be removed from the system. Only updates in the pending state may be deleted from the updates system. Removal will be done by an admin as time permits.

Questions and Answers

1. Q: What versions of Fedora and EPEL use or will use Bodhi? A: Fedora utilizes Bodhi as of Fedora 7. EPEL now utilizes Koji and Bodhi.

2. Q: Won't this slow down development / rawhide packages? A: bodhi will NOT be used for development / rawhide. Package builds there will (usually) be available in the next rawhide push. The exception being periods where there is a freeze in effect.

3. Q: Why do we need bodhi? What was wrong with just always pushing updates right out? A: There are lots of advantages to an updates system like bodhi, see Advantages of Bodhi.

4. Q: Is there a command line interface to bodhi? Do I have to have web access? A: The bodhi-client package is available.

5. Q: I want to push my package directly out, bypassing testing. A: Then once you submit your update, press "Push to Stable". Simple as that.

6. Q: What do I put in the "Notes" section of an update? A: It's up to you as maintainer. Consider that end users would like to know why they just downloaded this update. Does it add anything? Fix a bug? If it's a new package, consider adding in a copy of the description so end users will know what it is.

7. Q: Are we going to have any rule for how long things should be in updates-testing? How much QA? How many good/bad? A: Right now bodhi will automatically stabalize updates once they reach a karma of 3. Releng and security team members have full control of the updates, as well as the person that submits them.

Outstanding Questions

Enhancement suggestions

Proposed addition to New on the need and steps for ensuring that a package and its dependencies are pushed together as one unit.

There are cases where a package depends on one or more other packages and one must ensure that the package along with the packages it depends on are pushed to stable, or testing, as one unit. If the dependent package gets pushed ahead of the others this would cause unresolved dependencies at update time.

To give a concrete example: nss was split into three stand-alone packages, nss, nss-util, and nssutil. nss depends on nss-softokn and both nss and nss-soktokn depend on nss-util. They all in turn depend on nspr. nss-softokn is updated independently of, and less frequently than, nss whereas the nss-util package is usually updated in synchrony with nss. If several of these are updated they must be pushed as a unit.

Via the Bodhi Web interface: At the point of adding our package build to the update, add also any rebuilds of packages this one depends on. This ensures that the package and its dependencies are submitted as one unit.

Via the command line interface: is is not clear from the documentation how to to accomplish am update as a unit or that one can do it at all.