From Mageia wiki
Revision as of 21:18, 11 August 2020 by Luigiwalser (talk | contribs) (Work suggestions for apprentices: add shared bug list for issues with available patches)
Jump to: navigation, search


Drakconf multiflag.png
Other languages
English ; Français

This page supposes that you have followed completely the page Becoming a Mageia Packager. You have in particular followed the tutorials Packaging for beginners and Packagers RPM tutorial.

You are an apprentice and have a mentor.

In the rest of this page, we will describe the main work-flow that you should follow in order to contribute to Mageia as an apprentice.

Apprentice Work-flow

Preparations

From the tutorial that you have followed, your setup should already have the following packages and their correct configuration:

  • rpm: our patched version of Red Hat's.
  • rpm-build: holds scripts used to build packages.
  • spec-helper: a tool to minimize the specfiles by doing automatic things such as stripping the binaries and compressing the man pages.
  • libtool: used by some configure scripts to build shared libraries.
  • rpmlint: used to check the validity of the generated src.rpm.

Additionally, you should install:

  • rpmlint-mageia-policy: specific Mageia policies for rpmlint.
  • mgarepo: for the interaction with the Mageia svn and build system.
  • bm: to build and rebuild packages.
  • nopaste: to easily send patches to your mentor.

To ease the creation of a brand new spec file, install

  • rpmdevtools: This includes the command "rpmdev-newspec"

For Mageia Cauldron, you can install the meta package for packagers.

  • task-packager: This package will install the necessary tools you need to start

This software will make your life as an apprentice easier.

Setting up mgarepo

mgarepo is the main way packagers interact with the Mageia distribution. As an apprentice without commit rights, you need to set it up to use anonymous checkout. To do so, you need to edit the config file manually:

  • Create an initial configuration file:
mkdir ~/.mgarepo; cp /etc/mgarepo.conf ~/.mgarepo/config
  • Edit ~/.mgarepo/config and change:
repository = svn+ssh://svn.mageia.org/svn/packages/

to

repository = svn://svn.mageia.org/svn/packages/

You are now all set up to start working on packages. The two main tasks you might have to perform are:

  1. Updating an existing Mageia package
  2. Importing a new package in Mageia

In the next paragraphs, it is assumed that:

  • you are working on Cauldron packages;
  • you are in contact with your mentor to get help if any question arises;
  • you keep close to you all the documentation you need, especially this page and the tutorial.

Updating a package

You wish (or you've been asked by your mentor) to update a current Mageia Cauldron package. This can be to fix a bug or a weakness, or to update it to a more recent version.

A.1. Checkout the package
mgarepo co foo
  • it should create a directory with subdirectories SOURCES and SPECS. Go into that directory:
cd foo
A.2. Update the spec
  • This is done using your favorite text editor. For example:
emacs SPECS/foo.spec
  • Try to keep your changes to a minimum. This eases the job of your mentor by reducing the amount he has to review.
  • Look at how other packages spec are written for inspiration. Sophie [1] can help.
  • Any change to an existing package must include an update to the %mkrel parameter. If you are changing a package (but no new version), just increase by one that parameter as part of your changes. For example:
%define release %mkrel 2
  • If you are working on providing a new version, put %mkrel back to 1.


A.3. For a new version
  • In the spec file, update the version field and the Source link. For example:
%define version 1.2.3
Source0: http://www.program.org/download/foo-%{version}.tar.gz
  • You need to download the new source in the SOURCES subdirectory. It is advised to do it with wget and to use the Source field you just updated in the spec file. For example:
cd SOURCES; wget http://www.program.org/download/foo-1.2.3.tar.gz; cd ..
A.4. Rebuild
  • Once you have done some modifications to your package, you should build it. This can be done by the command
bm -l
  • This command actually builds at the same time the src.rpm and an architecture specific rpm. It creates and populates the subdirectories BUILD, BUILROOT, RPMS, SRPMS.
  • If you only want the src.rpm, use:
bm -ls
  • There are now two possibilities, either it succeeds and you go to step A.5, or it fails and you should look at the error message and most of the time go back to A.2.
    • Some errors will be obvious for you to solve: missing installed packages, typos.
    • Some errors will require some more involved work, such as re-diffing patches. In that case, ask your mentor.
A.5. Check the src.rpm
  • rpmlint is a tool that helps maintain some quality control over RPMs. Always run rpmlint on the src.rpm you have produced. For example:
rpmlint SRPMS/foo-1.2.3-1.src.rpm
  • rpmlint will give you errors and warnings. Try to reduce their numbers as much as possible.
    • Some warning are unavoidable at this stage, such as "no signature" or "no-changelogname-tag".
    • Some warnings (for example on mixing spaces and tabs) are simple to fix. In doubt, ask your mentor.
  • rpmlint can also be run on the spec directly. The verifications are less thorough but it can be useful as a first
A.6 Test the installation
  • Install the rpm package you just created. For example (as root):
urpmi RPMS/x86_64/foo-1.2.3-2.mga2.x86_64.rpm
  • Check that it works:
    • Does it appear in the menu? Does it launch correctly from the command line? Does it perform the usual tasks it is supposed to do?
  • Check the uninstallation. For example (still as root):
urpme foo-1.2.3-2.mga2.x86_64.rpm
    • Did it uninstall without any problem?
A.7 Check and send the patch
  • Once you are confident about the package you just produced, have a look at your changes by doing (in the package directory):
svn diff
  • This allows you to verify if your changes are all intentional and that the many iterations through A.2-5 did not enrich the spec by lots of garbage. Try to make that diff as small as possible (by going back to step A.2).
  • Once you are happy with both the package and the diff, you can send it to your mentor. A very useful tool is nopaste. For example:
svn diff > foo.spec.patch
nopaste foo.spec.patch
nopaste produces an URL that you can give to your mentor by email or IRC. They will then review it, apply it on their machine, ask you to correct any mistakes you made, then commit it to the Mageia svn.
A.8 Enjoy the build system
  • Once your mentor has accepted the patch, you can follow the build of the package on the build system. Go to [[2]].
    • If it appears green: victory! After a few minutes, the new version of your package will appear on the mirrors and be used by all Mageia users.
    • If it's red: don't worry you did not break anything. Look at the error messages and try to fix the problem with your mentor.

Importing a package

You wish (or you've been asked by your mentor) to import a new package into Mageia Cauldron. Please follow these steps:

B.0 Preliminary
  • To import a new package, you need to create a new src.rpm that you have to send to your mentor.
  • To that purpose, you should work in the rpm directory you created in the tutorial.
    • Reminder (to create these directories):
  mkdir -p ~/rpm/{BUILD,BUILDROOT,RPMS/{$ARCH,noarch},SOURCES,SRPMS,SPECS,tmp}
where $ARCH is the architecture(s): i586 / x86_64
    • You can start by removing all the previous work that was in the subdirectories of rpm.
B.1 There exists a src.rpm from another distribution
  • This situation is easier to handle as you should have been familiarized by the different steps of the tutorial.
  • Unpack the src.rpm
rpm -Uvh path/to/the/file/foo-1.2.3-1.mdvsrc.rpm
Go to B.3.
B.2 The package does not exist in any other rpm-based distribution
  • Are you really sure? It can be under a different name ...
  • Go to the rpm directory and put the source file into the SOURCES subdirectory.
cd SOURCES; wget http://www.program.org/download/foo-1.2.3.tar.gz; cd ..
  • Create a spec file:
emacs SPECS/foo.spec
  • Creating a spec file from scratch is not easy, so take inspiration from spec files of similar packages.
  • You can alternatively use the command "rpmdev-newspec foo.spec" to get a basic building block for your new package.
B.3 Follow the steps as in an update
  • Follow the steps A.2 to A.6 of the previous section.
B.4 Send the src.rpm to your mentor.
  • Once you are happy with the result, you should send the src.rpm you have produced to your mentor.
  • Try to use an online repository (like a personal page) instead of sending it by email.
  • Once your mentor receives it, they will have a look give you feedback and possibly will ask you to go back to iterating step B.2.
    • When your mentor is happy, they will import the package into Mageia and you will be able to access the svn version by:
mgarepo co foo

Apprentice Conclusion

The steps A.1 to A.8 and B.1 to B.3, should be followed throughout your training. Experienced packagers use them as well!

When your mentor decides that you should have commit rights, go to the next section.

The procedures will essentially stay the same; only the steps A.7 and B.3 will differ substantially.

Apprentice+ Work-flow

You are now an apprentice+, well done! Before you get any further, you need to adapt your setup to the new situation.

Getting your account upgraded for commit rights

When your mentor thinks you should get commit rights, he opens a bug request on bugzilla, against the Infrastructure -> Account request component. The bug should mention :

  • the apprentice login on identity
  • that it is a packager apprentice account (as there are other types of accounts that can be requested)

Preparations

ssh
  • Once your account has been upgraded, you should be able to upload your ssh key to identity, by follow the instructions at Packagers ssh. Once it's done, you should be able to access the svn using your account.
mgarepo
  • To use mgarepo with your identity, you need to change back the mgarepo's configuration file. Change:
repository = svn://svn.mageia.org/svn/packages/
binaries-repository = svn://svn.mageia.org/svn/binrepos
to
repository = svn+ssh://svn.mageia.org/svn/packages/
binaries-repository = svn+ssh://svn.mageia.org/svn/binrepos

Note that any svn checkout you did previously (with an anonymous identity) will not allow you to commit (as the anonymous login is remembered by svn). You need to redo fresh checkouts.

Updating a package

You should basically follow the same steps as before: A.1 to A.6

A.3' For a new version
  • The procedure changes here from previously: once you have set up the new version field and updated the Source0 URL, you can just add the new source to the repository using mgarepo. No need for wget anymore. Just do:
mgarepo sync -d
and the new source file will be downloaded from the URL and checked in the svn.
A.7' Check and commit the patch
  • As previously, once you are confident about the package you just produced, have a look at your changes by doing (in the package directory):
svn diff
  • Follow the same careful approach described in A.7.
  • Once you are happy with both the package and the diff, you can commit it:
mgarepo ci -m 'my commit message'
  • Commit messages are important as they are the way to convey to other pacakgers what changes you just made.
  • If you made just one change (for example, update to new version 1.2.3), one line commit message is enough:
mgarepo ci -m 'update to new version 1.2.3'
  • If you made several unrelated changes, write them in several lines preceded with a dash. The command:
mgarepo ci

will open an editor (the one specified by your EDITOR environment variable). There you can write the commit message you want. For example:

- update to new version 1.2.3
- added BuildRequires to python-devel
- clean spec
- fix issue of missing icon
  • Do not hesitate to ask your mentor and look at previous commit messages for inspiration:
mgarepo log foo
gives the history of commit messages for package foo.
A.8' Submitting
  • After committing, contact your mentor for him to review your changes and submit the package.


Importing a package

You should basically follow the same steps as before: B.0 to B.3. Then, instead of B.4, use B.5'.

B.5' Importing a package
  • Importing a package can be done once an src.rpm has been produced. Then use:
mgarepo import foo-1.2.3-1.src.rpm
  • Once imported, you can ask your mentor to review and submit the package.


Graduating

When your mentor feels that you are ready, he can decide to promote you to packager. The restrictions to your access to the build system will be lifted. The procedures you will have to follow will however stay the same, except that you will be able to submit the packages yourself.

Note that being an apprentice is not just about learning how to use the different tools mentioned on this page. It also includes:

  • knowing about package dependencies and the maintenance of libraries
  • knowing how to fix bugs
  • knowing about patch management

And even after you are being promoted as a packager,

much to learn you will still have ...

Some advice:

  • Look at the links suggested at the bottom of this page, notably mgarepo
  • Keep in touch with users, other packagers and your mentor
  • Take over the maintenance of packages
  • Have fun!

Work suggestions for apprentices

You mentor will not always suggest you some tasks: apprentices should take the initiative. Be careful however, some packages might be already taken care by other people, and some updates can break things. It is always wise to talk to your mentor about the changes you plan to make. He will direct you to the right person to ask, to the #mageia-dev IRC channel or to the mailing list.

Some suggestions in descending priority:

  1. before adding new packages to Mageia, first look to fix bugs for existing packages or help take maintainership for currently unmaintained packages.
    See the current list of unmaintained packages linked prominently at the top of our buildsystem overview page
  2. help the QA team validate bugfix and security updates, see Current Update candidates and QA process for validating updates
  3. Bugzilla is the main place to look when you want to contribute, but do not have a specific target.
    Look in particular for (but do not restrict yourself to) the Junior_Jobs for existing packages or Patches for existing packages (or the Junior_Jobs or PATCH keywords).
    See all saved-searches for more usefull bugzilla searches
  4. removing X-MandrivaLinux and X-Mageia categories from all .desktop files, as per https://bugs.mageia.org/show_bug.cgi?id=2449#c11 (also see some comments above)
  5. remove "This package is in PLF because..." from all packages where it is encountered or adapt the wording to say "This package is in tainted/nonfree because ..."
  6. http://check.mageia.org provides several quality analysis about the current distribution. If some dependencies are broken, some packages are missing or not up-to-date you can have a look.
  7. Take maintainership of a program you use particularly often and, depending on the situation, import it, update it and fix its bugs (example of query). Look notably at its upstream status and at its situation in other distributions.
  8. New package requests in Bugzilla

See also

All the pages in the Packager category on the wiki are relevant, notably:

A lot of external links are given at Packagers linkpage.

Return to the Packagers portal