From Fedora Project Wiki

m (Adamwill moved page Using Fedora GIT to Package maintenance guide: This is a better name. No-one else on earth capitalizes "git", and git is an implementation detail. This is about to get a dump of stuff from the 'package update HOWTO' that is ...)
(initial work on this (merged in much of the stuff from the 'package update howto'), more coming)
Line 1: Line 1:
{{autolang|base=yes}}
{{autolang|base=yes}}
{{admon/important | Git config needs| A config problem has been discovered which may make <code>fedpkg push</code> or <code>fedpkg commit -p</code> or even <code>git push</code> not understand your intentions.  As a short term work around, you can run: <code>git config --global push.default tracking</code>.  This option tells git that when it gets a push request with no other arguments, see if it's tracking a remote branch.  If it is, push to that remote branch.  This seems like it will usually be safe no matter what git repository you are using.}}


== Cookbooks ==
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 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).


Refer to [[Package_update_HOWTO |How to update a package]] if you want to update an existing package.
You may have been looking for, or also be interested in:


[[New package process for existing contributors]] gives step-by-step instructions for that case.
* [[How_to_create_an_RPM_package|Learning to create packages]]
* [[Join_the_package_collection_maintainers|Becoming a package maintainer]]
* [[Package_update_HOWTO|Submitting package updates]]
* [[New_package_process_for_existing_contributors|Adding a new package to the repository]] as an existing maintainer
* [[Package_SCM_admin_requests#Package_Change_Requests_for_existing_packages|adding a new release branch]] to an existing package
* [[Packaging:Guidelines|The Packaging Guidelines]]


== Commands ==
== Installing ''fedpkg'' and doing initial setup ==


Here is a basic table of equivalent commands:
The {{command|fedpkg}} tool will usually be your primary interface to the packaging system. Install it with {{command|yum install fedpkg}}, or any equivalent command. If you have not already done so, you will also need to install {{package|fedora-packager}} and run {{command|fedora-packager-setup}}. If you have run {{command|fedora-packager-setup}} before, but wish to set up a new machine for package maintenance, copy the files {{filename|~/.fedora*.cert}} to the new system.
{|border="2" cellpadding="2" cellspacing="0"
! OLD CVS !! NEW GIT !! Notes
|-
|cvs checkout libfoo || fedpkg clone libfoo || Note that branches are not separated out by directory with this command. <BR> To switch to a different branch with this layout, run: fedpkg switch-branch f13
|-
|cvs checkout libfoo '''(ALTERNATE)''' ||fedpkg clone -B libfoo || This command creates the same branch/directory layout that was used with cvs.
|-
|cvs update || fedpkg pull ||Retrieve latest content from fedora git
|-
|cvs commit . || fedpkg commit -p || The -p option to commit invokes a push, just like with git, but you can separate these actions, as shown just below
|-
|cvs commit . '''(ALTERNATE)''' || fedpkg commit && fedpkg push ||
|-
|cvs commit -m 'breaking things' . || fedpkg commit -m 'breaking things' -p ||
|-
|cvs add foo bar || git add foo bar ||
|-
|make clog || fedpkg clog || Create the "clog" file from the %changelog of the specfile.
|-
|cvs commit -F clog . || fedpkg commit -F clog -p || Use the contents of file "clog" as the commit message.
|-
|make tag || N/A || Explicitly tagging source states for package builds is no longer necessary.
|-
|make build || fedpkg build || When successful on Koji, the build will be tagged in koji with the corresponding koji tag (e.g., dist-f15 for Rawhide and dist-f14-updates-candidate for F14). No git tag will be created as of 2010-08-06. You can use <code>git tag $(fedpkg verrel) && git push --tags</code> to do this manually.
|-
|BUILD_FLAGS="--nowait" make build || fedpkg build --nowait || See above. The --nowait option to the build command avoid your waiting (for the build to complete before freeing up the Shell)
|-
|make prep || fedpkg prep ||
|-
|make chain-build CHAIN='foo bar : baz'|| fedpkg chain-build foo bar : baz || Just like before, the current directory package is always added to the end of the CHAIN list.
|-
|make scratch-build || fedpkg scratch-build ||
|-
|make srpm || fedpkg srpm ||
|-
|make srpm-scratch-build || fedpkg srpm<BR>fedpkg scratch-build --srpm <name of srpm> || Ideally this would be made a single "fedpkg srpm-scratch-build" command
|-
|make local || fedpkg local ||
|-
|make x86_64 || fedpkg local --arch x86_64 ||
|-
|make upload FILES='apollo starbuck'|| fedpkg upload apollo starbuck || Remember, this adds new source files without replacing others.
|-
|make new-sources FILES='red_fish blue_fish' || fedpkg new-sources red_fish blue_fish || This replaces any existing source files.
|-
|make help || fedpkg help || "fedpkg -h" also works
|-
|./cvs-import.sh libfoo-1.2-3.src.rpm || fedpkg clone libfoo <BR> cd libfoo <BR> fedpkg import libfoo-1.2-3.src.rpm <BR> (Review Changes) <BR> fedpkg commit -p ||
|}


=== Anonymous checkout ===
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.


If you need anonymous clone (checkout) without fedpkg, you can use git: <pre>git clone git://pkgs.fedoraproject.org/libfoo</pre> for package <code>libfoo</code>
== Common fedpkg commands ==


=== Merging ===
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.


Merging is one of the things that we can now do directly in the VCS that we had to do with an external diff program in CVSGetting used to how it works may take a little adjustment though.
* Check out a package:
fedpkg co <source_package_name>
cd <source_package_name>
{{hidden|header=Details|content=This retrieves a copy of the package sources from the server. It's known as your 'working copy'.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Update your checked-out copy from the Fedora server:
fedpkg pull
* Retrieve the package sources:
fedpkg sources
{{hidden|header=Details|content=This pulls any sources stored in the "lookaside cache" (see below for more). Steps like {{command|fedpkg prep}} and {{command|fedpkg srpm}} will do this if necessary, but you may want a copy right away.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Make your changes to the package
{{hidden|header=Details|content=This is not an RPM packaging guide, so we'll assume you know what you're doing here. New sources and patches go in the working copy directory for now.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Run the 'prep' stage (extract source, apply patches etc) within the checkout directory:
fedpkg prep
{{hidden|header=Details|content=This is useful for making sure your patches apply cleanly, and inspecting the source tree if you need to do so.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Do a local build of the current state:
fedpkg local
{{hidden|header=Details|content=This is the simplest kind of test build, but it's usually cleaner and a better test to do a Mock or Koji scratch build (see below).|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Do a mock build of the current state:
fedpkg mockbuild
{{hidden|header=Details|content=This fires off a [[Projects/Mock|Mock]] build, if you have Mock configured correctly. [[Using_Mock_to_test_package_builds]] can help there. |headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Generate a .src.rpm from the current state:
fedpkg srpm
{{hidden|header=Details|content=You can request a [[Koji]] 'scratch build' (a test build, which will not go to any repository) of the generated .src.rpm with the {{command|koji build --scratch}} command (see {{command|man koji}}).|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Check changes you have made:
fedpkg diff
{{hidden|header=Details|content=This is handy for making sure you didn't touch something by mistake, or forget to bump the release, or forget to include a changelog...|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Run some checks (rpmlint) on your package:
fedpkg lint
* Stage any small patches or new source files for commit:
git add (somefile)
{{hidden|header=Details|content=git does not consider all files in the working directory to be a part of the git repository by default (handy, for keeping other files around that are relevant, like the source tree). This tells git to start considering these files as part of the repository ''locally''. When you 'commit' and 'push' later, this change is communicated to the server.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Upload new source files to the lookaside cache:
fedpkg new-sources
{{admon/warning|Alert|This will replace the current list of source files, not add to it. See ''Details'' for more details on the lookaside cache system.}}
  fedpkg upload
{{hidden|header=Details|content='Pristine' upstream sources (like release tarballs) and other larger source files are stored in the [[Package_Source_Control#Lookaside_Cache|lookaside cache]] system, not committed directly to git. This provides more efficient storage and transfer of the files. The {{filename|sources}} and {{filename|.gitignore}} files in the repository keep it in sync with the lookaside cache. Any time you use {{command|fedpkg new-sources}} or {{command|fedpkg upload}}, you must remember to 'commit' changes to those files.


==== Initial Merging ====
{{command|new-sources}} 'starts from scratch', replacing all files currently in the lookaside cache - you'll typically use this command for many packages with just a single source tarball, each time you update to a new upstream version. {{command|upload}} just adds the given file to those already in the cache. Do remember not to leave stale sources lying around.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Switch to a different release branch:
fedpkg switch-branch <f{{FedoraVersionNumber}}, el6, master>
{{hidden|header=Details|content=Each Fedora release has its own branch in each package repository so different builds can be sent to each release. See below for more details on working with branches.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Generate git changelog from package changelog:
fedpkg clog
{{hidden|header=Details|content=This command extracts your package changelog entry to the file {{filename|clog}}, so you can use it as the git changelog if you like. Some maintainers draw a distinction between the two, some do not.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Commit changes:
fedpkg commit (-F clog) (-p) (-c)
{{admon/note|Difference from git|This behaves by default like {{command|git commit -a}} - it stages all modified files, though it does not add unstaged files.}}
{{hidden|header=Details|content=This creates a sort of bundle, a 'commit', of your changes to the repository, with a unique identity and a changelog. Other maintainers - and you yourself, later - can view the history of changes to the repository with the 'commit' as the finest level of detail. It is good practice to use many relatively small commits, each for a single purpose - don't combine a version bump with a bunch of whitespace fixes and some scriptlet changes all in one commit, create separate commits for each.


First, the way we imported from cvs means that we have to do a little work to make the older release branches "mergable" (F-14, since it branched after the conversion to git, doesn't need this).
The {{command|-F clog}} parameter will use the {{filename|clog}} file from the previous step as the changelog. {{command|-p}} will push (see below) at the same time as committing. {{command|-c}} combines the {{command|clog}} and {{command|commit -F clog}} steps into one, if you like that.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Push changes:
fedpkg push
{{hidden|header=Details|content=This sends all the new 'commits' in your local working copy to the upstream server. If you are still learning the system, now is a good time to {{command|fedpkg co}} another copy of the repository somewhere else, compare what you get to your working copy, and run a test build on it.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Do an 'official' build of the latest pushed changes:
fedpkg build
{{admon/important|Going into production|This is the first point at which you might possibly cause real mess for a real user, so use it with caution.}}
{{admon/note|Uses pushed state|Unlike most of the above commands, this operates on the ''state you have pushed to git'', not the local state. If you have issues make sure you have pushed and committed all patches and handled the sources correctly.}}
{{hidden|header=Details|content=This triggers a 'real' (not scratch) build of your package in [[Koji]]. Depending on the release you are building for, it may go directly to the [[Repositories#stable|''stable'' state]] or it may have to run through the [[Updates Policy|update process]]. See the [[Package_update_HOWTO|package update guide]] for more details on this. The command will output a URL where you can monitor the build's progress in Koji.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}
* Submit a package update for the latest build:
fedpkg update
{{hidden|header=Details|content=Again, see the [[Package_update_HOWTO|package update guide]] for more details on this process.|headerstyle=background:#e5e5e5|fw1=normal|ta1=left}}


{{admon/note|Which branches should you apply this to?|For packages where F-12, F-13, the freshly branched F-14 and rawhide all have the same spec files and packages, merging all the branches together clearly makes sense. However, when, say F-12 and F-13 share a package NVR, and F-14 and rawhide do... what to do then? Merge the branches that are supposed to be the same, then.
== Typical ''fedpkg'' session ==
}}


A typical session may look like this:
<pre>
<pre>
fedpkg clone bzrtools
fedpkg clone foo
cd bzrtools
cd foo
git merge origin/f13/master
fedpkg sources
# If no conflicts proceed to the next step.
fedpkg new-sources foo-0.0.2.tar.bz2
# Otherwise, resolve the conflicts, git add & git commit, and then move on
gedit foo.spec      # change the required things in the specfile. rpmdev-bumpspec is useful for simple version updates
git merge origin/f12/master
fedpkg mockbuild    # check that the changes you made are correct
git merge origin/el6/master
fedpkg diff
git merge origin/el5/master
fedpkg lint
fedpkg commit -p -c  # commit and push in one go
</pre>
</pre>


Potentially better alternative to the above (without conflicts, without actually changing the master content, and merging ALL former CVS branches which are supposed to be the same package):
=== Merging ===


<pre>
Merging is one of the things that we can now do directly in the VCS that we had to do with an external diff program in CVS.  Getting used to how it works may take a little adjustment though.
fedpkg clone menu-cache
 
cd menu-cache
==== Initial Merging ====
# implicitly we have the master branch checked out here
git merge -m "Initial pseudo merge for dist-git setup" -s ours origin/{f12,f13}/master
</pre>


==== Merging in normal operation ====
==== Merging in normal operation ====

Revision as of 11:52, 25 September 2014

This page provides some basic instructions for day-to-day usage of the git-based package maintenance system for Fedora. It is intended primarily for new and current Fedora package maintainers, but does briefly 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:

Installing fedpkg and doing initial setup

The fedpkg tool will usually be your primary interface to the packaging system. Install it with yum install fedpkg, or any equivalent command. If you have not already done so, you will also need to install Package-x-generic-16.pngfedora-packager and run fedora-packager-setup. If you have run fedora-packager-setup before, but wish to set up a new machine for package maintenance, copy the files ~/.fedora*.cert to the new system.

You also must have an ssh key configured in the 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.

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.

  • Check out a package:
fedpkg co <source_package_name>
cd <source_package_name>
Details

This retrieves a copy of the package sources from the server. It's known as your 'working copy'.

  • Update your checked-out copy from the Fedora server:
fedpkg pull
  • Retrieve the package sources:
fedpkg sources
Details

This pulls any sources stored in the "lookaside cache" (see below for more). Steps like fedpkg prep and fedpkg srpm will do this if necessary, but you may want a copy right away.

  • Make your changes to the package
Details

This is not an RPM packaging guide, so we'll assume you know what you're doing here. New sources and patches go in the working copy directory for now.

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

This is useful for making sure your patches apply cleanly, and inspecting the source tree if you need to do so.

  • Do a local build of the current state:
fedpkg local
Details

This is the simplest kind of test build, but it's usually cleaner and a better test to do a Mock or Koji scratch build (see below).

  • Do a mock build of the current state:
fedpkg mockbuild
Details

This fires off a Mock build, if you have Mock configured correctly. Using_Mock_to_test_package_builds can help there.

  • Generate a .src.rpm from the current state:
fedpkg srpm
Details

You can request a Koji 'scratch build' (a test build, which will not go to any repository) of the generated .src.rpm with the koji build --scratch command (see man koji).

  • Check changes you have made:
fedpkg diff
Details

This is handy for making sure you didn't touch something by mistake, or forget to bump the release, or forget to include a changelog...

  • Run some checks (rpmlint) on your package:
fedpkg lint
  • Stage any small patches or new source files for commit:
git add (somefile)
Details

git does not consider all files in the working directory to be a part of the git repository by default (handy, for keeping other files around that are relevant, like the source tree). This tells git to start considering these files as part of the repository locally. When you 'commit' and 'push' later, this change is communicated to the server.

  • Upload new source files to the lookaside cache:
fedpkg new-sources
Warning.png
Alert
This will replace the current list of source files, not add to it. See Details for more details on the lookaside cache system.
fedpkg upload
Details

'Pristine' upstream sources (like release tarballs) and other larger source files are stored in the lookaside cache system, not committed directly to git. This provides more efficient storage and transfer of the files. The sources and .gitignore files in the repository keep it in sync with the lookaside cache. Any time you use fedpkg new-sources or fedpkg upload, you must remember to 'commit' changes to those files.

new-sources 'starts from scratch', replacing all files currently in the lookaside cache - you'll typically use this command for many packages with just a single source tarball, each time you update to a new upstream version. upload just adds the given file to those already in the cache. Do remember not to leave stale sources lying around.

  • Switch to a different release branch:
fedpkg switch-branch <f40, el6, master>
Details

Each Fedora release has its own branch in each package repository so different builds can be sent to each release. See below for more details on working with branches.

  • Generate git changelog from package changelog:
fedpkg clog
Details

This command extracts your package changelog entry to the file clog, so you can use it as the git changelog if you like. Some maintainers draw a distinction between the two, some do not.

  • Commit changes:
fedpkg commit (-F clog) (-p) (-c)
Note.png
Difference from git
This behaves by default like git commit -a - it stages all modified files, though it does not add unstaged files.
Details

This creates a sort of bundle, a 'commit', of your changes to the repository, with a unique identity and a changelog. Other maintainers - and you yourself, later - can view the history of changes to the repository with the 'commit' as the finest level of detail. It is good practice to use many relatively small commits, each for a single purpose - don't combine a version bump with a bunch of whitespace fixes and some scriptlet changes all in one commit, create separate commits for each.

The -F clog parameter will use the clog file from the previous step as the changelog. -p will push (see below) at the same time as committing. -c combines the clog and commit -F clog steps into one, if you like that.

  • Push changes:
fedpkg push
Details

This sends all the new 'commits' in your local working copy to the upstream server. If you are still learning the system, now is a good time to fedpkg co another copy of the repository somewhere else, compare what you get to your working copy, and run a test build on it.

  • Do an 'official' build of the latest pushed changes:
fedpkg build
Important.png
Going into production
This is the first point at which you might possibly cause real mess for a real user, so use it with caution.
Note.png
Uses pushed state
Unlike most of the above commands, this operates on the state you have pushed to git, not the local state. If you have issues make sure you have pushed and committed all patches and handled the sources correctly.
Details

This triggers a 'real' (not scratch) build of your package in Koji. Depending on the release you are building for, it may go directly to the stable state or it may have to run through the update process. See the package update guide for more details on this. The command will output a URL where you can monitor the build's progress in Koji.

  • Submit a package update for the latest build:
fedpkg update
Details

Again, see the package update guide for more details on this process.

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

Merging

Merging is one of the things that we can now do directly in the VCS that we had to do with an external diff program in CVS. Getting used to how it works may take a little adjustment though.

Initial Merging

Merging in normal operation

Now when you make changes on one branch and want to move them to a different branch, you can use git to merge those changes.

fedpkg clone bzrtools
# Make some changes in the master branch
fedpkg new-sources bzrtools-2.2.tar.gz
vim bzrtools.spec
git commit
fedpkg switch-branch f14
git merge master
# for push into repo
git push

Resolving merge conflicts

When you git merge and a conflict occurs you still edit the files that have conflicts. Remove the conflict markers in the files and merge the changes manually. Then you need to commit your changes. Do that with git add CONFLICTEDFILES ; git commit

Using git mergetool to resolve conflicts

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

git config --global merge.tool meld
fedpkg switch-branch f13
git merge master
# Conflicts occurred
git mergetool # Opens up a meld showing a three way diff of the merge, working tree, and the last commit
# Resolved all the conflicts in the GUI
git add CONFLICTEDFILES
git commit

Branch names

Old CVS new remote git fedpkg local branch names Notes
devel origin/master master This is the default when you do fedpkg co
F-16 origin/f16/master f16
F-15 origin/f15/master f15
F-14 origin/f14/master f14
EL-6 origin/el6/master el6
EL-5 origin/el5/master el5
Note.png
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 fedpkg switch-branch, it will default to creating the names listed in the table above. So you can do fedpkg clone firefox ; fedpkg switch-branch f14 and then you'll have a new local branch named f14
Idea.png
Display current branch in your 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 here.

Errors

Access denied

During the next few days and weeks, occasional tweaking to the servers might cause short periods (seconds or minutes) when the git server refuses you access. Just try again.

Unable to switch

If you are trying switch to another branch by fedpkg switch-branch f13 and see this: Unable to switch to another branch: Could not create branch f13

Then you probably have some un-commited changes in master. If you want them, call:

# this "saves" your changes
git stash
# switch to preferred branch, now possible
fedpkg switch-branch f13
# apply "saved" changes into the current branch
git stash apply

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.

References