From: Benj. Mako Hill Date: Sat, 4 Jun 2005 00:07:11 +0000 (+0000) Subject: Added FreeSoftwareDevelopment which is the actual HOWTO document. So far, it X-Git-Url: https://projects.mako.cc/source/fspm_howto/commitdiff_plain/febb7957a8feb7e38610ebf3f920c7090fca1e74 Added FreeSoftwareDevelopment which is the actual HOWTO document. So far, it Author: mako Date: 2001/01/02 21:48:33 Added FreeSoftwareDevelopment which is the actual HOWTO document. So far, it is mostly just a copy of the template but I've put in an outline that goes as far as halfway through the 'Interacting with Users' section and still has mot of the old stuff. --- diff --git a/FreeSoftwareDevelopmentHOWTO.sgml b/FreeSoftwareDevelopmentHOWTO.sgml new file mode 100644 index 0000000..98e1607 --- /dev/null +++ b/FreeSoftwareDevelopmentHOWTO.sgml @@ -0,0 +1,1439 @@ + + +
+ + + + + Free Software Development HOWTO + + + Benjamin + Mako + Hill + +
+ mako@debian.org +
+ + + + + + v0.01 + 1 January 2001 + bch + + Initial Release + + + + + + + fswd + + + + This HOWTO is designed for people with experience in programming + and some skills in managing a software project but who are new to + the world of Free Software. This document is meant to act as a + guide to the non-technical aspects of programming and is meant as + a crash course in the people skills that can make or break a free + software project. + + + + + + + + + Introduction + + + fswd!introduction + + + + For various reasons this brand new release is codenamed the + release release. + + + + New code names will appear as per industry standard + guidelines to emphasize the state-of-the-art-ness of this + document. + + + + This document was written when I read a feedback asking for a + template to fill in to make new HOWTOs. This template was + initially made by extracting the skeletal structure of the Multi + Disk HOWTO which is a rather large HOWTO. It then went through + extensive editing. + + + + Stating the background is a simple way to getting started + writing the intro. + + + + First of all we need a bit of legalese. Recent development + shows it is quite important. + + + + + + Copyright Information + + + This document is copyrighted (c) 2000 Stein Gjoen and is + distributed under the terms of the Linux Documentation Project + (LDP) license, stated below. Replace with your name, + or supply a new license, when you use this skeleton for a new + HOWTO. + + + + Unless otherwise stated, Linux HOWTO documents are + copyrighted by their respective authors. Linux HOWTO documents may + be reproduced and distributed in whole or in part, in any medium + physical or electronic, as long as this copyright notice is + retained on all copies. Commercial redistribution is allowed and + encouraged; however, the author would like to be notified of any + such distributions. + + + + All translations, derivative works, or aggregate works + incorporating any Linux HOWTO documents must be covered under this + copyright notice. That is, you may not produce a derivative work + from a HOWTO and impose additional restrictions on its + distribution. Exceptions to these rules may be granted under + certain conditions; please contact the Linux HOWTO coordinator at + the address given below. + + + + In short, we wish to promote dissemination of this + information through as many channels as possible. However, we do + wish to retain copyright on the HOWTO documents, and would like to + be notified of any plans to redistribute the HOWTOs. + + + + If you have any questions, please contact + linux-howto@metalab.unc.edu + + + + + + + Disclaimer + + + No liability for the contents of this documents can be accepted. + Use the concepts, examples and other content at your own risk. + As this is a new edition of this document, there may be errors + and inaccuracies, that may of course be damaging to your system. + Proceed with caution, and although this is highly unlikely, + the author(s) do not take any responsibility for that. + + + + All copyrights are held by their by their respective owners, unless + specifically noted otherwise. Use of a term in this document + should not be regarded as affecting the validity of any trademark + or service mark. + + + + Naming of particular products or brands should not be seen + as endorsements. + + + + You are strongly recommended to take a backup of your system + before major installation and backups at regular intervals. + + + + + + + New Versions + + + (your index root)!news on + + + + This is where you make a summary of what is new. When a + HOWTO exceeds 20 pages it takes more than a casual read to find + the updates. This is where you help your readers with that, + alerting them to specific and important updates to the document. + + + + This is the initial release. + + + + Tell people where the document home page is so the very + newest release could be found in case of problems with the main + Linux Documentation + Project homepage. + + + + The following is a sample from the Multi Disk HOWTO: + + + + The latest version number of this document can be + gleaned from my plan entry if you + + finger my Nyx account. + + + + If you have the capability, it would be nice to + make the HOWTO available in a number of formats. + + + + The newest version of this HOWTO will always be made available on + my website, in a variety of formats: + + + + + + + HTML. + + + + + + plain text. + + + + + + compressed + postscript (US letter format). + + + + + + SGML source. + + + + + + + Note that paper sizes vary in the world, A4 and US letter differ + significantly. You might also wish to consider using the + universal format (8.27x11in; 210x279mm). + + + + + + + Credits + + + It is always nice to acknowledge people who help you + with input; it is also regarded by many as important in the + Linux world new economy. + + + + In this version I have the pleasure of acknowledging: + + + + name (at) site.org + + + + Please scramble the addresses so email harvesters + cannot get addresses from your HOWTO and then spam people. That + has happened in the past. + + + + Somecompany is acknowledged for sending me + documentation on their gizmos as well as permission to quote from + the material. These quotes have been approved before appearing + here and will be clearly labeled. + + + + + + + Feedback + + + Feedback is most certainly welcome for this document. Without + your submissions and input, this document wouldn't exist. Please + send your additions, comments and criticisms to the following + email address : sgjoen@nyx.net. + + + + + + + Translations + + + Not everyone speaks English, pointers to translations are nice. + Also your translators tend to give very important inputs. + + + + + + + + German Translation + by someone (at) somewhere.de + + + + + + French Translation + by someone (at) somewhere.fr + + + + + + Italian Translation + by someone (at) somewhere.it + + + + + + + + + + + + + + Starting a Project + + + + + Choosing a Project + + + + + + Deciding on a License + + + + + + Choosing a Method of Version Numbering + + + + + + Documentation + + + + + + Other Presentation Issues + + + + + + Nuturing Future Development + + + + + + + + + + Maintaining a Project: Interacting with Developers + + + + + Delegating Work + + + + + + Stable and Development Branches + + + + + + Freezing + + + + + + Avoiding the Code Cram Effect + + + + + + Accepting and Rejecting Patches + + + + + + + Maintaining a Project: Interacting with Users + + + + + Announcing Your Project + + + + + + Testing and Testers + + + + + + + Samples + + + This section gives some simple SGML examples you could + use. Read the SGML source to see how it was done. + + + + Further information and examples can be obtained from the publication + DocBook: The Definitive + Guide. Written by Norman Walsh + and Leonard Muellner; 1st Edition, October 1999. + + + + + + Lists + + + Lists are used frequently, and are available in a number + of formats shown below. + + + + A list in which each entry is marked with a bullet or other dingbat: + + + + + + + Apples + + + + Oranges + + + + Bananas + + + + + + + A list in which each entry is composed of a set of one or more + terms and an associated description: + + + + + + + Fruits + + such as apples, oranges, and more. + + + + + Nuts + + Don't eat too many; you are what you eat. + + + + + Vegetables + + Potatos are spelled with care. + + + + + + + + A list in which each entry is marked with a sequentially + incremented label: + + + + + + + Step one + + + + Step two + + + + + + + + + + Links + + + Links can be used within your documents to refer to + different sections and chapters or to refer to documents external + to yours. + + + + Internal links + + + Click on the link to jump to the top of + this chapter. Note the anchor at the section tag. + + + + + External links + + + Click on this link + to jump to the LDP site. Note you can use http, ftp, news and + other protocols in the locator if required. + + + + + + + + + Images + + + Avoid diagrams if possible as this cannot be rendered + in the ASCII outputs which are still needed by many around the + world. + + + +
+ Graphics Test Image + +
+ + + + Here is another variation which allows for ALT text: + + + + + + + + + + + + ALT text to be used: Green Ball + + + + + + Caption for the graphic goes here: This is a Green Ball. + + + + + + + + + + + + + + + Structure + + + A quick overview on how all parts fit together in the overall + structure. An example from the Multi Disk HOWTO is used. + + + + As this type of document is supposed to be as much for learning as + a technical reference document I have rearranged the structure to + this end. For the designer of a system it is more useful to have + the information presented in terms of the goals of this exercise + than from the point of view of the logical layer structure of the + devices themselves. Nevertheless this document would not be + complete without such a layer structure the computer field is so + full of, so I will include it here as an introduction to how it + works. + + + + + + Logical structure + + + disk!structure, I/O subsystem + + + + This is based on how each layer access each other, traditionally + with the application on top and the physical layer on the bottom. + It is quite useful to show the interrelationship between each of + the layers used in controlling drives. + + + ___________________________________________________________ + |__ File structure ( /usr /tmp etc) __| + |__ File system (ext2fs, vfat etc) __| + |__ Volume management (AFS) __| + |__ RAID, concatenation (md) __| + |__ Device driver (SCSI, IDE etc) __| + |__ Controller (chip, card) __| + |__ Connection (cable, network) __| + |__ Drive (magnetic, optical etc) __| + ----------------------------------------------------------- + + + + + In the above diagram both volume management and RAID and + concatenation are optional layers. The 3 lower layers are in + hardware. All parts are discussed at length later on in this + document. + + + + + + + Document structure + + + Most users start out with a given set of hardware and some plans + on what they wish to achieve and how big the system should be. + This is the point of view I will adopt in this document in + presenting the material, starting out with hardware, continuing + with design constraints before detailing the design strategy that + I have found to work well. I have used this both for my own + personal computer at home, a multi purpose server at work and + found it worked quite well. In addition my Japanese co-worker in + this project have applied the same strategy on a server in an + academic setting with similar success. + + + + Finally at the end I have detailed some configuration tables for + use in your own design. If you have any comments regarding this + or notes from your own design work I would like to hear from you + so this document can be upgraded. + + + + + + + Reading plan + + + As you go beyond 50 pages or so there will be a lot of + text that experts and even the experienced do not need to read. + Keeping in mind that we wish to care for all kinds of people in + the Linux world we might have to make a reading plan. Again, + an example follows from the Multi Disk HOWTO. + + + + Although not the biggest HOWTO it is nevertheless rather big + already and I have been requested to make a reading plan to make + it possible to cut down on the volume. + + + + + + + Expert + + + (aka the elite). If you are familiar with Linux as well as + disk drive technologies you will find most of what you need in + the appendices. Additionally you are recommended to read the + FAQ and the chapter. + + + + + + Experienced + + + (aka Competent). If you are familiar with computers in + general you can go straight to the chapters on + and continue from there on. + + + + + + Newbie + + + (mostly harmless). You just have to read the whole thing. + Sorry. In addition you are also recommended to read all the + other disk related HOWTOs. + + + + + + + + + + + + + + + + + Technologies + + + (your index root)!technologies + + + + Introduction of technology for the newbie with a few + references to detailed works. Remember that not everyone has + Internet access so you have to explain in sufficient details so + even the newbie can get by. + + + + + + + + + + + Implementation + + + (your index root)!implementation + + + + Now your readers should have a sufficient knowledge of + what this is about and now we come to the hands on of implementing + your clever scheme. + + + + + + + + + + + Maintenance + + + (your index root)!maintenance + + + + Few systems and designs are maintenance free, here you + explain how to keep the system running. + + + + + + + + + + + Advanced Issues + + + (your index root)!advanced topics + + + + You can get most things up and running in a quick and + dirty fashion, useful for testing and getting used to how things + work. For more serious use you would need to be a little more + advanced. This is the place to explain it all, if applicable. + + + + + + + + + + + Further Information + + + (your index root)!information resources + + + + A HOWTO cannot describe everything, some times the user + has to venture out on th enet to get more information or just + updates. Here is the place to tell where and how. Again examples + from the Multi Disk HOWTO, replace as needed. There is wealth + of information one should go through when setting up a major system, + for instance for a news or general Internet service provider. The + FAQs in the following groups are useful: + + + + + + News groups + + + disk!information resources!news groups + + + Some of the most interesting news groups are: + + + + + + Storage. + + + + + + PC storage. + + + + + + AFS. + + + + + + SCSI. + + + + + + Linux setup. + + + + + + + + Most newsgroups have their own FAQ that are designed to answer most + of your questions, as the name Frequently Asked Questions indicate. + Fresh versions should be posted regularly to the relevant newsgroups. + If you cannot find it in your news spool you could go directly to the + FAQ main archive FTP site. + The WWW versions can be browsed at the + FAQ + main archive WWW site. + + + + Some FAQs have their own home site, of particular interest: + + + + + + SCSI FAQ + and + + + + + + comp.arch.storage FAQ. + + + + + + + + + + + Mailing Lists + + + disk!information resources!mailing lists + + + + These are low-noise channels mainly for developers. Think twice + before asking questions there as noise delays the development. + Some relevant lists are linux-raid, + linux-scsi and linux-ext2fs. Many + of the most useful mailing lists run on the vger.rutgers.edu server but this is + notoriously overloaded, so try to find a mirror. There are some + lists mirrored at The Redhat + Home Page. Many lists are also accessible at linuxhq, and the + rest of the web site contains useful information as well. + + + + If you want to find out more about the lists available you can send + a message with the line lists to the list server + at majordomo@vger.rutgers.edu. + If you need help on how to use the mail server just send the line + help to the same address. Due to the + popularity of this server it is likely it takes a bit to time before + you get a reply or even get messages after you send a + subscribe command. + + + + There is also a number of other majordomo list servers that can + be of interest such as the EATA driver list + (linux-eata@mail.uni-mainz.de) + and the Intelligent IO list linux-i2o@dpt.com. + + + + Mailing lists are in a state of flux but you can find links to a + number of interesting lists from the + Linux Documentation + Homepage. + + + + + + + HOWTO + + + disk!information resources!HOWTOs + + + + These are intended as the primary starting points to get the + background information as well as show you how to solve a + specific problem. Some relevant HOWTOs are + Bootdisk, + Installation, + SCSI and + UMSDOS. The main site for these is the + LDP archiveat + Metalab (formerly known as Sunsite). + + + + There is a a new HOWTO out that deals with setting up a DPT RAID + system, check out the + DPT RAID + HOWTO homepage. + + + + + + + Local Resources + + + disk!information resources!local + + + + In most distributions of Linux there is a document directory + installed, have a look in the /usr/doc + directory. where most packages store their main documentation and + README files etc. Also you will here find the HOWTO archive + (/usr/doc/HOWTO) of ready formatted HOWTOs + and also the mini-HOWTO archive + (/usr/doc/HOWTO/mini) of plain text + documents. + + + + Many of the configuration files mentioned earlier can be found in + the /etc directory. In particular you will + want to work with the /etc/fstab file that + sets up the mounting of partitions and possibly also + /etc/raidtab file that is used for the + md system to set up RAID. + + + + The kernel source in /usr/src/linux is, of + course, the ultimate documentation. In other words, use + the source, Luke. It should also be pointed out that the + kernel comes not only with source code which is even commented + (well, partially at least) but also an informative + /usr/src/linux/Documentation. If you are + about to ask any questions about the kernel you should read this + first, it will save you and many others a lot of time and + possibly embarrassment. + + + + Also have a look in your system log file + (/var/log/messages) to see what is going on + and in particular how the booting went if too much scrolled off + your screen. Using tail -f /var/log/messages + in a separate window or screen will give you a continuous update + of what is going on in your system. + + + + You can also take advantage of the /proc + file system that is a window into the inner workings of your + system. Use cat rather than + more to view the files as they are reported as + being zero length. Reports are that less works + well here. + + + + + + + Web Sites + + + disk!information resources!WWW + + + disk!information resources!web pages + + + + There are a huge number of informative web sites available. By + their very nature they change quickly so do not be surprised + if these links become quickly outdated. + + + + A good starting point is of course the + Linux Documentation + Project home page, an information central for + documentation, project pages and much more. + + + + Please let me know if you have any other leads that can be + of interest. + + + + + + + + + + + + Getting Help + + + (your index root)!assistance, obtaining + + + + In the end you might find yourself unable to solve your problems + and need help from someone else. The most efficient way is either + to ask someone local or in your nearest Linux user group, search + the web for the nearest one. + + + + Another possibility is to ask on Usenet News in one of the many, + many newsgroups available. The problem is that these have such a + high volume and noise (called low signal-to-noise ratio) that your + question can easily fall through unanswered. + + + + No matter where you ask it is important to ask well or you will + not be taken seriously. Saying just my disk + does not work is not going to help you and instead the + noise level is increased even further and if you are lucky someone + will ask you to clarify. + + + + Instead describe your problems in some detail that will enable + people to help you. The problem could lie somewhere you did not + expect. Therefore you are advised to list the following information + about your system: + + + + + + + Hardware + + + + + Processor + + + + DMA + + + + IRQ + + + + Chip set (LX, BX etc) + + + + Bus (ISA, VESA, PCI etc) + + + + + Expansion cards used (Disk controllers, video, IO + etc.) + + + + + + + + + + Software + + + + + + BIOS (On motherboard and possibly SCSI host adapters) + + + + LILO, if used + + + + + Linux kernel version as well as possible modifications + and patches + + + + + Kernel parameters, if any + + + + + Software that shows the error (with version number + or date) + + + + + + + + + + + Peripherals + + + + + + + Type of disk drives with manufacturer name, version and type + + + + + Other relevant peripherals + + + + + + + + + + + + Remember that booting text is logged to + /var/log/messages which can answer most of + the questions above. Obviously if the drives fail you might not be + able to get the log saved to disk but you can at least scroll + back up the screen using the SHIFT and + PAGE UP keys. It may also be useful to include + part of this in your request for help but do not go overboard, + keep it brief as a complete log file dumped + to Usenet News is more than a little annoying. + + + + + + + + + + + Concluding Remarks + + + (your index root)!conclusion + + + + Just summing up... Also a place for general + recommendations. + + + + + + + + + + + Questions and Answers + + + (your index root)!FAQ + + + (your index root)!frequently asked questions + + + + Check the newsgroups and try to determine some frequent + problems and cover them here. Again an example from the Multi Disk + HOWTO. + + + + This is just a collection of what I believe are the most common + questions people might have. Give me more feedback and I will turn + this section into a proper FAQ. + + + + + + + Q:How many physical disk drives (spindles) does a Linux system need? + + + + A: Linux can run just fine on one drive (spindle). Having + enough RAM (around 32 MB, and up to 64 MB) to support swapping + is a better price/performance choice than getting a second + disk. (E)IDE disk is usually cheaper (but a little slower) than + SCSI. + + + + + + Q: Are there any disadvantages in this scheme? + + + + A: There is only a minor snag: if even a single partition + overflows the system might stop working properly. The severity + depends of course on what partition is affected. Still this is + not hard to monitor, the command df gives + you a good overview of the situation. Also check the swap + partition(s) using free to make sure you are + not about to run out of virtual memory. + + + + + + Q: OK, so should I split the system into as many partitions as + possible for a single drive? + + + + A: No, there are several disadvantages to that. First of all + maintenance becomes needlessly complex and you gain very little + in this. In fact if your partitions are too big you will seek + across larger areas than needed. This is a balance and + dependent on the number of physical drives you have. + + + + + + + Greg Leblanc: Depending on how big this FAQ gets, perhaps it + would be worthwhile to have, say, the 5 most FAQ, and put the + rest into an external FAQ. Dunno. Comments? + + + (rest deleted.) + + + + + + + + + + + Bits and Pieces + + + disk!miscellaneous + + + + This is basically a section where I stuff all the bits I have not + yet decided where should go, yet that I feel is worth knowing + about. It is a kind of transient area. + + + + + + + + + + + Examples + + + (your index root)!examples + + + + Example designs and sample configuration files and other + relevant details is always handy + + + + + + +
+ + diff --git a/FreeSoftwareProjectManagementHOWTO.sgml b/FreeSoftwareProjectManagementHOWTO.sgml new file mode 100644 index 0000000..98e1607 --- /dev/null +++ b/FreeSoftwareProjectManagementHOWTO.sgml @@ -0,0 +1,1439 @@ + + +
+ + + + + Free Software Development HOWTO + + + Benjamin + Mako + Hill + +
+ mako@debian.org +
+ + + + + + v0.01 + 1 January 2001 + bch + + Initial Release + + + + + + + fswd + + + + This HOWTO is designed for people with experience in programming + and some skills in managing a software project but who are new to + the world of Free Software. This document is meant to act as a + guide to the non-technical aspects of programming and is meant as + a crash course in the people skills that can make or break a free + software project. + + + + + + + + + Introduction + + + fswd!introduction + + + + For various reasons this brand new release is codenamed the + release release. + + + + New code names will appear as per industry standard + guidelines to emphasize the state-of-the-art-ness of this + document. + + + + This document was written when I read a feedback asking for a + template to fill in to make new HOWTOs. This template was + initially made by extracting the skeletal structure of the Multi + Disk HOWTO which is a rather large HOWTO. It then went through + extensive editing. + + + + Stating the background is a simple way to getting started + writing the intro. + + + + First of all we need a bit of legalese. Recent development + shows it is quite important. + + + + + + Copyright Information + + + This document is copyrighted (c) 2000 Stein Gjoen and is + distributed under the terms of the Linux Documentation Project + (LDP) license, stated below. Replace with your name, + or supply a new license, when you use this skeleton for a new + HOWTO. + + + + Unless otherwise stated, Linux HOWTO documents are + copyrighted by their respective authors. Linux HOWTO documents may + be reproduced and distributed in whole or in part, in any medium + physical or electronic, as long as this copyright notice is + retained on all copies. Commercial redistribution is allowed and + encouraged; however, the author would like to be notified of any + such distributions. + + + + All translations, derivative works, or aggregate works + incorporating any Linux HOWTO documents must be covered under this + copyright notice. That is, you may not produce a derivative work + from a HOWTO and impose additional restrictions on its + distribution. Exceptions to these rules may be granted under + certain conditions; please contact the Linux HOWTO coordinator at + the address given below. + + + + In short, we wish to promote dissemination of this + information through as many channels as possible. However, we do + wish to retain copyright on the HOWTO documents, and would like to + be notified of any plans to redistribute the HOWTOs. + + + + If you have any questions, please contact + linux-howto@metalab.unc.edu + + + + + + + Disclaimer + + + No liability for the contents of this documents can be accepted. + Use the concepts, examples and other content at your own risk. + As this is a new edition of this document, there may be errors + and inaccuracies, that may of course be damaging to your system. + Proceed with caution, and although this is highly unlikely, + the author(s) do not take any responsibility for that. + + + + All copyrights are held by their by their respective owners, unless + specifically noted otherwise. Use of a term in this document + should not be regarded as affecting the validity of any trademark + or service mark. + + + + Naming of particular products or brands should not be seen + as endorsements. + + + + You are strongly recommended to take a backup of your system + before major installation and backups at regular intervals. + + + + + + + New Versions + + + (your index root)!news on + + + + This is where you make a summary of what is new. When a + HOWTO exceeds 20 pages it takes more than a casual read to find + the updates. This is where you help your readers with that, + alerting them to specific and important updates to the document. + + + + This is the initial release. + + + + Tell people where the document home page is so the very + newest release could be found in case of problems with the main + Linux Documentation + Project homepage. + + + + The following is a sample from the Multi Disk HOWTO: + + + + The latest version number of this document can be + gleaned from my plan entry if you + + finger my Nyx account. + + + + If you have the capability, it would be nice to + make the HOWTO available in a number of formats. + + + + The newest version of this HOWTO will always be made available on + my website, in a variety of formats: + + + + + + + HTML. + + + + + + plain text. + + + + + + compressed + postscript (US letter format). + + + + + + SGML source. + + + + + + + Note that paper sizes vary in the world, A4 and US letter differ + significantly. You might also wish to consider using the + universal format (8.27x11in; 210x279mm). + + + + + + + Credits + + + It is always nice to acknowledge people who help you + with input; it is also regarded by many as important in the + Linux world new economy. + + + + In this version I have the pleasure of acknowledging: + + + + name (at) site.org + + + + Please scramble the addresses so email harvesters + cannot get addresses from your HOWTO and then spam people. That + has happened in the past. + + + + Somecompany is acknowledged for sending me + documentation on their gizmos as well as permission to quote from + the material. These quotes have been approved before appearing + here and will be clearly labeled. + + + + + + + Feedback + + + Feedback is most certainly welcome for this document. Without + your submissions and input, this document wouldn't exist. Please + send your additions, comments and criticisms to the following + email address : sgjoen@nyx.net. + + + + + + + Translations + + + Not everyone speaks English, pointers to translations are nice. + Also your translators tend to give very important inputs. + + + + + + + + German Translation + by someone (at) somewhere.de + + + + + + French Translation + by someone (at) somewhere.fr + + + + + + Italian Translation + by someone (at) somewhere.it + + + + + + + + + + + + + + Starting a Project + + + + + Choosing a Project + + + + + + Deciding on a License + + + + + + Choosing a Method of Version Numbering + + + + + + Documentation + + + + + + Other Presentation Issues + + + + + + Nuturing Future Development + + + + + + + + + + Maintaining a Project: Interacting with Developers + + + + + Delegating Work + + + + + + Stable and Development Branches + + + + + + Freezing + + + + + + Avoiding the Code Cram Effect + + + + + + Accepting and Rejecting Patches + + + + + + + Maintaining a Project: Interacting with Users + + + + + Announcing Your Project + + + + + + Testing and Testers + + + + + + + Samples + + + This section gives some simple SGML examples you could + use. Read the SGML source to see how it was done. + + + + Further information and examples can be obtained from the publication + DocBook: The Definitive + Guide. Written by Norman Walsh + and Leonard Muellner; 1st Edition, October 1999. + + + + + + Lists + + + Lists are used frequently, and are available in a number + of formats shown below. + + + + A list in which each entry is marked with a bullet or other dingbat: + + + + + + + Apples + + + + Oranges + + + + Bananas + + + + + + + A list in which each entry is composed of a set of one or more + terms and an associated description: + + + + + + + Fruits + + such as apples, oranges, and more. + + + + + Nuts + + Don't eat too many; you are what you eat. + + + + + Vegetables + + Potatos are spelled with care. + + + + + + + + A list in which each entry is marked with a sequentially + incremented label: + + + + + + + Step one + + + + Step two + + + + + + + + + + Links + + + Links can be used within your documents to refer to + different sections and chapters or to refer to documents external + to yours. + + + + Internal links + + + Click on the link to jump to the top of + this chapter. Note the anchor at the section tag. + + + + + External links + + + Click on this link + to jump to the LDP site. Note you can use http, ftp, news and + other protocols in the locator if required. + + + + + + + + + Images + + + Avoid diagrams if possible as this cannot be rendered + in the ASCII outputs which are still needed by many around the + world. + + + +
+ Graphics Test Image + +
+ + + + Here is another variation which allows for ALT text: + + + + + + + + + + + + ALT text to be used: Green Ball + + + + + + Caption for the graphic goes here: This is a Green Ball. + + + + + + + + + + + + + + + Structure + + + A quick overview on how all parts fit together in the overall + structure. An example from the Multi Disk HOWTO is used. + + + + As this type of document is supposed to be as much for learning as + a technical reference document I have rearranged the structure to + this end. For the designer of a system it is more useful to have + the information presented in terms of the goals of this exercise + than from the point of view of the logical layer structure of the + devices themselves. Nevertheless this document would not be + complete without such a layer structure the computer field is so + full of, so I will include it here as an introduction to how it + works. + + + + + + Logical structure + + + disk!structure, I/O subsystem + + + + This is based on how each layer access each other, traditionally + with the application on top and the physical layer on the bottom. + It is quite useful to show the interrelationship between each of + the layers used in controlling drives. + + + ___________________________________________________________ + |__ File structure ( /usr /tmp etc) __| + |__ File system (ext2fs, vfat etc) __| + |__ Volume management (AFS) __| + |__ RAID, concatenation (md) __| + |__ Device driver (SCSI, IDE etc) __| + |__ Controller (chip, card) __| + |__ Connection (cable, network) __| + |__ Drive (magnetic, optical etc) __| + ----------------------------------------------------------- + + + + + In the above diagram both volume management and RAID and + concatenation are optional layers. The 3 lower layers are in + hardware. All parts are discussed at length later on in this + document. + + + + + + + Document structure + + + Most users start out with a given set of hardware and some plans + on what they wish to achieve and how big the system should be. + This is the point of view I will adopt in this document in + presenting the material, starting out with hardware, continuing + with design constraints before detailing the design strategy that + I have found to work well. I have used this both for my own + personal computer at home, a multi purpose server at work and + found it worked quite well. In addition my Japanese co-worker in + this project have applied the same strategy on a server in an + academic setting with similar success. + + + + Finally at the end I have detailed some configuration tables for + use in your own design. If you have any comments regarding this + or notes from your own design work I would like to hear from you + so this document can be upgraded. + + + + + + + Reading plan + + + As you go beyond 50 pages or so there will be a lot of + text that experts and even the experienced do not need to read. + Keeping in mind that we wish to care for all kinds of people in + the Linux world we might have to make a reading plan. Again, + an example follows from the Multi Disk HOWTO. + + + + Although not the biggest HOWTO it is nevertheless rather big + already and I have been requested to make a reading plan to make + it possible to cut down on the volume. + + + + + + + Expert + + + (aka the elite). If you are familiar with Linux as well as + disk drive technologies you will find most of what you need in + the appendices. Additionally you are recommended to read the + FAQ and the chapter. + + + + + + Experienced + + + (aka Competent). If you are familiar with computers in + general you can go straight to the chapters on + and continue from there on. + + + + + + Newbie + + + (mostly harmless). You just have to read the whole thing. + Sorry. In addition you are also recommended to read all the + other disk related HOWTOs. + + + + + + + + + + + + + + + + + Technologies + + + (your index root)!technologies + + + + Introduction of technology for the newbie with a few + references to detailed works. Remember that not everyone has + Internet access so you have to explain in sufficient details so + even the newbie can get by. + + + + + + + + + + + Implementation + + + (your index root)!implementation + + + + Now your readers should have a sufficient knowledge of + what this is about and now we come to the hands on of implementing + your clever scheme. + + + + + + + + + + + Maintenance + + + (your index root)!maintenance + + + + Few systems and designs are maintenance free, here you + explain how to keep the system running. + + + + + + + + + + + Advanced Issues + + + (your index root)!advanced topics + + + + You can get most things up and running in a quick and + dirty fashion, useful for testing and getting used to how things + work. For more serious use you would need to be a little more + advanced. This is the place to explain it all, if applicable. + + + + + + + + + + + Further Information + + + (your index root)!information resources + + + + A HOWTO cannot describe everything, some times the user + has to venture out on th enet to get more information or just + updates. Here is the place to tell where and how. Again examples + from the Multi Disk HOWTO, replace as needed. There is wealth + of information one should go through when setting up a major system, + for instance for a news or general Internet service provider. The + FAQs in the following groups are useful: + + + + + + News groups + + + disk!information resources!news groups + + + Some of the most interesting news groups are: + + + + + + Storage. + + + + + + PC storage. + + + + + + AFS. + + + + + + SCSI. + + + + + + Linux setup. + + + + + + + + Most newsgroups have their own FAQ that are designed to answer most + of your questions, as the name Frequently Asked Questions indicate. + Fresh versions should be posted regularly to the relevant newsgroups. + If you cannot find it in your news spool you could go directly to the + FAQ main archive FTP site. + The WWW versions can be browsed at the + FAQ + main archive WWW site. + + + + Some FAQs have their own home site, of particular interest: + + + + + + SCSI FAQ + and + + + + + + comp.arch.storage FAQ. + + + + + + + + + + + Mailing Lists + + + disk!information resources!mailing lists + + + + These are low-noise channels mainly for developers. Think twice + before asking questions there as noise delays the development. + Some relevant lists are linux-raid, + linux-scsi and linux-ext2fs. Many + of the most useful mailing lists run on the vger.rutgers.edu server but this is + notoriously overloaded, so try to find a mirror. There are some + lists mirrored at The Redhat + Home Page. Many lists are also accessible at linuxhq, and the + rest of the web site contains useful information as well. + + + + If you want to find out more about the lists available you can send + a message with the line lists to the list server + at majordomo@vger.rutgers.edu. + If you need help on how to use the mail server just send the line + help to the same address. Due to the + popularity of this server it is likely it takes a bit to time before + you get a reply or even get messages after you send a + subscribe command. + + + + There is also a number of other majordomo list servers that can + be of interest such as the EATA driver list + (linux-eata@mail.uni-mainz.de) + and the Intelligent IO list linux-i2o@dpt.com. + + + + Mailing lists are in a state of flux but you can find links to a + number of interesting lists from the + Linux Documentation + Homepage. + + + + + + + HOWTO + + + disk!information resources!HOWTOs + + + + These are intended as the primary starting points to get the + background information as well as show you how to solve a + specific problem. Some relevant HOWTOs are + Bootdisk, + Installation, + SCSI and + UMSDOS. The main site for these is the + LDP archiveat + Metalab (formerly known as Sunsite). + + + + There is a a new HOWTO out that deals with setting up a DPT RAID + system, check out the + DPT RAID + HOWTO homepage. + + + + + + + Local Resources + + + disk!information resources!local + + + + In most distributions of Linux there is a document directory + installed, have a look in the /usr/doc + directory. where most packages store their main documentation and + README files etc. Also you will here find the HOWTO archive + (/usr/doc/HOWTO) of ready formatted HOWTOs + and also the mini-HOWTO archive + (/usr/doc/HOWTO/mini) of plain text + documents. + + + + Many of the configuration files mentioned earlier can be found in + the /etc directory. In particular you will + want to work with the /etc/fstab file that + sets up the mounting of partitions and possibly also + /etc/raidtab file that is used for the + md system to set up RAID. + + + + The kernel source in /usr/src/linux is, of + course, the ultimate documentation. In other words, use + the source, Luke. It should also be pointed out that the + kernel comes not only with source code which is even commented + (well, partially at least) but also an informative + /usr/src/linux/Documentation. If you are + about to ask any questions about the kernel you should read this + first, it will save you and many others a lot of time and + possibly embarrassment. + + + + Also have a look in your system log file + (/var/log/messages) to see what is going on + and in particular how the booting went if too much scrolled off + your screen. Using tail -f /var/log/messages + in a separate window or screen will give you a continuous update + of what is going on in your system. + + + + You can also take advantage of the /proc + file system that is a window into the inner workings of your + system. Use cat rather than + more to view the files as they are reported as + being zero length. Reports are that less works + well here. + + + + + + + Web Sites + + + disk!information resources!WWW + + + disk!information resources!web pages + + + + There are a huge number of informative web sites available. By + their very nature they change quickly so do not be surprised + if these links become quickly outdated. + + + + A good starting point is of course the + Linux Documentation + Project home page, an information central for + documentation, project pages and much more. + + + + Please let me know if you have any other leads that can be + of interest. + + + + + + + + + + + + Getting Help + + + (your index root)!assistance, obtaining + + + + In the end you might find yourself unable to solve your problems + and need help from someone else. The most efficient way is either + to ask someone local or in your nearest Linux user group, search + the web for the nearest one. + + + + Another possibility is to ask on Usenet News in one of the many, + many newsgroups available. The problem is that these have such a + high volume and noise (called low signal-to-noise ratio) that your + question can easily fall through unanswered. + + + + No matter where you ask it is important to ask well or you will + not be taken seriously. Saying just my disk + does not work is not going to help you and instead the + noise level is increased even further and if you are lucky someone + will ask you to clarify. + + + + Instead describe your problems in some detail that will enable + people to help you. The problem could lie somewhere you did not + expect. Therefore you are advised to list the following information + about your system: + + + + + + + Hardware + + + + + Processor + + + + DMA + + + + IRQ + + + + Chip set (LX, BX etc) + + + + Bus (ISA, VESA, PCI etc) + + + + + Expansion cards used (Disk controllers, video, IO + etc.) + + + + + + + + + + Software + + + + + + BIOS (On motherboard and possibly SCSI host adapters) + + + + LILO, if used + + + + + Linux kernel version as well as possible modifications + and patches + + + + + Kernel parameters, if any + + + + + Software that shows the error (with version number + or date) + + + + + + + + + + + Peripherals + + + + + + + Type of disk drives with manufacturer name, version and type + + + + + Other relevant peripherals + + + + + + + + + + + + Remember that booting text is logged to + /var/log/messages which can answer most of + the questions above. Obviously if the drives fail you might not be + able to get the log saved to disk but you can at least scroll + back up the screen using the SHIFT and + PAGE UP keys. It may also be useful to include + part of this in your request for help but do not go overboard, + keep it brief as a complete log file dumped + to Usenet News is more than a little annoying. + + + + + + + + + + + Concluding Remarks + + + (your index root)!conclusion + + + + Just summing up... Also a place for general + recommendations. + + + + + + + + + + + Questions and Answers + + + (your index root)!FAQ + + + (your index root)!frequently asked questions + + + + Check the newsgroups and try to determine some frequent + problems and cover them here. Again an example from the Multi Disk + HOWTO. + + + + This is just a collection of what I believe are the most common + questions people might have. Give me more feedback and I will turn + this section into a proper FAQ. + + + + + + + Q:How many physical disk drives (spindles) does a Linux system need? + + + + A: Linux can run just fine on one drive (spindle). Having + enough RAM (around 32 MB, and up to 64 MB) to support swapping + is a better price/performance choice than getting a second + disk. (E)IDE disk is usually cheaper (but a little slower) than + SCSI. + + + + + + Q: Are there any disadvantages in this scheme? + + + + A: There is only a minor snag: if even a single partition + overflows the system might stop working properly. The severity + depends of course on what partition is affected. Still this is + not hard to monitor, the command df gives + you a good overview of the situation. Also check the swap + partition(s) using free to make sure you are + not about to run out of virtual memory. + + + + + + Q: OK, so should I split the system into as many partitions as + possible for a single drive? + + + + A: No, there are several disadvantages to that. First of all + maintenance becomes needlessly complex and you gain very little + in this. In fact if your partitions are too big you will seek + across larger areas than needed. This is a balance and + dependent on the number of physical drives you have. + + + + + + + Greg Leblanc: Depending on how big this FAQ gets, perhaps it + would be worthwhile to have, say, the 5 most FAQ, and put the + rest into an external FAQ. Dunno. Comments? + + + (rest deleted.) + + + + + + + + + + + Bits and Pieces + + + disk!miscellaneous + + + + This is basically a section where I stuff all the bits I have not + yet decided where should go, yet that I feel is worth knowing + about. It is a kind of transient area. + + + + + + + + + + + Examples + + + (your index root)!examples + + + + Example designs and sample configuration files and other + relevant details is always handy + + + + + + +
+ +