From Fedora Project Wiki

No edit summary
No edit summary
Line 1: Line 1:
= What is Eclipse Fedora Packager? =
= Fedora Package Process =
This user guide will demonstrate how to create a RPM package using eclipse Fedora Packager.
=== Create Account ===
If you are a new package maintainer:
* Create a new account on [https://admin.fedoraproject.org/accounts Fedora Account System (FAS)]
** Click on 'New account' and fill in the blanks.
**After you create your account, please be sure to sign the CLA (if you click on the "My Account" link in the top right, you should see CLA: CLA Done).
**Also you need to upload a public RSA SSH key. You need to use the matching private key to access Fedora machines via SSH.
*** Here is information on [http://www.openbsd.org/cgi-bin/man.cgi?query=ssh-keygen creating SSH key].
* Create an account in Red Hat [https://bugzilla.redhat.com/createaccount.cgi bugzilla].
* Install the client tools
** To build Packages for the Fedora Collection or [http://fedoraproject.org/wiki/EPEL EPEL], you need [http://fedoraproject.org/wiki/Using_the_Koji_build_system Koji].
** You'll also need to [https://admin.fedoraproject.org/accounts/user/gencert generate a client side certificate at the Fedora Account System] and save the file in ~/.fedora.cert, where fedpkg will look for it by default.
** You can now use "koji" to try to build your RPM packages on platforms (e.g., PPC) or distributions you don't have. Note that you can test out builds ("scratch" builds) even when your package hasn't been approved and you don't have a sponsor. [http://fedoraproject.org/wiki/Join_the_package_collection_maintainers#Install_the_Client_Tools_.28Koji.29 Here] is a simple way to do a scratch build using koji on the command line.


Eclipse Fedora Packager is a plug-in for Eclipse. It helps Fedora packagers who are used to IDEs (such as Eclipse IDE), to package their Fedora RPMs from within Eclipse without needing to resort to the command line. (at least for the most part :-) ).
=== Make a Package ===
* Make sure it is a new package. Check this [https://admin.fedoraproject.org/pkgdb/acls/list/ list] of existing packages.
* Create an RPM package:
** Select "File->New->Other..." from the main menu. Choose "RPM->RPM Project", click "Next".
** Input the "Project name". Click "Finish".
** Right click on SPECS, select "New->Other...", choose "RPM->Specfile Based on a Template", click "Next".
** Fill out the template or accept the default values and customize it based your package specifications.
*** You can also use RPM-stubby plug-in to create a spec-file stub.
** To send your SRPM/Spec-file for review, select "File->Export" from the main munu, choose "RPM->Source/Binary RPM", click "Next".
** Based on your requirements, select one or both options, click "Finish".
* Make sure it is a suitable package
** Check [http://fedoraproject.org/wiki/Packaging:Guidelines Packaging Guidelines] and [http://fedoraproject.org/wiki/Packaging:NamingGuidelines Packaging Naming Guidelines] to see if it meets the requirements
** Read some other package submissions to learn about packaging and gain familiarity with the process and requirements. One way of doing this is to join the package-review@lists.fedoraproject.org mailing list.


'''Some features included in the Eclipse Fedora Packager are:'''
(provide space to enter URL of hosted SRPM/.spec or scp to fedorapeople.org) and create review-request bug (using mylyn)


* Conveniently clone Fedora Git projects
=== Submit For Review ===
* RPM-spec-file editor with syntax highlighting, auto-completion and changelog support (<Ctrl>+<Alt>+C keyboard shortcut)
* Join the mailing lists (--'''Are all these info for mailing list necessary here, or shall we just put a link to them: http://fedoraproject.org/wiki/Join_the_package_collection_maintainers#Join_the_important_Mailing_Lists?''')
* Download source files and upload new source files
** When a new package maintainer joins the Fedora Project, we request that he/she introduces themselves on the devel@lists.fedoraproject.org. To sign up for the list, visit the devel list signup page . The primary purpose of this is to begin the process of building trust by learning about the package maintainer and increase the chances of your review request being processed sooner.
* Prepare local builds (execute %prep section of your spec-file only)
***The purpose of all this is to break anonymity and foster real-world community within the project. You are under no obligation to reveal personal secrets. The objective is to establish a level of trust with yourself and the other members of the project.
* Create source RPM files based on current spec-file
***Subject: Self Introduction
* Execute local builds
***Body: Add any information you believe is applicable including past experience, a link to the review request you have filed and a brief description of yourself. You can also post your GPG key information if you want to.
* Push builds to Koji (the Fedora build system)
**You must join the fedora devel-announce@lists.fedoraproject.org mailing list. It is a low traffic announcements only list, where important development information is posted.
* Mock builds
**You can join the fedora devel@lists.fedoraproject.org mailing list, where discussions about the development of Fedora are held. This is a high traffic mailing list.
* Push Bodhi updates
**You can also consider joining the package-announce@lists.fedoraproject.org mailing list -- The commits mailing list gets notifications on all commits in any package in the Fedora repository. This is a very high traffic mailing list. The Fedora package database sends commit mails for packages you (co-)maintain.
* Eclipse Git support (via EGit, please refer to EGit documentation)
**Another mailing list you might consider (at least to view the archives) is packaging@lists.fedoraproject.org. This is the mailing list of the Fedora Packaging Committee, who determine the official packaging guidelines for Fedora projects.
* Upload your package
** Upload your SRPM and SPEC files onto the Internet somewhere. This can be anywhere accessible by a URL.
** If you need hosting space, please make a note of it in your ticket submission and someone will take care of you.
** If you have already got a Fedora Account then you can use your storage at <user-name>.fedorapeople.org for this.
* Create your review request
** Fill out this form at [https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review bugzilla].
** Before submitting your request, be sure there’s not a previous request for the same package.
** Make sure that you put the name of the package (excluding version and release numbers) in the 'Review Summary' field, along with a very brief summary of what the package is.
** Put a description of your package (usually, this can be the same thing as what you put in the spec %description) in the 'Review Description' field.
** Include the URLs to your SRPM and SPEC files.
** If this is your first package, explain it and say that you need a sponsor.
* Watch the bugzilla report for feedback
** You should get notifications of changes by email. Fix any blockers that the reviewer(s) point out.


Eclipse Fedora Packager has been available for Fedora users since F14. Want to try it out? Issue the following command to install it:
=== Ready to Ship ===
Follow these steps after your package is approved by reviewers.
* Obtain member sponsorship (to check in and build your package)
** you must separately obtain member sponsorship in order to check in and build your package. Sponsorship is not automatic and may require that you further participate in other ways in order to demonstrate your understanding of the packaging guidelines.
** Key to becoming sponsored is to convince an existing sponsor-level member that you understand and follow the project's guidelines and processes.
** See [http://fedoraproject.org/wiki/How_to_get_sponsored_into_the_packager_group how to get sponsored into the packager group] for more information.
*  Add package to Source Code Management (SCM) system and Set Owner
When the package is approved by the reviewer, request a git module and branches with the [http://fedoraproject.org/wiki/Package_SCM_admin_requests SCM admin requests].
* Check out the empty module from SCM
** Once you have the git module, checkout your module from git.
*** Select "import->Git->Projects from Fedora Git" and click on Next.
*** Input the name of the package in the "Package name".
** It is probably a good idea to make a "git" toplevel directory, then check-out your files inside of that. (--'''Do we need this line?''')


<pre>
=== Update your SCM ===
yum install eclipse-fedorapackager
* Import and commit your SRPM into master branch
</pre>
** Right click on your rpm file in SRPMS folder on your local RPM project in eclipse, select "Copy".
 
** Right click on your cloned project from Fedora Git, select "Paste". (--'''We can consider making it simpler by just one click on RPM project''')
= Using Eclipse Fedorapackager =
** Right click on pasted file, select "Fedora Packager->Upload this File->Add to Existing Sources".
 
** Do the same steps for your .spec file.
Since Fedora 14, the Git version control system for keeping track of files required for Fedora packaging is used. See the [https://fedoraproject.org/wiki/Dist_Git_Project dist-git documentation] for in depth information about dist-git. Fortunately, how dist-git works when using the Eclipse Fedora Packager plug-in is unimportant. There is only a slightly different approach for doing packaging work compared to what might have been used with CVS instead of Git.
* Build your package
 
** Select your spec file, right click, select "Fedora Packager->Prepare for local build".
== Initial Setup ==
--'''what are the other steps here? -"Build for Local Architecture", then "Local Build using Mock" then "push the build to Koji"?'''
 
--'''Do we actually need to put all of them here or just refer to "Fedora Packager User Guide" in Eclipse help?'''
This step is only required to be completed once for a new Fedora packager or if using a new machine that does not have required FAS certificates set up. When it is certain this is correct it is safe to skip this step. The following explains how to set up those certificates for a [https://admin.fedoraproject.org/accounts/ FAS account]?
* Submit your package as update in Bodhi
 
**  If this package will be built for any version of Fedora that is already released please submit it for inclusion in the 'fedora-updates' repository for those versions of Fedora.  
First, install the <code>fedora-packager</code> RPM package:
** For doing this, right click on your project, select "Fedora Packager->Create New Bodhi Update".
 
* Close the bugzilla account
<pre>
** If the package built successfully, you should close it as NEXTRELEASE.
yum install fedora-packager
* Add the package to the comp files
</pre>
** If appropriate for the package, make it available in "comps" files so that it can be selected during installation and included in yum's package group operations. See [http://fedoraproject.org/wiki/PackageMaintainers/CompsXml PackageMaintainers/CompsXml] for more info.
 
* Enable Upstream Release Monitoring
Then run the following command and simply follow the instructions provided:
** Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging. Refer to [http://fedoraproject.org/wiki/Upstream_Release_Monitoring Upstream Release Monitoring] for more details.
 
<pre>
$ fedora-packager-setup
</pre>
 
Once this is done Eclipse Fedorapackager is ready for use. Fire up Eclipse. Let's get started. Yay!
 
== Importing a Fedora Git Project ==
 
Getting started is easy. Go to "File" => "Import" => "Git" => "Projects from Fedora Git". This will clone the desired Git repository and create necessary local branches. For convenience, the "Git Repositories" view will also open once the clone process has finished.  
 
[[Image:ImportFedoraGit.png|Fedora Git Import]]
 
Here's how the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.
 
[[Image:SelectPackageNameGit.png|Select Package Name]]
 
Once the new project has been created something akin to the following is seen. Note the branches in the Git Repository view and "[eclipse-fedorapackager master]" right beside the project name. In this case, ''eclipse-fedorapackager'' refers to the Git repository name and ''master'' to the currently checked out branch.
 
[[Image:GitProjectBranchesView.png|Git Branch View]]
 
== Fedora Packaging Work ==
 
After a Fedora Git project has been created, all files required for packaging the desired release can be found in the created Eclipse project directly. For example, files for release Fedora 13 correspond to files present in the Eclipse project one switched to branch '''f13/master'''. Files in branch '''master''' correspond to '''Fedora rawhide''', the current development release of Fedora. The following is a brief description of things to consider doing while packaging up some software. Working in a different sequence works, but keep in mind that before trying a Koji build '''push your locally committed changes to the public repository'''.
 
=== Uploading Source Files Required for a Package ===
 
In order to upload new sources in Eclipse Fedora Packager, first download upstream sources and place the downloaded sources in the same folder as the Eclipse project. If this is done outside of Eclipse, don't forget to refresh the project afterwards (F5) so that the file actually shows up. A slick way to download sources is to use RPM editor functionality directly. See its [http://wiki.eclipse.org/Linux_Tools_Project/SpecfileEditor/User_Guide documentation] for more information on this. Once the new source file is available in the project, it can be uploaded to the lookaside cache by right-clicking on the file=> "Fedora Packager" => Upload This File => Replace/Add File. This either adds the file to the sources required to build the package or replaces the current content of the <code>sources</code> file to contain a single line with the MD5 sum of the file selected.  
 
A valid certificate is required to upload to the lookaside cache. If it has expired, a new one can be created by issuing the following command on a terminal:
 
<pre>
$ fedora-cert -n
</pre>
 
=== Downloading Source Files Required for a Package ===
 
To download the required source files for an existing package in order to build it, right-click on the spec-file => "Fedora Packager" => Download Sources. This downloads all sources listed in the file <code>sources</code>.
 
=== Using the Spec-File Editor ===
 
Eclipse Fedora Packager uses the RPM Editor and ChangeLog plug-in from the Eclipse Linux Tools project (http://www.eclipse.org/linuxtools). For instance, a new ChangeLog entry can easily be created in the spec-file by using the <CTRL>+<ALT>+C keyboard shortcut (though a good idea is to set appropriate “ChangeLog” preferences first). Using <CTRL>+<SPACE> auto-completes locally installed packages. Also, rpmlint can be run by right-clicking on the spec-file => “Run Rpmlint”. For more information have a look at the spec-file editor screencast: http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg or at the "Specfile Editor User Guide": Help => Help Contents => Specfile Editor User Guide.
 
=== Committing Changes to the Local Git Repository ===
 
After the spec-file, patches etc. have been added/changed, commit those changes to the repository. This is done by:
 
# Selecting the files to commit (alternatively select the Fedora Git project and select desired ''unstaged'' files when the commit dialog is shown)
# Right-click, "Team" => "Commit..."
 
[[Image:GitCommit.png|Git Commit]]
 
=== Switching Branches (Git Checkout) ===
 
Switching branches is as easy as double-clicking on the desired local branch to be worked on. The currently checked out branch is indicated to the left of the project name. Make sure to commit, revert, or stash changes before switching to a different branch. Refer to the [http://www.kernel.org/pub/software/scm/git/docs/ Git] and [http://wiki.eclipse.org/EGit/User_Guide EGit] documentation for more information on this.
 
=== Prepare Sources for a Local Build ===
 
Eclipse Fedora Packager will download and prepare sources by right-clicking on the spec-file => “Fedora Packager” => “Prepare Sources for Build”.
 
[[Image:PrepareSourcesForBuild.png|Prepare Sources for Build]]
 
=== Build RPM for a Local Architecture ===
 
This is a great way to test if the spec-file actually builds at all. Once the RPM has been successfully built locally, it is recommended further testing be carried out on the spec-file by completing a build in a chroot'ed environment using <code>mock</code>. Both ways are supported by Eclipse Fedora Packager.
 
The RPM can be built locally by selecting the spec-file => right-click => “Fedora Packager” => “Build for Local Architecture”. Output of the RPM build will appear on the Eclipse console.
 
Using mock-builds is a great way to test the “Requires/BuildRequires” of a spec-file. Select the spec-file => right-click => “Fedora Packager” => “Local Build Using Mock”. Be aware that this may take a long time (>20 minutes) and requires the mock package to be installed. Use Eclipse's “Run in Background” functionality for convenience.
 
=== Make Locally Committed Changes Public (Git Push) ===
 
The changes are ready to be pushed (or published) publicly when the locally committed changes are satisfying. Remember, Git allows history to be rewritten before changes are made public. See the [http://www.kernel.org/pub/software/scm/git/docs/ Git] and [http://wiki.eclipse.org/EGit/User_Guide EGit] documentation for more information. To bring the local repository in sync with ''origin'':
 
# Select the Fedora Git project
# Right-click, "Team" => "Push..."
# Select the Git repository to be pushed to (usually this is kept unchanged)
# Select the Git references to be pushed
# Carry out the push operation
 
The Git push dialog.
 
[[Image:GitPushDialog.png|Git Push Dialog]]
 
Select the Git references to push. In this example, branches ''master'' and ''f14/master'' will get pushed. Keep in mind that source and destination references are the same for Eclipse Fedora Packager. Clicking the “Add all branches spec” button is a convenience that pushes all commits to all local branches.
 
[[Image:SelectGitReferencesToPush.png|Select Git References]]
 
=== Pushing a Build to Koji ===
 
Once satisfied with a spec-file, upload the sources of the package, commit the changes to the local repository, and then push the local changes to the remote repository. When this is done, push a build to Koji by right-clicking the spec-file => “Fedora Packager” => “Push to Koji”.
 
[[Image:EclipseFedoraPackagerPushBuildToKoji.png]]
 
Eclipse will pop up a message with the Koji URL to track your build. This is an example of how the message may look:
 
[[Image:KojiBuildPopupMessage.png|Koji Popup Dialog]]
 
This should be enough information to track the builds.
 
=== Pushing a Bohi Update ===
 
After successfully building the RPMs, use Eclipse Fedora Packager to push an update for those packages. To do so, select the spec-file => right click => "Fedora Packager" => "Bodhi Update". When creating a Bodhi update using Eclipse Fedora Packager, similar information is required as needed by the Bodhi Web interface. Once an update has successfully been created, the pushed update will be visible on the Bodhi updates website. The status of updates can also be tracked there.
 
= Feedback/Reporting Bugs =
 
If a bug is found in the Eclipse Fedora Packager, please feel free to open a ticket at https://fedorahosted.org/eclipse-fedorapackager/report/1 (a FAS username is required to create tickets). Alternatively, try [https://bugzilla.redhat.com/buglist.cgi?query_format=advanced&bug_status=NEW&bug_status=ASSIGNED&bug_status=MODIFIED&component=eclipse-fedorapackager&product=Fedora&classification=Fedora this query] on RedHat Bugzilla in order to find already existing bugs. Thanks!

Revision as of 19:05, 27 May 2011

Fedora Package Process

This user guide will demonstrate how to create a RPM package using eclipse Fedora Packager.

Create Account

If you are a new package maintainer:

  • Create a new account on Fedora Account System (FAS)
    • Click on 'New account' and fill in the blanks.
    • After you create your account, please be sure to sign the CLA (if you click on the "My Account" link in the top right, you should see CLA: CLA Done).
    • Also you need to upload a public RSA SSH key. You need to use the matching private key to access Fedora machines via SSH.
  • Create an account in Red Hat bugzilla.
  • Install the client tools
    • To build Packages for the Fedora Collection or EPEL, you need Koji.
    • You'll also need to generate a client side certificate at the Fedora Account System and save the file in ~/.fedora.cert, where fedpkg will look for it by default.
    • You can now use "koji" to try to build your RPM packages on platforms (e.g., PPC) or distributions you don't have. Note that you can test out builds ("scratch" builds) even when your package hasn't been approved and you don't have a sponsor. Here is a simple way to do a scratch build using koji on the command line.

Make a Package

  • Make sure it is a new package. Check this list of existing packages.
  • Create an RPM package:
    • Select "File->New->Other..." from the main menu. Choose "RPM->RPM Project", click "Next".
    • Input the "Project name". Click "Finish".
    • Right click on SPECS, select "New->Other...", choose "RPM->Specfile Based on a Template", click "Next".
    • Fill out the template or accept the default values and customize it based your package specifications.
      • You can also use RPM-stubby plug-in to create a spec-file stub.
    • To send your SRPM/Spec-file for review, select "File->Export" from the main munu, choose "RPM->Source/Binary RPM", click "Next".
    • Based on your requirements, select one or both options, click "Finish".
  • Make sure it is a suitable package
    • Check Packaging Guidelines and Packaging Naming Guidelines to see if it meets the requirements
    • Read some other package submissions to learn about packaging and gain familiarity with the process and requirements. One way of doing this is to join the package-review@lists.fedoraproject.org mailing list.

(provide space to enter URL of hosted SRPM/.spec or scp to fedorapeople.org) and create review-request bug (using mylyn)

Submit For Review

  • Join the mailing lists (--Are all these info for mailing list necessary here, or shall we just put a link to them: http://fedoraproject.org/wiki/Join_the_package_collection_maintainers#Join_the_important_Mailing_Lists?)
    • When a new package maintainer joins the Fedora Project, we request that he/she introduces themselves on the devel@lists.fedoraproject.org. To sign up for the list, visit the devel list signup page . The primary purpose of this is to begin the process of building trust by learning about the package maintainer and increase the chances of your review request being processed sooner.
      • The purpose of all this is to break anonymity and foster real-world community within the project. You are under no obligation to reveal personal secrets. The objective is to establish a level of trust with yourself and the other members of the project.
      • Subject: Self Introduction
      • Body: Add any information you believe is applicable including past experience, a link to the review request you have filed and a brief description of yourself. You can also post your GPG key information if you want to.
    • You must join the fedora devel-announce@lists.fedoraproject.org mailing list. It is a low traffic announcements only list, where important development information is posted.
    • You can join the fedora devel@lists.fedoraproject.org mailing list, where discussions about the development of Fedora are held. This is a high traffic mailing list.
    • You can also consider joining the package-announce@lists.fedoraproject.org mailing list -- The commits mailing list gets notifications on all commits in any package in the Fedora repository. This is a very high traffic mailing list. The Fedora package database sends commit mails for packages you (co-)maintain.
    • Another mailing list you might consider (at least to view the archives) is packaging@lists.fedoraproject.org. This is the mailing list of the Fedora Packaging Committee, who determine the official packaging guidelines for Fedora projects.
  • Upload your package
    • Upload your SRPM and SPEC files onto the Internet somewhere. This can be anywhere accessible by a URL.
    • If you need hosting space, please make a note of it in your ticket submission and someone will take care of you.
    • If you have already got a Fedora Account then you can use your storage at <user-name>.fedorapeople.org for this.
  • Create your review request
    • Fill out this form at bugzilla.
    • Before submitting your request, be sure there’s not a previous request for the same package.
    • Make sure that you put the name of the package (excluding version and release numbers) in the 'Review Summary' field, along with a very brief summary of what the package is.
    • Put a description of your package (usually, this can be the same thing as what you put in the spec %description) in the 'Review Description' field.
    • Include the URLs to your SRPM and SPEC files.
    • If this is your first package, explain it and say that you need a sponsor.
  • Watch the bugzilla report for feedback
    • You should get notifications of changes by email. Fix any blockers that the reviewer(s) point out.

Ready to Ship

Follow these steps after your package is approved by reviewers.

  • Obtain member sponsorship (to check in and build your package)
    • you must separately obtain member sponsorship in order to check in and build your package. Sponsorship is not automatic and may require that you further participate in other ways in order to demonstrate your understanding of the packaging guidelines.
    • Key to becoming sponsored is to convince an existing sponsor-level member that you understand and follow the project's guidelines and processes.
    • See how to get sponsored into the packager group for more information.
  • Add package to Source Code Management (SCM) system and Set Owner

When the package is approved by the reviewer, request a git module and branches with the SCM admin requests.

  • Check out the empty module from SCM
    • Once you have the git module, checkout your module from git.
      • Select "import->Git->Projects from Fedora Git" and click on Next.
      • Input the name of the package in the "Package name".
    • It is probably a good idea to make a "git" toplevel directory, then check-out your files inside of that. (--Do we need this line?)

Update your SCM

  • Import and commit your SRPM into master branch
    • Right click on your rpm file in SRPMS folder on your local RPM project in eclipse, select "Copy".
    • Right click on your cloned project from Fedora Git, select "Paste". (--We can consider making it simpler by just one click on RPM project)
    • Right click on pasted file, select "Fedora Packager->Upload this File->Add to Existing Sources".
    • Do the same steps for your .spec file.
  • Build your package
    • Select your spec file, right click, select "Fedora Packager->Prepare for local build".

--what are the other steps here? -"Build for Local Architecture", then "Local Build using Mock" then "push the build to Koji"? --Do we actually need to put all of them here or just refer to "Fedora Packager User Guide" in Eclipse help?

  • Submit your package as update in Bodhi
    • If this package will be built for any version of Fedora that is already released please submit it for inclusion in the 'fedora-updates' repository for those versions of Fedora.
    • For doing this, right click on your project, select "Fedora Packager->Create New Bodhi Update".
  • Close the bugzilla account
    • If the package built successfully, you should close it as NEXTRELEASE.
  • Add the package to the comp files
    • If appropriate for the package, make it available in "comps" files so that it can be selected during installation and included in yum's package group operations. See PackageMaintainers/CompsXml for more info.
  • Enable Upstream Release Monitoring
    • Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging. Refer to Upstream Release Monitoring for more details.
Retrieved from "https://fedoraproject.org/w/index.php?title=Eclipse_How_to_Maintain_Fedora_Package_User_Guide&oldid=238327"