Note: this handbook isn't up-to-date, the effort to update it is at NewGuruHandbook

Table of Contents

Section 1

Section 2

Section 3

Section 4

Appendix

Bibliography

SECTION 1:

INTRODUCTION

Welcome to the wonderful world of Source Mage GNU Linux!

You are about to become a contributing member of the SGL team, the users and current team members want to thank you for your time and effort in advance.

What follows here are simple guidelines that have been set up to make everyone's work on the Grimoire simpler. We hope you enjoy the tips and have alot of fun working on the future of Source Mage GNU Linux.

GENERAL SETUP

Subscribe to all the freshmeat pages for the software in your section of the grimoire, and also appropriate email lists for that software, and also [MAILTO] sm-spell-submit@lists.ibiblio.org for our own notifications. You probably have this covered already.

You will be responsible for taking newly contributed spells from new spell submissions assigned to you via bugzilla ([WWW] http://bugs.sourcemage.org/), reviewing, correcting and submitting for inclusion in the grimoire. You may recruit as many people to help you with this as you want. You can reject, decline or otherwise ignore a newly contributed spell for any reason. You may delay reviewing spells for as long as you like.

PERFORCE REPOSITORY SETUP

To maintain your section you can use the Perforce repository and code versioning system. We have created a Quickstart guide that covers all the steps need to get you working on your section, please see PerforceQuickstart.

Section 2:

QUALITY ASSURANCE

The grimoire maintainer assumes that all submitted changes and updates to a section have been tested and tried by the section maintainers. So when a newer version of sources becomes available, please do a cast on the spell to verify that it installs and works properly before reporting the newer version. Modify spells as needed to fix problems and changes with sources.

SECURITY STEPS

To avoid a lot of extra work when dealing with updating spells, duffelbunk has been so kind as to create a script to generate the most needed components. Please take the time to get it from the "guru-tools" spell.

It's usage is:

syntax: update_spell.sh [ option ] file

options:

If you want to know the details of doing MD5 by hand:

Each spell will have its own MD5sum listed in the DETAILS file. Add a MD5 field as follows:

MD5[#]=(md5sum value)

For example, the apache2 spell points to the tarball on the apache servers and when you execute the 'summon apache2' you get a tarball in /var/spool/sorcery/httpd-2.0.36.tar.gz (current version as of this writing), by executing:

zcat /var/spool/sorcery/httpd-2.0.36.tar.gz | md5sum

we get the output:

we then place the following field in the apache2 DETAILS file:

That's it!

If you have a spell with multiple sources then you will have multiple md5[#] lines: 

MD5[0]= ....
MD5[1]= .... 
MD5[2]= ....

For all the details see MD5 download for the latest state of the Sorcery Teams efforts.

The easiest way to always get the md5 checksum that sorcery uses is to get the 'md5unpack' script that is part of the guru-tools spell. It's usage is simple: md5unpack <file>

Along these same lines there has been enough discussion to warrant a quick review of how Sorcery deals with possible multiple SOURCE_URL lines (some spells will have more than one source, such as a patch file)(where 'x' starts at '0' for the first source URL, and increments for each additional mirror):

SOURCE#_URL[x]=....

Currently mulitple sources will have lines as follows:

SOURCE_URL[x]=.... this is to allow all single url spells to remain the same and is supported. SOURCE1_URL[x]=.... SOURCE2_URL[x]=.... SOURCE3_URL[x]=....

REQUIRED TESTING

summon <spell 1> <spell 2> <spell 3>.....

[Note: any other tips can be submitted for this section to [WWW] Tome Team by any section maintainer.]

GENERAL NOTES

1. The UPDATED field should be changed with great care! The following actions will result in a recompile of a spell:

So the only reason to update the "update" field is that you absolutely need everyone who has that spell installed to recompile that spell!!!

2. You must include a HISTORY file to keep a log on the spell just include it in the spell directory and use the following general format: 

2003-10-13[ONE-SPACE]Name[ONE-SPACE]<your e-mail>
[ONE-TAB]*[ONE-SPACE]<comma-space-delimited-file(s)>:[ONE-SPACE]Description of similar changes.
[BLANK LINE HERE]
2003-10-08[ONE-SPACE]Name[ONE-SPACE]<your e-mail>
[ONE-TAB]*[ONE-SPACE]<comma+space-delimited-file(s)>:[ONE-SPACE]Description of similar changes.
[ONE-TAB]*[ONE-SPACE]<comma+space-delimited-file(s)>:[ONE-SPACE]Description of similar changes
[ONE-TAB][TWO-SPACES]continuing on another line.
[BLANK LINE HERE]

The format is simple and flexible for everyone.

Also add LICENCE field as:

LICENCE[#]=(abbr | URL)

with abbr = one of the listed short names on the licence list:

LicenseList

if this list does not contain a usable licence or the spell licence is specialized then place a complete html url pointing to the softwares licence. Please note that mulitple licenses can be added by using multiple license lines; 

LICENSE[0]= ....
LICENSE[1]= .... 
LICENSE[2]= ....

Section 3:

PERFORCE NOTES

Just some perforce usage suggestions and tips:

BUGZILLA NOTES

When a bug gets assigned to you in bugzilla, check it to see if you intend to work on it soon. If you don't have time for it at the moment, leave it as it is, otherwise change its status to ASSIGNED. If a bug doesn't have the ASSIGNED status after two weeks in bugzilla, every guru is free to take and fix it.

GRIMOIRE NOTES

The grimoire now has its own facility to define functions to be used by spells. Currently the only functions defined are glibc_is_nptl, create_account and create_group. create_account and create_group need the files accounts and groups in the grimoire root directory. Integration of changes to these files from devel to test and stable are done the usual way. Any changes to these files should also be integrated to the z-rejected grimoire. If you don't have access to z-rejected, just add a note to your perforce submission 'Please integrate this into z-rejected' and one of those with access will do it.

Section 4:

MAJOR UPDATE / CHANGES

Sometimes, due to heavy internal changes, updated software is not compatible with previous releases. It may break a user's configuration, databases, etc.

To prevent these issues, the grimoire maintainer should post a warning on the mailing list, with the following informations if available:

Depending on the spell's importance, the maintainer should ask for beta tester participation, and for user feedback even before pushing the update into devel grimoire.

If other spells are known to depend on it or if the spell is system critical, the maintainer should contact the grimoire team leader to ensure grimoire-wide teamwork and synchronization.

SPELL DEPRECATION

see Spell Deprecation

GRIMOIRE CHANGELOG

Whenever a spell gets deprecated, renamed or moved to another section/grimoire, an entry should be added to the grimoire ChangeLog stating what has been done.

APPENDIX:

FILE HIERARCHY STANDARDS IN LINUX:

This is a short discription of the Linux files system as presented by Avi Alkalay in his essay [1].

Linux system directories

/usr/bin Directory for the executables that are accessed by all users (everybody has this directory in his $PATH). The main files of your software will probably be here. You should never create a subdirectory under this directory.

/bin Like /usr/bin, but here you'll find only boot process-vital executables that are simple and small. Your software (being high-level) probably doesn't have anything to install here.

/usr/sbin Like /usr/bin, but contains only the executables that must be accessed by the administrator (root user). Regular users should never have this directory in their $PATH. If your software is a daemon, this is the directory for some of its executables.

/sbin Like /usr/sbin, but only for the boot process-vital executables, and some that will be accessed by sysadmin for some system maintenance. Commands like fsck (filesystem check), init (father of all processes), ifconfig (network configuration), mount, etc., can be found here. It is the system's most vital directory in many ways.

/usr/lib Contains dynamic libraries and support static files for the executables at /usr/bin and /usr/sbin. You may create a subdirectory such as /usr/lib/myproduct to contain your helper files or dynamic libraries that will be accessed only by your software without user intervention. A subdirectory here may be used as a container for plugins and extensions.

/lib Like /usr/lib but contains dynamic libraries and support static files needed in the boot process. You'll never find an executable at /bin or /sbin that needs a library that is outside this directory. Kernel modules (device drivers) are under /lib.

/etc Contains configuration files. If your software uses several files, put them in a subdirectory such as /etc/myproduct/.

/var The name comes from "variable", because everything that is under this directory changes a frequently. Often, /var is mounted in a separate high-performance partition. In /var/log logfiles grow. For web content we use /var/www, and so on.

/home Contains the users' (real human beings') home directories. Your software package should never install files here (during installation). If your business logic requires a special UNIX user (not a human being) to be created, you should assign him a home directory under /var or some other place outside /home. Do not forget that.

/usr/share/doc, /usr/share/man The "share" word is used because what is under /usr/share is platform independent, and can be shared among several machines thru a network filesystem. Portanto this is the place for manuals, documentations, examples etc.

/usr/local, /opt These are obsolete folders. When UNIX didn't have a package system (like RPM), sysadmins needed to separate an optional (or local) application from the main OS. These were the directories used for that.

Quick Perforce Submit Script:

This is a script that allow faster submission of perforce changes to the grimoire, hence increasing productivity. This script allow the user to include the description of changes on the command line instead of using an editor to include the description. The script is saved as p4submit and contains: 

#!/bin/bash
export  A=$'\\a' &&
p4 change -o | sed -e "s${A}<enter description here>${A}${1}${A}" | p4 submit -i

An example of its use is: p4submit "Update version to 2.0.1"

Grimoire Tree Layout:
|-test
|
|-stable-rc
| |
| |-0.0
| | |
| | |-stable/0.0
| | |
| | |
| | |-0.1
| | | |
| | | |-stable/0.1
| | |
| | |...
-z-rejected
-games

What this means is that changes are made in test, z-rejected, or games. If a change is made in test then it should be pulled into stable-rc if it works, or marked with a WIP file explaining why it should stay in devel. The Quality Assurance Team will do integrates into stable-rc, which is then branched into stable as a new release is made.

BIBLIOGRAPHY:

[1] A.Alkalay, 'Creating Integrated High Quality Linux Applications', [WWW] http://www.linuxandmain.com/essay/avi.html, IBM, 2002.

last edited 2007-02-21 04:03:27 by TommyBoatman