User Tools

Site Tools


developingpld

How to become a PLD developer

This article will attempt to explain the basics of a Linux-based distribution development process.

Required knowledge

As PLD Linux is an RPM-based distribution, the following knowledge is assumed:

  • Basic rpm operation
  • Use of versioning tools such as git
  • Handling file differencies using diff and patch
  • Building applications from their sources

Inside PLD

Unlike other big distributions, there is no commercial support behind PLD Linux. The developer community consists of people who either need to get their work done or simply enjoy contributing to an open project (or both).

Internally, PLD is split into distribution lines. Currently there are three of them:

Each line has a person in charge of it, called the Release Manager. RMs spend time maintaining parts of PLD's infrastructure, making decisions if other developers can't agree on something by themselves and taking care of the content of our FTP server.

Other than that, most developers spend their time maintaining packages which usually means working on spec files (explained later). There is no enforced responsibility and everyone is free to work on any package they want. The only rule is to only touch things when you are sure you know what you are doing. In other words, people don't randomly pick a package and update it, but rather work only on the stuff they have a need for. It might sound a bit chaotic, but this model is quite stable, since every change is almost immediately reviewed. Not to mention that developers like this kind of organization very much, since they don't need anyone's permission to introduce changes they need.

Getting more technical

Spec files

A spec file contains metadata and building instruction required to create at least one RPM package. It is a text file suitable for processing with the builder script which in turn handles the whole building process from fetching all the necessary sources from PLD's infrastructure (or directly from the Internet) to packaging the results into installable RPM files (the latter being done by the rpmbuild utility).

You can also read more on spec files.

All the spec files reside inside their respective package dir of our GIT server. rpm-build-tools package, containing builder script, also contains some special files, the most crucial being the builder script.

The builder script

The builder script is responsible for the whole package assembly process. It fetches all the needed sources, checks for required dependencies, unpacks the sources, compiles them and finally packages the result into installable RPM files.

You can also read more on builder script.

The script can be run by any user inside a special directory structure under that user's home directory and heavily depends on the rpmbuild binary provided by the rpm-build package.

The same script is used by machines forming the PLD building farm to build packages that can be found on our FTP server.

The adapter script

The adapter script is a tool to aid you in the process of writing clean spec files. It can automatically perform a number of cleaning tasks and take care of some common mistakes found in spec files.

PLD is very strict when it comes to spec files so you are advised to adapterize each and every file before either sending it to the developer list or commiting it into the repository.

You can also read more on adapter script.

PLD building farm

The building farm is a cluster of machines used to build RPM files from their spec equivalents. Each machine has a specific purpose. Some build packages for specific architectures, while others create src.rpm packages containing everything required to build a given package. There are also machines that serve as testing environments for developers to do package building and debugging.

You can also read more on PLD machines.

Each distribution line has it's own set of builders and it's own building queue maintained by a group of trusted developers.

Rules for sending requests to PLD 3.0 (Th) builders.

Rules for sending requests to PLD 2.0 (Ac) builders.

Becoming involved

Mailing lists

You should start right off by subscribing to at least some of our mailing lists. Especially the pld-devel-en (or pl for Polish speaking developers) list and possibly also pld-discuss for various distribution-related discussions.

Take note that there is a special pld-cvs-commit list but it's not meant for direct posting. Instead, this list collects GIT, SVN or CVS commits and website changes commited by PLD Linux developers.

Preparing your working environment

Working on packages

Start with simple things. Picking random package and updating it might seem like a good idea, but it'll eventually get you in trouble. Breaking an app someone depends on won't hurt the distribution itself that much, but people will get angry at you and making future changes will get a lot harder. Try adding a spec file for that little application you use for your everyday work or update an existing spec for a new release of some useful tool you just can't live without.

Before you decide you are done, double-check your dependencies section for all necessary packages and make sure the package builds cleanly (for instance, no files are left after packaging RPM files - builder warns about that at the end of building process).

If you're bored and don't know what to do, you can try fulfilling requests from PLD-doc/PLD-specs-TODO(or this same list but with additional entries on wiki http://pld-users.org/specs-todo), or autogenerated TODO headers from *.spec: PLD-doc/specs-auto-todo.txt

Publishing your changes

As a wannabe developer you most likely won't have read/write access to the GIT repository so you'll have to find someone to check your changes in and add them to the repository. The best way to do it is to send a unified diff of your changes against the original files (or the whole files in case you are adding any) in a mail message along with a brief description of what you did to the pld-devel-en (or pl) mailing list.

It's also acceptable to make your changes in your git repository, perhaps published in github and let somebody to pull your changes to pld repository.

Once existing developer, who has time to review your changes, you will be notified of any errors that need to be fixed and eventually your files will get committed or pushed.

Once you provide enough valuable changes, other developers might decide to give you full access to our repositories. This process is always initiated by someone who already has read/write access, asking for access on your own will not do you any good.

When that happens, you will be able to do GIT commits and push them to PLD servers yourself. Remember to check the files you are committing before sending them to the repository. Make sure you also provide a meaningful commitlog. All logs have to be in the following format:

- first change 
- second change
- third change
- some additional info

Even if there is only one message in your commitlog, prefixing it with a dash will make reading it a lot easier.

Package's life cycle

After a spec file gets commited, the package needs to be built. The life cycle is as follows:

  1. spec file is commited (including changes to needed patches and other files referenced in the spec)
  2. One of the developers requests a test build (this is done using the make-request.sh script). If you don't have the rights contact your RM for access. It is possible to skip this step and ask for an upgrade directly however it is not recommended as a partial upgrade results in desynchronising packages between build servers. If found guilty, you will be executed on the spot.
  3. The package is successfully built on all architectures.
  4. One of the priviledged developers requests an upgrade build (same script as above) - contact your RM for access.
  5. The package is once again built on all architectures and upgraded across the whole builder farm.
  6. The package is moved to the queue tree (ready for Ac and test for Th).
  7. Your RM takes further care of the package. He decides when the package is ready to be moved to the stable tree (or the updates tree in case of an already released version). If you believe it takes too long, check if all the dependencies (both introduced or broken by the particular package) have been satisfied in the queue tree.
  8. The package is finally moved to the stable or updates tree and anyone can use it.
  9. The package is placed to obolete source if new version available.

Resolving common problems

developingpld.txt · Last modified: 2014-05-13 18:34 by glen

Except where otherwise noted, content on this wiki is licensed under the following license: Public Domain
Public Domain Donate Powered by PHP Valid HTML5 Valid CSS PLD Linux Driven by DokuWiki