write README, contributing.txt, reorganize the other documentation files

README

@@ -1,32 +1,129 @@
-ns-3 uses the Mercurial software revision control system
 
-Mercurial cheat sheet
+    The Network Simulator Version 3
+    -------------------------------
 
-clone this repository:
+Table of Content:
-----------------------
+-----------------
-hg clone http://code.nsnam.org/ns-3-dev
 
-pull development tree changes to your local repository:
+1) An Open Source project
-------------------------------------------------------
+2) An overview of the ns-3 project
-hg pull http://code.nsnam.org/ns-3-dev
+3) Building ns-3
-hg update (apply the changes)  OR
+4) Running ns-3
-hg merge (if you've made local changes)
+5) Working with the development version of ns-3
 
-commit locally:
---------------
-hg status
-hg add <new files, if any>
-hg ci -m "message"
 
-push upwards (developers access only):
+1) An Open Source project
---------------------------------------
+-------------------------
-hg push ssh://code@code.nsnam.org//home/code/repos/ns-3-dev
 
-view the change log:
+ns-3 is an Open Source project and we intend to make this
---------------
+project a successful collaborative project: we hope that 
-hg log <file>
+the missing pieces of the models we have not yet implemented
+will be contributed by the community in an open collaboration
+process.
 
-doing a scons make clean:
+Contributing to the ns-3 project is still a very informal
-------------------------
+process because that process depends heavily on the personality
-scons -c
+of the people involved, the amount of time they can invest
+and the type of model they want to work on.
 
+Despite this lack of a formal process, there are a number of 
+steps which naturally stem from the open-source roots of the
+project. These steps are described in doc/contributing.txt
+
+2) An overview of the ns-3 project
+----------------------------------
+
+This package contains the latest version of ns-3 which is aims 
+at being a replacement for ns-2. Currently, ns-3 provides a 
+number of very simple network simulation models:
+  - an ipv4 and udp stack
+  - arp support at the bottom of the stack
+  - point-to-point physical-layer links
+  - OnOff traffic generator
+
+However, the framework is there to make adding new models as 
+simple as possible:
+  - an extensive tracing system can be used to connect
+    any number of arbitrary trace sources to any number
+    of trace sinks. This tracing system is decoupled
+    from the act of serializing the trace events to a 
+    file: users can and should provide their own
+    trace handling routines.
+
+  - simple file trace serialization support is included
+    to both text and pcap files.
+
+  - adding new MAC-level models simply requires subclassing
+    the pair of classes NetDevice and Channel.
+
+  - adding new traffic generation algorithms is also very 
+    simple through the Application and the Socket classes.
+
+3) Building ns-3
+----------------
+
+The code for the framework and the default models provided
+by ns-3 is built as a set of libraries. User simulations
+are expected to be written as simple programs which make
+use of these ns-3 libraries.
+
+To build the set of default libraries and the example
+programs included in this package, you need to use the
+tool 'scons'. Detailed information on how to install
+and use scons is included in the file doc/build.txt
+
+However, the real quick and dirty way to get started is to
+type the command "scons" the the directory which contains
+this README file. The files built will be copied in the
+build-dir/dbg-shared/bin and build-dir/dbg-shared/lib
+directories. build-dir/dbg-shared/bin will contain
+one binary for each of the sample code in the 'samples'
+directory and one binary for each of the detailed examples
+found in the 'examples' directory.
+
+The current codebase is expected to build and run on the
+following set of platforms:
+  - linux x86 gcc 4.1, gcc 3.4.
+  - MacOS X ppc and x86
+
+The current codebase is expected to fail to build on
+the following platforms:
+  - gcc 3.3 and earlier
+  - optimized builds on linux x86 gcc 4.0 
+
+Other platforms might or might not work: we welcome 
+patches to improve the portability of the code to these
+other platforms.
+
+4) Running ns-3
+---------------
+
+On Recent Linux systems, once you have built ns-3, it 
+should be easy to run the sample programs with the
+following command:
+
+./build-dir/dbg-shared/bin/simple-p2p
+
+or:
+
+cd build-dir/dbg-shared/bin
+./simple-p2p
+
+That program should generate a simple-p2p.tr text 
+trace file and a set of simple-p2p-xx-xx.pcap binary
+pcap trace files.
+
+5) Working with the development version of ns-3
+-----------------------------------------------
+
+If you want to download and use the development version 
+of ns-3, you need to use the tool 'mercurial'. A quick and
+dirty cheat sheet is included in doc/mercurial.txt but
+reading through the mercurial tutorials included on the
+mercurial website is usually a good idea if you are not
+familiar with it.
+
+If you have successfully installed mercurial, you can get
+a copy of the development version with the following
+command:
+"hg clone http://code.nsnam.org/ns-3-dev"

RELEASE_NOTES

@@ -3,6 +3,18 @@
 
 This file contains ns-3  release notes (most recent releases first).
 
+Release 0.2 (2007/05/XX)
+========================
+
+  - Implement a new memory management infrastructure based
+    on reference counting and smart pointers (the latter being
+    optional)
+
+  - Implement a COM-like framework with support for QueryInterface
+    to provide object extensibility
+
+  - Add support for a BSD-style socket API for user applications
+
 Release 0.1 (2007/03/31)
 ========================
 

doc/contributing.txt

@@ -0,0 +1,53 @@
+
+Contributing to the ns-3 project
+--------------------------------
+
+Despite the lack of a formal contribution process to the ns-3
+project, there are a number of steps which we expect every
+potential contributor to follow. These naturally stem from 
+the open-source roots of the project:
+
+  - first, you should subscribe to the ns-developers 
+    mailing-list (see http://www.nsnam.org/mailing_lists.html)
+
+  - then, you should send an email there stating your interest
+    in working on a specific part of the models and trying
+    to explain how you would like to implement it, what 
+    resources you have, etc.
+
+  - you should be prepared to work together with the other
+    potential contributors who want to work on the same models.
+
+  - you should be prepared to go through code reviews with the
+    ns-3 development team prior to integration. The goal of these
+    code reviews is to:
+      - ensure adherence to the coding style of the project
+        (see doc/codingstyle.html)
+      - ensure that the structure of your code has a certain 
+        coherence with regard to the rest of the ns-3 codebase
+      - improve the quality of the code: we strongly believe in
+        the old saying: "many eyes make all bugs shallow".
+      - increase code reuse by trying to generalize certain 
+        useful pieces of your code to make them available to
+        other models.
+
+  - you should be prepared to try to integrate as many tests
+    in the codebase as possible: we understand that writing
+    tests is not sexy and that not everyone is convinced that
+    they improve the code-writing poductivity which is why
+    we do not enforce strict rules about testing. However,
+    we expect model authors to answer basic questions about
+    how they plan to test and validate their models.
+
+  - you should be prepared to maintain your model once it is
+    integrated: while we consider every bug filed against the 
+    simulator as being a bug we must deal with and while we 
+    will try to fix as many bugs as humanly possible, we
+    also expect model authors to act as responsible maintainers
+    and be reactive to bug reports concerning their models.
+
+  - you should make sure that you understand that contributed
+    models should be licensed under the GPLv2. You do not have
+    to assign your copyright to the ns-3 project but you must
+    accept the terms of the GPLv2. See the following link:
+    http://www.fsf.org/licensing/licenses/info/GPLv2.html

doc/mercurial.txt

@@ -0,0 +1,44 @@
+Introduction
+------------
+
+ns-3 uses the Mercurial software revision control system which
+is a replacement for tools liks cvs or subversion. Thus, to get
+access to the developement versions of ns-3, you need to install
+mercurial first. See http://www.selenic.com/mercurial/wiki/
+
+Mercurial cheat sheet
+---------------------
+
+Look at our project history and source code:
+-------------------------------------------
+http://code.nsnam.org/ns-3-dev
+
+clone this repository:
+---------------------
+hg clone http://code.nsnam.org/ns-3-dev
+
+commit locally:
+--------------
+hg status
+hg add <new files, if any>
+hg ci -m "message"
+
+pull development tree changes to your local repository:
+------------------------------------------------------
+hg ci -m "my local changes are recorded"
+hg pull http://code.nsnam.org/ns-3-dev
+hg update (apply the changes)  OR
+hg merge (if you've made local changes)
+
+view the change log:
+-------------------
+hg log <file>
+
+push upwards (developers access only):
+--------------------------------------
+To the main repository:
+hg push ssh://code@code.nsnam.org/repos/ns-3-dev
+To your private repository:
+hg push ssh://username@code.nsnam.org//home/username/repositories/username/repository
+
+