From Fedora Project Wiki

No edit summary
(Redirect Package Maintainer wiki links to docs.fp.o)
 
(142 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=Introduction=
= What is Eclipse Fedora Packager? =
Eclipse Fedora Packager is a plug-in for Eclipse that has been available for Fedora users since F14. 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 :-) ).


There are many ways to generate help content in Eclipse. One particular method involves generating your help content from the wiki which allows you to crowdsource your documentation. By having your documentation on the wiki, you lower the barrier of entry for people to contribute documentation. The purpose of this wiki entry is to guide you through an example of how you can crowdsource your documentation using Mylyn WikiText.
'''Some features included in the Eclipse Fedora Packager are:'''


=What is WikiText=
* Conveniently clone Fedora Git projects
* RPM .spec file editor with syntax highlighting, auto-completion of package names for Requires/BuildRequires templates, <code>%changelog</code> support (<code>Ctrl+Alt+c</code> keyboard shortcut), etc.
* Download source files and upload new source files
* Prepare local builds (execute <code>%prep</code> section of your .spec file only)
* Create source RPMs based on current .spec file
* Perform local builds
* Push builds to Koji (the Fedora build system)
* Mock builds
* Push Bodhi updates
* Eclipse Git support (via EGit, please refer to [http://wiki.eclipse.org/EGit/User_Guide EGit documentation])


Mylyn WikiText provides an extensible framework and tools for parsing, editing and presenting lightweight markup. On top of that, it has a wiki text editor for Eclipse and Ant tasks for converting lightweight markup to HTML and other formats. In this specific example, we will be using WikiText's ability to convert Mediawiki content into Eclipse help content.


[[Image:What-is-wikitext.png]]
Feel free to [[Eclipse_How_to_Maintain_Fedora_Package_User_Guide#Using_Eclipse_Fedorapackager|skip the next section]] if you already know how to package new software for Fedora.


=A Simple Example=
= Getting Started as Maintainer for a New Fedora Package =
If you haven't previously packaged software for Fedora, this guide will lead you through your first package submission.
<br/>
Wiki changes the image file names that start with lowercase to uppercase.<br/>
eg. this image with name lowercase.png will convert the image file name <br/>
to Lowercase.png, but the html file will stay as it is now.
<br/>


The best way to learn is by doing. As an example, we will take this wiki entry and create some Eclipse help content from it. To accomplish this, we will use Ant so you can easily integrate this into a build if you wish.
[[Image:lowercase.png|lowercase image]]


==Setting up the Classpath==


The first order of business is to setup your Ant classpath so you can use the WikiText Ant tasks.


You can [http://www.eclipse.org/downloads/download.php?file=/tools/mylyn/update/weekly/mylyn-wikitext-standalone-latest.zip download] the WikiText SDK which contains the jars you'll need. In our case, we only need the org.eclipse.mylyn.wikitext.core_1.3.0.I20100116-0000-e3x.jar and org.eclipse.mylyn.wikitext.mediawiki.core_1.3.0.I20100116-0000-e3x.jar since we are only working with Mediawiki. If we were working with something like confluence, we would have to grab the respective JAR and put it on our classpath.
<br/><br/><br/><br/><br/><br/>


In the end, your Ant file will look something like the snippet below.


<pre style="width: 60em;">
<path id="wikitext.tasks.classpath">
<fileset dir="lib">
<include name="org.eclipse.mylyn.wikitext.*core*.jar"/>
</fileset>
</path>


<taskdef classpathref="wikitext.tasks.classpath"
[[Image:FedoraMaintainPackage.png|fedora submit package]]
  resource="org/eclipse/mylyn/internal/wikitext/mediawiki/core/tasks/tasks.properties"/>
 
<taskdef classpathref="wikitext.tasks.classpath"
== Creating Account for New Contributors ==
resource="org/eclipse/mylyn/wikitext/core/util/anttask/tasks.properties"/>
If you are a new package maintainer:
=== Creating a new account in Fedora Account System ===
* First step is to create account in [https://admin.fedoraproject.org/accounts Fedora Account System (FAS)].
* Click '''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 <code>CLA: CLA Done</code>).
* Also you need to upload a public <code>RSA SSH key</code>. 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].
 
=== Creating a Bugzilla Account===
Create an account in [https://bugzilla.redhat.com/createaccount.cgi Red Hat bugzilla].
* The email address that you use for your bugzilla account should be the same email address as you use in the ''Fedora Account System'' for all things related to fedora packaging.
* To make you work and your bug tracking easier, there is a task management plug-in for eclipse called '''Mylyn'''. You can follow these instructions on [[Eclipse_How_to_Maintain_Fedora_Package_User_Guide/mylyn_bugzilla|how to integrate your bugizlla account with your mylyn plug-in in eclipse]].
 
=== Initial Setup ===
 
This step is only required to be completed once for a new Fedora packager or if using a new machine that does not have the 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 an [https://admin.fedoraproject.org/accounts/ FAS account].<br/>
First, install the <code>fedora-packager</code> RPM package:
<pre>  yum install fedora-packager </pre>
Then run the following command and follow the instructions provided:
<pre>  fedora-packager-setup </pre>
 
== Making a Package ==
=== Packaging Guidlines ===
* If you don't know how to create an RPM package, refer to the tutorial at [[A_Short_RPM_Tutorial|A Short RPM Tutorial]] or the more advanced and much more detailed [[How_to_create_an_RPM_package|how to create an RPM package]].
* Make sure it is a new package. Check this [https://admin.fedoraproject.org/pkgdb/acls/list/ list of existing packages].
* Make sure it is a suitable package. Read [[Packaging:Guidelines|Packaging Guidelines]] and [[Packaging:NamingGuidelines|Packaging Naming Guidelines]].
* 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 [https://admin.fedoraproject.org/mailman/listinfo/package-review package-review@lists.fedoraproject.org] mailing list.
 
=== Creating an RPM package: ===
Perform the following steps to create an RPM package:
# Select '''File''' > '''New''' > '''Other...''' from the main menu. Choose '''RPM''' > '''RPM Project''', click '''Next'''.<br/>
# Type the '''Project name'''. Click '''Finish'''.<br/>
# Right click on SPECS, select '''New''' > '''Other...''', choose '''RPM''' > '''Specfile Based on a Template''', click '''Next'''.<br/>
# Fill out the template or accept the default values and customize it based your package specifications. You may use specific templates (e.g. for Perl or Java packages) to create a .spec file stub.
# When your package is ready to submit for review, select '''File''' > '''Export''' from the main munu, choose '''RPM''' > '''Source/Binary RPM''', click '''Next'''.<br/>
# Based on your requirements, select one or both options, click '''Finish'''.<br/>
* For more information have a look at the "Specfile Editor User Guide": '''Help''' > '''Help Contents''' > '''Specfile Editor User Guide'''.
 
== Submiting For Review ==
=== Joining the Possible Fedora Mailing Lists ===
When a new package maintainer joins the Fedora Project, we request that he/she introduces themselves on the [https://admin.fedoraproject.org/mailman/listinfo/devel 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.
* Here is the information of [https://docs.fedoraproject.org/en-US/package-maintainers/Joining_the_Package_Maintainers/#join_the_important_mailing_lists Join_the_important_Mailing_Lists possible mailing lists] for you to join. And there is also a list of [[Category:Packaging_SIGs|special interest groups for Fedora Packaging]].
 
=== Uploading the 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 <code><user-name>.fedorapeople.org</code> for this.
 
Example:
<pre> scp path/to/file.spec path/to/rpm-file.src.rpm <user-name>.fedorapeople.org:public_html </pre>
<code>file.spec</code> and <code>rpm-file.src.rpm</code> will then be available via the following URLs:
<pre>
http://<user-name>.fedorapeople.org/file.spec
http://<user-name>.fedorapeople.org/rpm-file.src.rpm
</pre>
</pre>


==Converting to Eclipse Help==
=== Creating Review Request ===
Before submitting your request, be sure there is not a previous request for the same package.
* Fill out this form at [https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&format=fedora-review bugzilla].
* 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 <code>%description</code>) 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.
 
=== Bugzilla feedback ===
* You should get notifications of changes by email. Fix any blockers that the reviewer(s) point out.


After we have setup the classpath for our task, we need to go and fetch the wiki content and convert it to Eclipse help. This is accomplished via the '''mediawiki-to-eclipse-help Ant''' task.


In the end, your Ant file will look something like the snippet below.
== Ready to Ship ==
Follow these steps after your package is approved by reviewers.
=== Obtaining Member Sponsorship ===
After your package is approved by reviewers, you must separately obtain member sponsorship 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 [https://docs.fedoraproject.org/en-US/package-maintainers/How_to_Get_Sponsored_into_the_Packager_Group/ how to get sponsored into the packager group] for more information.


<pre style="width: 60em;">
=== Requesting a new package SCM ===
When the package is approved by the reviewer, request a git module and branches with the [http://fedoraproject.org/wiki/Package_SCM_admin_requests Source Code Management(SCM) admin requests].
* Mention the name of the branches you need your package to be included in.


<mediawiki-to-eclipse-help
=== Checking Out the Empty Module from SCM ===
    wikiBaseUrl="http://wiki.eclipse.org"
Once you have the git module, clone your module from git.
validate="true"
failonvalidationerror="true"
prependImagePrefix="images"
formatoutput="true"
defaultAbsoluteLinkTarget="doc_external"
    dest="${basedir}"
    title="Crowdsourcing Documentation"
    generateUnifiedToc="false">
    <path name="DocumentationGuidelines/Example"
                title="Crowdsourcing Documentation"
                generateToc="true"/>
    ...
</pre>


When the Ant task is executed... the wiki content will be transformed into HTML and a respective Eclipse help TOC XML will be generated.
*  Go to '''File''' > '''Import''' > '''Git''' > '''Projects from Fedora Git''' and enter your package name when prompted. This will clone the desired Git repository. Refer to this user guide on [[Using_Fedora_GIT|Using Fedora Git]] for more information.  
* For convenience, the ''Git Repositories view'' will also open once the clone process has finished. <br/><br/>


[[Image:Crowdsourcing-toc.png]]
[[Image:ImportFedoraGit.png|Fedora Git Import]]<br/><br/>


When you self-host and launch Eclipse Help in the self-hosted instance, you should see this content there as shown below.
* Here's what the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.<br/><br/>


[[Image:Crowdsourcing-help-content.png]]
[[Image:SelectPackageNameGit.png|Select Package Name]]<br/><br/>


==Source Code==
* Since you are cloning your new empty git repository, you will just see the '''sources''' file in your cloned package directory.


The full source code for this example is available on [http://github.com/caniszczyk/mylyn-wikitext-examples GitHub].
== Updating the SCM ==
=== Importing and Committing the Package Contents ===
After you have checked out your empty git module, you need to import and commit your package contents into the master branch.
: 1. Right-click on your source files in SOURCES folder on your local RPM project in Eclipse and click '''Copy'''.
: 2. Right-click on your cloned project from Fedora Git and click '''Paste'''.
: 3. To upload these files, right-click on them, select '''Fedora Packager''' > '''Upload this File''' > '''Add to Existing Sources'''. This either adds the files to the list of source files required to build the package or replaces the current content of the '''sources''' file to contain a single line with the MD5 sum of the file selected.
: 4. Repeat steps 1-2 for your .spec file in SPECS folder.
: 5. To commit the package contents to the git repository, select the '''source''' file and the '''.spec''' file to commit (alternatively select the Fedora Git project and select desired ''unstaged'' files when the commit dialog is shown), right-click, '''Team''' > '''Commit...'''
* Use this message for your initial commit: "<code> Initial import (#nnnnnn)</code>" (where nnnnnn is your Bugzilla package review bug number).


=Other Approaches=
=== Closing the Bugzilla Ticket ===
* If the package built successfully, you should close it as '''NEXTRELEASE'''.


There are two main approaches when it comes to crowdsourcing documentation: '''wiki-based''' and '''file-based'''.
=== Enabling Upstream Release Monitoring ===
Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging.
* Refer to [https://docs.fedoraproject.org/en-US/package-maintainers/Upstream_Release_Monitoring/ Upstream Release Monitoring] for more details.
* Learn to handle updates by reading the [https://docs.fedoraproject.org/en-US/package-maintainers/Package_Update_Guide/ Package update HOWTO].


In this example, we focus on the wiki-based approach as it's the most collaborative approach. Anyone can contribute to documentation easily and the changes are instantly available online for people to see. The downside to this approach is that contributions are a bit less controlled which could impact quality depending on how a project structures its documentation process and depending on the wiki you choose, version history may be a bit harder to manage.  
=== Updating Your Package ===
Once you have pushed your package into the git repository, you can follow the instructions on [[User:Mziaei1/eclipse/toc#Using_Eclipse_Fedorapackager | Using Eclipse Fedorapackager]] to work with all available features of this plug-in.


In the file-based approach, the origin of the content is only in the SCM and is transformed during build-time. The plus side to this is it's managed by your existing version control system. The two major downsides are that changes aren't immediately available to your users and that it's much harder to contribute to the documentation since you need to have commit access. There are merits to both approaches and it really depends on your needs. Thankfully, examples for both approaches can be found in the [[#Eclipse.org Reference Projects]] section.
= Using Eclipse Fedorapackager =
Since Fedora 14, the Git version control system for keeping track of files required for Fedora packaging is used. See the [[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.


=Tips and Tricks=


You can use <pageAppendum> to add some extra information to your documentation.  
== Importing a Fedora Git Project ==
Getting started is easy:
: 1. Select '''Import''' > '''Git''' > '''Projects from Fedora Git''' and click '''Next'''.
: 2. type the name of the package in '''Package name'''.
:: You can find screenshots of these steps in [[Eclipse_How_to_Maintain_Fedora_Package_User_Guide#Checking_Out_the_Empty_Module_from_SCM| Checking Out the Empty Module]] in this user guide.
: 3. Once the new project has been created something akin to the following is seen.
: 4. 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.<br/><br/>


It's common to add a blurb about how to update the documentation so users can be informed that the documentation they are reading has been generating from the wiki.
[[Image:GitProjectBranchesView.png|Git Branch View]]


=Eclipse.org Reference Projects=
== 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, once 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'''.


If you're looking for other examples on how to crowdsource your documentation at Eclipse, the best place is to look and see what other Eclipse.org projects are doing.
=== 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 your file, '''Fedora Packager''' > '''Upload This File''' > '''Replace/Add Existing Sources'''. 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 in a terminal:
<pre>
$ fedora-cert -n
</pre>


==Mylyn==
=== 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 and select '''Fedora Packager''' > '''Download Sources'''. This downloads all sources listed in the file <code>sources</code>.


The Mylyn project uses two wiki pages on Eclipsepedia for its documentation: [[Mylyn/User Guide]] and [[Mylyn/FAQ]].
=== Using the Specfile Editor ===
Eclipse Fedora Packager uses the RPM Specfile Editor and changeLog plug-in from the [http://www.eclipse.org/linuxtools Eclipse Linux Tools project].<br/>
For instance, a new ChangeLog Entry can easily be created in the .spec file by using the <code>Ctrl+Alt+c</code> keyboard shortcut or by clicking '''Edit''' > '''ChangeLog Entry''' (though a good idea is to set appropriate [http://wiki.eclipse.org/Linux_Tools_Project/ChangeLog/User_Guide#ChangeLog_Preferences '''ChangeLog Preferences'''] first). Also, rpmlint can be run by right-clicking on the .spec file and selecting '''Run Rpmlint'''. <br/>
For more information have a look at the [http://www.eclipse.org/downloads/download.php?file=/technology/linuxtools/videos/specfile-demo.ogg .spec file editor screen-cast],  or at the "Specfile Editor User Guide": '''Help''' > '''Help Contents''' > '''Specfile Editor User Guide'''.


Each of these have their own Help table of contents, which are arranged into a common document via a top-level table of contents with links.
=== Committing Changes on the Local Git Working Directory ===
After the .spec file, patches, etc. have been added/changed, commit those changes to the repository. This is done by:


You can browse the source code [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/?root=Mylyn_Project here]. Pay attention to [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/build-helper.xml?root=Mylyn_Project&view=markup build-helper.xml], which drives the generation tasks, and [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.mylyn/org.eclipse.mylyn.help.ui/toc.xml?root=Mylyn_Project&view=markup toc.xml], which links the generated table of contents into a single document.
# 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...'''<br/><br/>


==EGit==
[[Image:GitCommit.png|Git Commit]]


The EGit project uses a single wiki page on Eclipsepedia for its [http://wiki.eclipse.org/EGit/User_Guide documentation].
=== 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.


Check out the '''org.eclipse.egit.doc''' plug-in.
=== Building the Package ===
==== Preparing Sources for Build ====
Eclipse Fedora Packager will download and prepare sources for building a package.
* Select your .spec file, right-click, '''Fedora Packager''' > '''Prepare Sources for Build'''.
[[Image:PrepareSourcesForBuild.png|Prepare Sources for Build]]


==Xtext==
==== Building 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 environment using mock. Both ways are supported by Eclipse Fedora Packager.
* To build the RPM locally right-click on the .spec file and select '''Fedora Packager''' > '''Build for Local Architecture'''. Output of the RPM build process will appear in the Eclipse Console view.


The Xtext project uses a Textile and Wikitext for its documentation. The code is available in the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tmf/org.eclipse.xtext/plugins/org.eclipse.xtext.doc/?root=Modeling_Project org.eclipse.xtext.doc] plug-in. The documentation is sourced from various Textile files stored in source control and then transformed at build-time. This is different from the previous two examples which used the wiki as the source of documentation.
Using mock to build your package is a great way to verify that you have the correct <code>BuildRequires</code> in a .spec file.  
* To build the RPM locally using mock, right-click on the .spec file and select '''Fedora Packager''' > '''Local Build Using Mock'''. Be aware that this may take a long time and requires the mock package to be installed. Use Eclipse's ''Run in Background'' functionality for convenience.


Pay attention to the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tmf/org.eclipse.xtext/plugins/org.eclipse.xtext.doc/customBuild.xml?root=Modeling_Project&view=markup customBuild.xml] and the [http://dev.eclipse.org/viewcvs/index.cgi/org.eclipse.tmf/org.eclipse.xtext/plugins/org.eclipse.xtext.doc/doc/?root=Modeling_Project doc] folder.
=== Make Locally Committed Changes Public (Git Push) ===
When you are satisfied with your locally-committed changes, you are ready to publish them publicly. Remember, if you made any mistake in your commits, 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.<br/>
To bring the local repository in sync with the remote repository (which is by default called [http://wiki.eclipse.org/EGit/User_Guide#Local_Destination origin]):
: 1. Right-click on the Fedora Git project, click '''Team''' > '''Remote''' > '''Push...'''
: 2. Select the Git repository to which you would like to push (usually this is kept unchanged), click '''Next'''.<br/><br/>


==OSEE==
[[Image:GitPushDialog.png|Git Push Dialog]]<br/><br/>


For modularity reasons, the OSEE project has multiple help projects which generate Eclipse online help from different parts of the [[OSEE#Documentation|OSEE wiki]]. The central help plugin is [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.framework.help.ui/ org.eclipse.osee.framework.help.ui], which contains a [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.framework.help.ui/build-helper.xml build-helper.xml] file that calls <tt>mediawiki-to-eclipse-help</tt> and specifies the different help chapters:
: 5. 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 way that pushes all commits to all local branches.<br/><br/>


<source lang="xml">
[[Image:SelectGitReferencesToPush.png|Select Git References]]<br/><br/>
<mediawiki-to-eclipse-help wikiBaseUrl="${osee.help.doc.url.base}"
validate="true" failonvalidationerror="true" prependImagePrefix="images"
formatoutput="true" defaultAbsoluteLinkTarget="osee_external" dest="${basedir}"
navigationimages="true" title="OSEE User's Guide"
generateUnifiedToc="true">
<path name="OSEE/Users_Guide/Getting_Started" title="Introduction" />
<path name="OSEE/Users_Guide/Concepts" title="Concepts" />
<path name="OSEE/Users_Guide/Features" title="Features" />
<path name="OSEE/Users_Guide/Tips" title="Tips" />
<path name="OSEE/Users_Guide/New" title="New" />
<stylesheet url="book.css" />
<pageAppendum>
= Updating This Document =


This document is maintained in a collaborative wiki. If you wish to
: 4. Carry out the push operation
update or modify this document please visit {url}
</pageAppendum>
</mediawiki-to-eclipse-help>
</source>


Classpath/taskdef setup is performed in [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.framework.help.ui/scripts/help-build-common.xml help-build-common.xml]. Another example of an OSEE help plugin is [https://dev.eclipse.org/svnroot/technology/org.eclipse.osee/trunk/plugins/org.eclipse.osee.ats.help.ui/ org.eclipse.osee.ats.help.ui], which uses the libraries and taskdefs from org.eclipse.osee.framework.help.ui.
=== Pushing a Build to Koji ===
* To push a build to Koji, right-click on the .spec file, select '''Fedora Packager''' > '''Push to Koji'''.<br/><br/>


== PsychoPath XPath 2.0 Processor ==
[[Image:EclipseFedoraPackagerPushBuildToKoji.png]]<br/><br/>


The [[PsychoPathXPathProcessor/UserManual | PsychoPath Processor documentation]] is maintained on the eclipse wiki.  The documentation is then generated into DocBook format using Mylyn WikiText.   The documentation is then cleaned up as some of the conversions do not necessarily fit our specific needs.  The Docbook Project's XSL stylesheets are then used to generate the help into a variety of formats including eclipse help.
* Eclipse will pop up a message with the Koji URL to track your build. This is an example of how the message may look:<br/><br/>


* See [[Authoring_Eclipse_Help_Using_DocBook]] for more information on using Docbook to generate the final output produced by WikiText.
[[Image:KojiBuildPopupMessage.png|Koji Popup Dialog]]<br/><br/>


== XSL Tools ==
* If you click on the provided URL, a browser tab will open in Eclipse showing you the contents of the koji status page. Refresh it as you like to follow build progress.


Like the Psychopath Processor, the webtools [[XSLT_Project | XSL Tools documentation]] is also available on the wiki and generated back into DocBook format using Mylyn WikiText.
=== Pushing a Bodhi Update ===
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:
* Switch to the appropriate git branch on '''Git Repositories view'''.
* Commit all your changes for this branch.
* Right-click on your project, '''Fedora Packager''' > '''Create New 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 in the Bodhi updates website. The status of updates can also be tracked there.


* See [[Authoring_Eclipse_Help_Using_DocBook]] for more information on using Docbook to generate the final output produced by WikiText.
= 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 (an 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] in Red Hat bugzilla in order to find already existing bugs. Thanks!

Latest revision as of 19:34, 2 October 2021

What is Eclipse Fedora Packager?

Eclipse Fedora Packager is a plug-in for Eclipse that has been available for Fedora users since F14. 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 :-) ).

Some features included in the Eclipse Fedora Packager are:

  • Conveniently clone Fedora Git projects
  • RPM .spec file editor with syntax highlighting, auto-completion of package names for Requires/BuildRequires templates, %changelog support (Ctrl+Alt+c keyboard shortcut), etc.
  • Download source files and upload new source files
  • Prepare local builds (execute %prep section of your .spec file only)
  • Create source RPMs based on current .spec file
  • Perform local builds
  • Push builds to Koji (the Fedora build system)
  • Mock builds
  • Push Bodhi updates
  • Eclipse Git support (via EGit, please refer to EGit documentation)


Feel free to skip the next section if you already know how to package new software for Fedora.

Getting Started as Maintainer for a New Fedora Package

If you haven't previously packaged software for Fedora, this guide will lead you through your first package submission.
Wiki changes the image file names that start with lowercase to uppercase.
eg. this image with name lowercase.png will convert the image file name
to Lowercase.png, but the html file will stay as it is now.

lowercase image









fedora submit package

Creating Account for New Contributors

If you are a new package maintainer:

Creating a new account in Fedora Account System

  • First step is to create account in Fedora Account System (FAS).
  • Click 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.

Creating a Bugzilla Account

Create an account in Red Hat bugzilla.

  • The email address that you use for your bugzilla account should be the same email address as you use in the Fedora Account System for all things related to fedora packaging.
  • To make you work and your bug tracking easier, there is a task management plug-in for eclipse called Mylyn. You can follow these instructions on how to integrate your bugizlla account with your mylyn plug-in in eclipse.

Initial Setup

This step is only required to be completed once for a new Fedora packager or if using a new machine that does not have the 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 an FAS account.
First, install the fedora-packager RPM package: 

   yum install fedora-packager

Then run the following command and follow the instructions provided: 

   fedora-packager-setup

Making a Package

Packaging Guidlines

Creating an RPM package:

Perform the following steps to create an RPM package:

  1. Select File > New > Other... from the main menu. Choose RPM > RPM Project, click Next.
  2. Type the Project name. Click Finish.
  3. Right click on SPECS, select New > Other..., choose RPM > Specfile Based on a Template, click Next.
  4. Fill out the template or accept the default values and customize it based your package specifications. You may use specific templates (e.g. for Perl or Java packages) to create a .spec file stub.
  5. When your package is ready to submit for review, select File > Export from the main munu, choose RPM > Source/Binary RPM, click Next.
  6. Based on your requirements, select one or both options, click Finish.
  • For more information have a look at the "Specfile Editor User Guide": Help > Help Contents > Specfile Editor User Guide.

Submiting For Review

Joining the Possible Fedora 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.

Uploading the 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.

Example: 

 scp path/to/file.spec path/to/rpm-file.src.rpm <user-name>.fedorapeople.org:public_html

file.spec and rpm-file.src.rpm will then be available via the following URLs: 

http://<user-name>.fedorapeople.org/file.spec
http://<user-name>.fedorapeople.org/rpm-file.src.rpm

Creating Review Request

Before submitting your request, be sure there is not a previous request for the same package.

  • Fill out this form at bugzilla.
  • 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.

Bugzilla 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.

Obtaining Member Sponsorship

After your package is approved by reviewers, you must separately obtain member sponsorship 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.

Requesting a new package SCM

When the package is approved by the reviewer, request a git module and branches with the Source Code Management(SCM) admin requests.

  • Mention the name of the branches you need your package to be included in.

Checking Out the Empty Module from SCM

Once you have the git module, clone your module from git.

  • Go to File > Import > Git > Projects from Fedora Git and enter your package name when prompted. This will clone the desired Git repository. Refer to this user guide on Using Fedora Git for more information.
  • For convenience, the Git Repositories view will also open once the clone process has finished.

Fedora Git Import

  • Here's what the Fedora Git import dialog looks like. Next, specify the package name that will then be prepared for you.

Select Package Name

  • Since you are cloning your new empty git repository, you will just see the sources file in your cloned package directory.

Updating the SCM

Importing and Committing the Package Contents

After you have checked out your empty git module, you need to import and commit your package contents into the master branch.

1. Right-click on your source files in SOURCES folder on your local RPM project in Eclipse and click Copy.
2. Right-click on your cloned project from Fedora Git and click Paste.
3. To upload these files, right-click on them, select Fedora Packager > Upload this File > Add to Existing Sources. This either adds the files to the list of source files required to build the package or replaces the current content of the sources file to contain a single line with the MD5 sum of the file selected.
4. Repeat steps 1-2 for your .spec file in SPECS folder.
5. To commit the package contents to the git repository, select the source file and the .spec file to commit (alternatively select the Fedora Git project and select desired unstaged files when the commit dialog is shown), right-click, Team > Commit...
  • Use this message for your initial commit: " Initial import (#nnnnnn)" (where nnnnnn is your Bugzilla package review bug number).

Closing the Bugzilla Ticket

  • If the package built successfully, you should close it as NEXTRELEASE.

Enabling Upstream Release Monitoring

Fedora has infrastructure available for monitoring new upstream releases of the software you are packaging.

Updating Your Package

Once you have pushed your package into the git repository, you can follow the instructions on Using Eclipse Fedorapackager to work with all available features of this plug-in.

Using Eclipse Fedorapackager

Since Fedora 14, the Git version control system for keeping track of files required for Fedora packaging is used. See the 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.


Importing a Fedora Git Project

Getting started is easy:

1. Select Import > Git > Projects from Fedora Git and click Next.
2. type the name of the package in Package name.
You can find screenshots of these steps in Checking Out the Empty Module in this user guide.
3. Once the new project has been created something akin to the following is seen.
4. 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.

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, once 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 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 your file, Fedora Packager > Upload This File > Replace/Add Existing Sources. This either adds the file to the sources required to build the package or replaces the current content of the sources 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 in a terminal:
$ fedora-cert -n

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 and select Fedora Packager > Download Sources. This downloads all sources listed in the file sources.

Using the Specfile Editor

Eclipse Fedora Packager uses the RPM Specfile Editor and changeLog plug-in from the Eclipse Linux Tools project.
For instance, a new ChangeLog Entry can easily be created in the .spec file by using the Ctrl+Alt+c keyboard shortcut or by clicking Edit > ChangeLog Entry (though a good idea is to set appropriate ChangeLog Preferences first). Also, rpmlint can be run by right-clicking on the .spec file and selecting Run Rpmlint.
For more information have a look at the .spec file editor screen-cast, or at the "Specfile Editor User Guide": Help > Help Contents > Specfile Editor User Guide.

Committing Changes on the Local Git Working Directory

After the .spec file, patches, etc. have been added/changed, commit those changes to the repository. This is done by:

  1. Selecting the files to commit (alternatively select the Fedora Git project and select desired unstaged files when the commit dialog is shown)
  2. Right-click, Team > Commit...

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 Git and EGit documentation for more information on this.

Building the Package

Preparing Sources for Build

Eclipse Fedora Packager will download and prepare sources for building a package.

  • Select your .spec file, right-click, Fedora Packager > Prepare Sources for Build.

Prepare Sources for Build

Building 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 environment using mock. Both ways are supported by Eclipse Fedora Packager.

  • To build the RPM locally right-click on the .spec file and select Fedora Packager > Build for Local Architecture. Output of the RPM build process will appear in the Eclipse Console view.

Using mock to build your package is a great way to verify that you have the correct BuildRequires in a .spec file.

  • To build the RPM locally using mock, right-click on the .spec file and select Fedora Packager > Local Build Using Mock. Be aware that this may take a long time and requires the mock package to be installed. Use Eclipse's Run in Background functionality for convenience.

Make Locally Committed Changes Public (Git Push)

When you are satisfied with your locally-committed changes, you are ready to publish them publicly. Remember, if you made any mistake in your commits, Git allows history to be rewritten before changes are made public. See the Git and EGit documentation for more information.
To bring the local repository in sync with the remote repository (which is by default called origin):

1. Right-click on the Fedora Git project, click Team > Remote > Push...
2. Select the Git repository to which you would like to push (usually this is kept unchanged), click Next.

Git Push Dialog

5. 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 way that pushes all commits to all local branches.

Select Git References

4. Carry out the push operation

Pushing a Build to Koji

  • To push a build to Koji, right-click on the .spec file, select Fedora Packager > Push to Koji.

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:

Koji Popup Dialog

  • If you click on the provided URL, a browser tab will open in Eclipse showing you the contents of the koji status page. Refresh it as you like to follow build progress.

Pushing a Bodhi Update

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:

  • Switch to the appropriate git branch on Git Repositories view.
  • Commit all your changes for this branch.
  • Right-click on your project, Fedora Packager > Create New 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 in the Bodhi updates website. The status of updates can also be tracked there.

Feedback/Reporting Bugs

Retrieved from "https://fedoraproject.org/w/index.php?title=Eclipse_How_to_Maintain_Fedora_Package_User_Guide&oldid=626551"