Skip to content

Developper_Guidelines

Jump to bottom Edit New page
Olivier LAHAYE edited this page Dec 10, 2019 · 12 revisions

Developing SystemImager ®

Design Goals

The design goal for SystemImager was to create a tool that was both easy and fast to use, allowing system administrators to perform incremental upgrades that minimized system disruptions and provided software independent of any packaging system. The specific requirements follow:

  • Images should be pulled from a working system.
  • Unattended installs are a must.
  • The unattended install system has to be able to repartition the destination drive(s).
  • System administrators who don't completely understand the tool should be able to use it.
  • The install should be easy and quick so that it can be useful immediately without a lot of site-specific customization.
  • Images should be stored as normal files to allow for incremental upgrades, as opposed to "dd" style block level images of physical disks.
  • The SystemImager software should be independent of any and all packaging systems (such as RPM) in order to easily accommodate different distributions.
  • SystemImager should be able to store multiple images for different types of systems and for revision control.
  • A mechanism should be available to let unattended install clients know which image to install.
  • SystemImager should have a command line interface that can easily be wrapped with a GUI.

Development of SystemImager Architecture

Minimal system requirements were a top priority for SystemImager, which began as a series of utilities written as shell scripts. However, shell scripts were inadequate as SystemImager matured and its utilities became more complex. Perl, part of most Linux installs and possessing minimal system requirements, then replaced shell scripts. Using Perl, developers have been able to generate cleaner, more advanced code.

SystemImager architecture was designed to be open to modification at every level. The protocol for transferring files during installs and updates is currently rsync(1), but the modular code easily allows drop-in replacements as is appropriate. All unicast file transfer mechanisms, including rsync(1) are implemented in a "pull" fashion, which is generally considered to be superior to a "push," because it is much easier to monitor the state of the receiving system prior to and during the file transfers.

Versioning

SystemImager releases use an "A.B.C.D" numbering scheme similar to that used by the Linux kernel.

Synopsis

VERSION.MAJOR.MINOR[.EXTRAVERSION]

Official release

  • SystemImager official releases are denoted using a standard triplet of integers: VERSION.MAJOR.MINOR.
  • The basic intent is that a VERSION increment indicates a major architectural change, a MAJOR increment indicates major improvements and a MINOR increment indicates a bug fix release or a release with minor improvements.
  • An odd MAJOR number indicates an unstable release, an even number indicates a stable release.
  • An odd MINOR number indicates a pre-release or a release candidate (see below) of the VERSION.MAJOR.(MINOR + 1), an even number always indicates an official release (stable or unstable, depening on the MAJOR number).
  • A pre-release is always considered unstable, even if MAJOR is a even number.
  • Official releases are always distributed uploading the files and packages via the [http://sourceforge.net/project/showfiles.php?group_id=259](SourceForge file release system).

Development pre-release

  • Development pre-release or release candidate versions use an additional integer at the end of the version string: VERSION.MAJOR.MINOR.EXTRAVERSION. By definition the EXTRAVERSION number can be appended only if the MINOR number is odd (pre-release or releaes candidate).
  • The first 3 numbers (VERSION, MAJOR and MINOR) define the version of the next official release, that will be called: VERSION.MAJOR.(MINOR + 1).
  • EXTRAVERSION should always contain the string gitNUMBER, where NUMBER is a reference to the date (format YYYMMDD) of the last commit (checked into http://svn.systemimager.org). By default a pre-release is always based on the exact content of the SVN branch MAJOR.MINOR.x. Otherwise an additional comment, string, abbreviation, etc. must be appended, that can identify for example:
    • the name of the developer (i.e. .git20170625arighi),
    • an explicative name of a new feature present only in the local repository of a developer (i.e. git20200328bittorrent),
    • a name that identify the origin of the source repository (i.e. .git20180123master, .git20180921udevbranch, etc.).

Examples

  • Stable mainline:
    • 3.8.0
    • 3.8.2
    • 3.8.4
    • ...
  • Unstable:
    • 3.9.0
    • 3.9.2
    • 3.9.4
    • ...
  • Pre-release:
    • 3.9.1.git20150612 = pre-release of 3.9.2 (based on GIT last commit 12th June 2015)
    • 3.9.5.git20180317veryexperimentalfeature = pre-release of 3.9.6 (based on GIT last commit 12th June 2015 + adds the new cool "veryexperimentalfeature" that is not yet checked in the git repository)
    • 3.8.5.git20140930arighi = pre-release of 3.8.6 (based on GIT last commit 30 Sept 2014 + customizations added by the developer arighi, not yet checked in the svn repository)

Using GIT

SystemImager is maintained in GIT at https://github.com/finley/SystemImager. To easily submit patches for future releases, it's strongly suggested to generate them against the code in GIT (see also the submitting patches section below). There are typically three active branches at any given time: the current stable branch, the current unstable branch and the development branch (called master). If you are fixing a bug that exists in the current stable release, generate a patch against the stable branch. If you are adding a new feature or fixing a bug that is only in the unstable or development branch, use the trunk.

Instructions for accessing the SVN repository can be found at SystemImager Wiki

Submitting Patches

Following are suggested guidelines for submitting packages for a future release that make it easier to incorporate the changes.

Select e-mail destination

Always send your patches to: sisuite-devel@lists.sourceforge.net.

Separate logical changes

If your changes include multiple bug fixes and performance enhancements, separate those changes into two or more patches. On the other hand, if you make a single change to numerous files, group those changes into a single patch. Thus a single logical change is contained within a patch. If one patch depends on another patch in order for a change to be complete, that is OK. Simply note "this patch depends on patch X" in your patch description. If you cannot condense your patch set into a smaller set of patches, then only post say 15 or so at a time and wait for review and integration.

Email subject format

Use the following template for the subject of your email with a patch:

[PATCH] one-line summary

Where "one-line summary" summarizes the change the patch makes. This summary is copied directly into the svn changelog, so make sure that your summary is descriptive. "update to latest GIT" or "fix bug" is not specific enough about what portion of the code is being modified.

Keep your overall subject line under 65 characters or so.

Email body contents: description

At the beginning of your email, use as many lines as you wish to describe the patch. This text is copied directly into the GIT changelog. Be as specific as possible. The WORST descriptions possible include things like "update Server.pm", "bug fix for Server.pm", or "this patch includes updates for the server side. Please apply."

If your description starts to get too long, that's a sign that you probably need to split up your patch. Include comments you don't wish to be in the GIT changelog following a "---" terminator line. The terminator must be on a line by itself.

Name your SystemImager version

It is important to note, either in the subject line or in the patch description, the SystemImager version to which this patch applies. If the patch does not apply cleanly to the latest SystemImager version, it will reduce the chances of your change being accepted.

Email body contents: patch

Try to use "git diff" to create patches as it is the easiest way to do so. Which this method, you can create patch for a single or multiple file(s). This is done in the following way:

`SRCTREE=systemimager-3.9.6
 MYFILE1=lib/SystemImager/Server.pm
 MYFILE2=lib/SystemImager/Config.pm
 cd $SRCTREE
 vi $MYFILE1 $MYFILE2      # make your change
 git diff $MYFILE1 $MYFILE2 > /tmp/bugfix.patch`

If it is not possible, then, always uses "diff -urN" to create patches. When creating your patch, make sure to create it in "unified diff" format, as supplied by the '-u' argument to diff(1).

Patches should be based in the root SystemImager source directory, not in any lower subdirectory.

To create a patch for a single file without git, it is often sufficient to do:

 `SRCTREE=systemimager-3.9.6
  MYFILE=lib/SystemImager/Server.pm
  cd $SRCTREE
  cp $MYFILE $MYFILE.orig
  vi $MYFILE      # make your change
  cd ..
  diff -u $SRCTREE/$MYFILE{.orig,} > /tmp/${MYFILE}.patch`

To create a patch for multiple files without git, you should unpack a "vanilla", or unmodified SystemImager source tree, and generate a diff against your own source tree. For example:

`MYSRC=/devel/systemimager-3.9.6
 tar xvjf systemimager-3.9.6.tar.bz2
 mv systemimager-3.9.6 systemimager-3.9.6-vanilla
 diff -urN systemimager-3.9.6-vanilla $MYSRC > /tmp/bugfix.patch`

Make sure your patch does not include any extra files which do not belong in a patch submission. Make sure to review your patch after generated it with diff(1), to ensure accuracy.

The format of the patches made by GIT is compliant with these rules.

If your changes produce a lot of deltas, you may want to look into splitting them into individual patches which modify things in logical stages. This will facilitate easier reviewing by other SystemImager developers, very important if you want your patch accepted.

E-mail size

Large changes are not appropriate for mailing lists, and some maintainers. If your patch, uncompressed, exceeds 40 kB in size, it is preferred that you store your patch on an Internet-accessible server, and provide instead a URL (link) pointing to your patch.

No MIME, no links, no compression, no attachments: just plain text

It is important to be able to "quote" your changes, using standard e-mail tools, so that they may comment on specific portions of your code. For this reason, all patches should be submitting e-mail "inline".

Be wary of your editor's word-wrap corrupting your patch, if you choose to cut-n-paste your patch.

Do not attach the patch as a MIME attachment, compressed or not. Many popular e-mail applications will not always transmit a MIME attachment as plain text, making it impossible to comment on your code.

Tour of the Source Tree

Makefile Overview

Currently, the make system is a single Makefile that includes make snippets from other places in the tree. This setup allows you to easily depend on other make rules but also means all rules must exist in a flat namespace. Notice that the rules and variables in each .rul file use a common prefix. For example, every rule in the parted.rul file begins with "parted_", and every variable begins with "PARTED_". Another thing to keep in mind when working within this system is that all paths are relevant to the toplevel. We may change to a recursive make style build system at some point.

Third Party Software

Obsolete stuff: The SystemImager build system builds a mini Linux distribution called BOEL that runs on clients during an autoinstall (See "Additional Installation Information" in Chapter 3 for more information on BOEL). The initrd.img file contains a subset of BOEL that is small enough to allow a fast startup of the clients After the client has booted and brought up networking, it receives the boel_binaries.tar.gz file and extracts it over the root of the filesystem, providing an additional set of commands, libraries, and kernel modules that may be needed during the installation.

SystemImager.org

SystemImager logo

Clone this wiki locally