package-maintainer-docs/content/en-US/old/package-maintenance-guide.adoc

= package maintainence guide
This page provides some basic instructions for day-to-day usage of the
http://git-scm.com/[git]-based package maintenance system for Fedora. It
is intended primarily for new and current Fedora package maintainers,
but does briefly link:#anon[cover anonymous read-only use of the
system]. It is not a guide to RPM packaging per se. Some pre-existing
knowledge of git may be useful, but is not a pre-requisite (in fact,
Fedora packaging can be a relatively painless introduction to it).

You may have been looking for, or also be interested in:

* link:How_to_create_an_RPM_package[Learning to create packages]
* link:Join_the_package_collection_maintainers[Becoming a package
maintainer]
* link:Package_update_HOWTO[Submitting package updates]
* link:New_package_process_for_existing_contributors[Adding a new
package to the repository] as an existing maintainer
*
link:PackageDB_admin_requests#Additional_branches_for_existing_packages[adding
a new release branch] to an existing package
* Packaging:Guidelines[The Packaging Guidelines]

[[installing-fedpkg-and-doing-initial-setup]]
== Installing _fedpkg_ and doing initial setup

Start by installing with . This will also install the tool, which will
be your primary interface to the packaging system. Run to configure your
machine for package maintenance. If you have run before, but wish to set
up a new machine, copy the files to the new system.

You also must have an ssh key configured in the
https://admin.fedoraproject.org/accounts/[Fedora Accounts System] to be
able to make changes to any package (including your own). fedpkg will
expect the correct ssh key to be available in your keyring.

Before uploading sources with `new-sources` and `upload` and building
packages in Koji, with `build` for example, you have to get your
Kerberos credential first with `kinit`, e.g.

` kinit [FAS name]@FEDORAPROJECT.ORG`

(Keep FEDORAPROJECT.ORG in capital case)

[[common-fedpkg-commands]]
== Common fedpkg commands

This section lists typical fedpkg commands in a normal workflow, with
short descriptions. Longer explanations for each can be seen by clicking
the 'Show' links. In this workflow, we will be operating on the
link:Releases/Rawhide[Rawhide] branch of the package.

* Check out a package:

`fedpkg co ` +
`cd `

* Update your checked-out copy from the Fedora server:

`fedpkg pull`

* Retrieve the package sources:

`fedpkg sources`

* Make your changes to the package

* Run the 'prep' stage (extract source, apply patches etc) within the
checkout directory:

`fedpkg prep`

* Do a local build of the current state:

`fedpkg local`

* Do a mock build of the current state:

`fedpkg mockbuild`

* Generate a .src.rpm from the current state:

`fedpkg srpm`

* Do a scratch build using koji: see
https://fedoraproject.org/wiki/Using_the_Koji_build_system#Scratch_Builds[Koji
scratch builds]
* Check changes you have made:

`fedpkg diff`

* Run some checks (rpmlint) on your package:

`fedpkg lint`

* Stage any small patches or new source files for commit:

`git add (somefile)`

* Upload new source files to the lookaside cache:

`fedpkg new-sources`

`fedpkg upload`

* Switch to a different release branch:

`fedpkg switch-branch `

* Generate git changelog from package changelog:

`fedpkg clog`

* Commit changes:

`fedpkg commit (-F clog) (-p) (-c)`

* Push changes:

`fedpkg push`

* Do an 'official' build of the latest pushed changes:

`fedpkg build`

* In the event you are working with a Docker
link:Changes/Layered_Docker_Image_Build_Service[Container Layered Image
Build]

`fedpkg container-build`

* Submit a package update for the latest build:

`fedpkg update`

[[typical-fedpkg-session]]
== Typical _fedpkg_ session

A typical session may look like this:

---------------------------------------------------------------------------
fedpkg clone foo
cd foo
fedpkg sources
fedpkg new-sources foo-0.0.2.tar.bz2
gedit foo.spec       # change the required things in the specfile.
                     # rpmdev-bumpspec is useful for simple version updates
fedpkg mockbuild     # check that the changes you made are correct
fedpkg diff
fedpkg lint
fedpkg commit -p -c  # commit and push in one go
---------------------------------------------------------------------------

[[working-with-branches]]
== Working with branches

Each Fedora release is represented by a branch in the git repository.
You can switch between them like this:

`fedpkg switch-branch f` +
`fedpkg switch-branch f` +
`fedpkg switch-branch master`

The _master_ branch is for link:Releases/Rawhide[Rawhide]. You can
maintain each branch entirely separately, if you like, laboriously
copying changes between them (so long as you always stay within the
link:Updates Policy[Updates Policy] requirements). However, git provides
us with several handy tools for working with branches. Here's an
example: This will 'merge' the changes from the _master_ (Rawhide)
branch to the f branch. git aficionados may note this is a somewhat
unusual workflow, but it is appropriate to the context of package
management. Remember, after pushing to and building for a stable release
or a link:Releases/Branched[Branched] release after
link:Updates Policy#Bodhi_enabling[Bodhi has been enabled], you will
have to link:Package_update_HOWTO[submit an update] before any other
Fedora users will see your build.

Note that merges will only be sure to work cleanly so long as the
branches have not previously diverged. That is, if you do this: you may
encounter a _merge conflict_.

Remember that git is a _collaborative_ system, and used as such in
Fedora package management. It is often the case that you must consider
changes made by others in working on a package, and consider how your
changes will affect others.

[[resolving-merge-conflicts]]
=== Resolving merge conflicts

This is a large topic and somewhat beyond the scope of this guide, but
we can give basic pointers. There are other good references in the
http://git-scm.com/book/en/Git-Branching-Basic-Branching-and-Merging[git
book] and at
https://help.github.com/articles/resolving-a-merge-conflict-from-the-command-line[github].

When you git merge and a conflict occurs you can edit the files that
have conflicts. Remove the conflict markers in the files and merge the
changes manually. Use or to inspect the changes against the pre-conflict
state and verify you are happy with the resolution. Then you can commit
the files with or . git will know if you have resolved the conflict by
checking that all the conflict markers have been removed.

[[using-git-mergetool-to-resolve-conflicts]]
=== Using `git mergetool` to resolve conflicts

Git provides a graphical diff program to help resolve conflicts. This
can be handy for visualizing what changes have occurred and dealing with
them as a set.

[[requesting-special-dist-tags]]
== Requesting special dist tags

When a change to a package affects a large number of dependencies (e.g.
all perl, python, ruby or ghc packages), requiring them to be rebuilt,
it may be better to initially do the builds in a special repository, so
that there is less disruption in Rawhide.

If you think you have an update that falls under this case you can
request a special dist tag by filing a
https://fedorahosted.org/rel-eng/newticket[release engineering ticket].
Someone from link:ReleaseEngineering[release engineering] will likely
want to discuss your needs to make sure this is really an appropriate
case (it's OK ask if you aren't sure) and that you get what you need.

[[tips-and-tricks]]
== Tips and tricks

[[using-fedpkg-anonymously]]
=== Using fedpkg anonymously

You can use fedpkg like this:

`fedpkg clone --anonymous `

to check out a package without requiring identification. Obviously, you
will not be able to push any changes to this repository, but it is
useful for non-packagers who simply want to examine a package, make
changes for their own use, and perhaps submit changes to a Fedora
developer.

[[local-branch-names]]
=== Local branch names

If you use git commands to branch and checkout directly, you can define
whatever local branch names you want. If you use , it will default to
creating the names used in the examples above.

[[current-branch-and-state-in-shell-prompt]]
=== Current branch and state in shell prompt

It is often helpful to know what branch you are working on at a glance.
You can add this information to your bash prompt with the information
link:Git_Quickref#Display_current_branch_in_bash[here].

[[importing-a-.src.rpm-to-update]]
=== Importing a .src.rpm to update

The command usually used to initially populate a git package repository
from a .src.rpm that has been through the
link:Package Review Process[Package Review Process] can also be used to
update a normal working copy, if you have an old-school packaging
process to which you are particularly attached. Just run and it will
upload new tarballs into lookaside cache, update a working copy of the
last version found in git, and commit all changes. documents some other
parameters it can accept.

[[making-changes-on-an-older-branch-without-breaking-the-upgrade-path]]
=== Making changes on an older branch without breaking the upgrade path

Here is the scenario: you've built your package successfully on the __
branch, but there is a problem keeping your package from building on __.

Solution: make your changes in the branch and then add a digit to the
very right of the release tag. There is no need to change the release in
the other branches. This allows upgrades to work smoothly if the user
upgrades to a newer release of Fedora.

--------------------
Name:    foo
Version: 1.0
Release: 1%{?dist}

Name:    foo
Version: 1.0
Release: 1%{?dist}.1
--------------------

Then tag and build as usual. This approach was initially discussed
https://www.redhat.com/archives/fedora-extras-list/2006-May/msg00083.html[in
this mailing list thread].

[[removing-a-package-build-pending-for-rawhide-or-branched]]
=== Removing a package build pending for link:Releases/Rawhide[Rawhide]
or link:Releases/Branched[Branched]

From time to time you may want to remove a package build you submitted
to Rawhide or to Branched prior to the Alpha freeze (both cases where
the build would usually go out to the main link:Repositories[repository]
without further gating). This could happen in a situation where a bug or
issue is found in your package that will be resolved upstream in the
next release, or you realize you made a significant mistake in the build
that cannot easily be corrected.

You can remove the package by using Koji:

where is replaced with the name of your package build. See or
link:Using_the_Koji_build_system[using Koji] for more information.

[[ssh-fingerprint]]
=== ssh fingerprint

The recommended option is to include "`VerifyHostKeyDNS yes`" in your
~/.ssh/config file. This will result in using DNS to check that the key
is correct.

But you can also manually check against the list of keys at
https://admin.fedoraproject.org . The strings there are what ends up in
your ~/.ssh/known_hosts file. So you can accept the fingerprint when
prompted and then check that the correct string for
pkgs.fedoraproject.org ended up in your ~/.ssh/known_hosts file.

[[problems-connecting-to-the-repository]]
=== Problems connecting to the repository

The _fedpkg_ tool clones repositories using the ssh:// protocol, so this
should not be a problem normally (as long as you have your ssh key). If
you cloned using the _git_ utility itself, check the file to ensure the
remote repository is being accessed via an ssh:// protocol, and not
git://.

[[expired-certificates-error-255-or-openssl.ssl.error]]
=== Expired certificates (Error 255 or OpenSSL.SSL.Error)

This error usually means that your client certificate (~/.fedora.cert)
has expired, so you need to run fedora-cert to get a new one. If you
have trouble with this, you may try removing and re-running .

[[it-builds-here-why-doesnt-it-build-there]]
=== It builds here, why doesn't it build there?

Is your package building locally - even with Mock, even as a scratch
build! - but not when you run ? Before you get too frustrated, remember
runs on the package as it exists in the upstream repository, not your
local working copy. Make sure you have committed and pushed all changes
and source files, and handled the lookaside cache correctly. Other
issues that have been reported, are issues because of
https://bugzilla.redhat.com/show_bug.cgi?id=1179139[build/make check
parallelization] and failures because of test suites that depend on
operations finish on precise timing (and a busy build system may not be
able to perform operations on time).

[[references]]
== References

* http://pkgs.fedoraproject.org/cgit/
* Infrastructure/Kerberos
* link:Package SCM admin requests[Package SCM admin requests]
* Package_Renaming_Process
* PackageMaintainers/PackagingTricks
* Package_update_HOWTO
*
PackageMaintainers/BuildSystemClientSetup#Install_the_Client_Tools_.28Koji.29
* PackageMaintainers/MockTricks#How_do_I_use_Mock.3F
* Using_the_Koji_build_system
* Package_Review_Process
* Fedora_Release_Life_Cycle
* PackageMaintainers/Join
* Infrastructure/VersionControl/dist-git

Category:Package Maintainers[Category:Package Maintainers]