% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
% This file is part of SableVM.                             %
% See the file "LICENSE" for Copyright information and the  %
% terms and conditions for copying, distribution and        %
% modification of SableVM.                                  %
% % % % % % % % % % % % % % % % % % % % % % % % % % % % % % %
\documentclass[12pt]{article}
\usepackage{amsmath}

\title{Hacking SableVM}
\author{The SableVM Development Team}
\date{February 3rd 2004}

\begin{document}

\section{Introduction}
\label{sec:introduction}

This document should help you get started with SableVM.  It is a work
in progress.  It is maintained in LaTeX so that you can print it and
have something nice to read.

\section{Contributions to SableVM}
\label{sec:contributions}

Before you are granted write access to the SableVM Subversion
repository at {\tt svn.sablevm.org}, you must ensure that:

\begin{enumerate}
\item You have maintained a "clean-room" status with respect to all
  code possibly related to SableVM.  You should not have had access to
  confidential material under license terms that precludes
  contributing to the development of SableVM.  Having signed the Sun
  community source license or any similar non-disclusure agreement,
  for example, would be such a situation
  
\item You ARE the copyright holder of the code you contribute.  Your
  university or your employer (if you have one) might be the real
  copyright holder, if you are paid to do the work or if your
  university got you to sign a document accepting a school policy that
  all student programs are the property of the university.  It has
  been shown that the current McGill University policy is OK.
  
  In fact, we are a little more permissive, but on a case by case
  basis.  Usually, no code that is not written by the contributor
  himself should be added to the repository.
    
\item You confirm that you either:

  \begin{description}
  \item[(a)] license all of the work (programs AND texts) you write
    and commit into the the repository under the LGPL, or
    
  \item[(b)] release them into the public domain.
  \end{description}
  
  Copyright assignment from a contributor, while welcome, will never
  be asked for.  A consequence of this policy is that the
  contributor remains the copyright holder on the code he *himself*
  writes, and can thus license it to other parties (off the svn
  repository) under any other license (Free or proprietary).
  
\item Papers, reports, and theses do NOT go into your sandbox.
  Mainly, your sandbox is a *public* accessible place, with LGPL (or
  public domain) stuff in it.  You are *not* allowed to put any junk
  or irrelevant stuff into it.  No binaries!  However, documents
  like this one and "technical notes" that serve as project
  documentation should be licensed under the LGPL and put in your
  sandbox, so that they can be modified to reflect changes as the
  project matures.
  
\item You give the SableVM Project the right to make little license
  changes and clarifications in the future, if it becomes critical
  for the project.  This is quite unlikely, as the LGPL does achieve
  quite well the objectives of the SableVM Project to:
  
  \begin{description}
  \item[(a)] make sure the source code of *our* work is always
    distributed with derivative works, and
    
  \item[(b)] allow for non-Free derivative works.
  \end{description}
  
\item You agree to these terms for ALL projects you work on in the
  repository, whether they are part of the main SableVM tree or just a
  directory in your sandbox.  There are exceptions to this, but they
  are granted on a case by case basis, and only if there is a good
  motivation for it.  If you do not wish to work under these terms,
  there is no obligation for you to use the repository.

\end{enumerate}

\section{Using the Subversion (svn) Repository}

To get access to the repository, you need to send Etienne Gagnon an
email at {\tt gagnon.etienne $\_$ m@uqam.ca} that:

\begin{enumerate}
\item describes what you want to do in your project

\item indicates acceptance of the developer agreement in the previous
  section
  
\item contains a public DSA ssh 2 key
  
\item your preferred choice of username
\end{enumerate}

If you do not have an appropriate public key, type:
\begin{verbatim}
$ ssh-keygen -t dsa
\end{verbatim}

which will create two files:

\begin{verbatim}
  ~/.ssh/id_dsa:     your *private* key (NEVER share this)
  ~/.ssh/id_dsa.pub: your *public* key (send this to Etienne)
\end{verbatim}

If you need more info,

\begin{verbatim}
$ man ssh
\end{verbatim}

and

\begin{verbatim}
$ man ssh-keygen
\end{verbatim}

will tell you more about ssh.  While you are waiting for repository
access, you can start reading the svn book at:

\begin{verbatim}
http://svnbook.red-bean.com/book.html
\end{verbatim}

You should read ALL chapters, including those that pertain to
branching and merging, but you can skip the sections that are
specifically for repository administrators.  Your sandbox is at:

\begin{verbatim}
svn+ssh://svn.sablevm.org/public/developers/$NAME/sandbox
\end{verbatim}

and your personal tags are at:

\begin{verbatim}
svn+ssh://svn.sablevm.org/public/developers/$NAME/tags
\end{verbatim}

If you need help with anything, stop by {\tt \#sablevm} on {\tt
  irc.freenode.net} using any IRC client (Mozilla ships with
Chatzilla, XChat is available for multiple platforms as well, and you
have ircll for the commandline in *nix systems).  In the next section
we will describe our branch management policies and the layout of the
svn repository.

\section{Branch Management}

\begin{enumerate}
\item {\tt /public/developers/\$NAME/sandbox} Your sandbox is your
  personal development directory.  When you start a new project,
  create a branch of either a stable trunk tag or an experimental
  release (described below) using "svn cp".  You are free to develop
  as you wish in your sandbox, provided you follow the terms of being
  a SableVM developer outlined above.  All code in your sandbox is
  *public*.
  
\item {\tt /public/developers/\$NAME/tags} This is where you make
  snapshots or tags of your sandbox work, either for immediate release
  for testing purposes, or for integration into staging, or for
  whatever good reason you have to make a public snapshot.  Again, you
  are free to create tags as you wish -- branching and tagging are
  very cheap in Subversion.
  
\item {\tt /sablevm/tag/sablevm-X.even.Z} These are tags of {\tt
    /sablevm/trunk}, and are the official *stable* public releases.
  We follow an even/odd numbering system for stable and experimental
  releases respectively.

Etienne Gagnon (egagnon) makes tags.  Trunk tags evolve as follows:

\begin{description}
\item[(a)] {\tt X.even.0} is made by bringing a snapshot of bugfree
  (which adds useful new functionality for users) into the trunk.
        
\item[(b)] {\tt X.even.Z (Z=1,2,3,...)} are critical bug fixes
  releases.
        
\item[(c)] {\tt X} is changed on major milestones.
\end{description}

\item {\tt /sablevm/trunk} The main development trunk of SableVM, and
  it is always utterly stable.  Not every commit necessarily leads to
  a new tag, but it should always be in a state such that it *could*
  be tagged and released as is.
  
  Unlike many multi-author projects, commits to {\tt /sablevm/trunk} are
  reviewed and made exclusively by egagnon, the project leader.
  
  Commits do not preserve svn log history from sandboxes, staging, or
  bugfree.  This is so that we can automatically generate a ChangeLog
  that contains information USERS need to know about bugfixes and
  added features.  While this leads to what appears to be "lost" log
  information, there are three reasons why it is still acceptable for
  developers:

  \begin{description}
  
  \item[(a)] Commits to the trunk are utterly stable, and therefore it
    is highly unlikely that tracing a bug back through commit logs for
    trunk files will be necessary.
    
  \item[(b)] If developers *really* need this information for some
    reason, they can always dig back into the staging branches to find
    it.
    
  \item[(c)] Finally, nothing stops developers from keeping separate,
    more verbose files in their sandbox describing changes.
  \end{description}
  
\item {\tt /sablevm/tag/sablevm-X.odd.Z} These are tags of {\tt
    /sablevm/branches/bugfree}, and are the official *experimental*
  public releases.
  
  {\tt egagnon} and specially-authorized developers (not just "power
  developers") make tags.  Bugfree tags evolve as follows:

  \begin{description}
  \item[(a)] The bugfree branch is always created as a branch of the
    highest stable {\tt X.even.0} trunk state, and refreshed whenever
    a new {\tt X.even.0} release is made.
    
  \item[(b)] {\tt X.odd.Z (Z=0,1,2,3)} are made whenever power
    developers think it is worth making some new code available to
    users as a release.
  \end{description}
    
  Despite its public "experimental" name, a bugfree release is
  supposed to be as stable as a "stable" release.  The only real
  difference is that code does not have to pass through the egagnon
  review bottleneck.
  
\item {\tt /sablevm/branches/bugfree} Also utterly stable.  Only
  commit things that are READY to be added to trunk, but that are not
  critical to be added this instant. If you have doubts, ask/explain
  on the sablevm-developer list or in {\tt \#sablevm} on IRC before
  committing (always good).
  
  Commits to bugfree are directly made by sablevm "power developers".
  They are not reviewed by {\tt egagnon}, and are made using {\tt svn
    merge} to integrate sandbox changes (and thus preserve sandbox
  history).  A power developer NEVER directly develops in a {\tt "svn
    co .../bugfree"} working copy, except in exceptional situations,
  such as quick fixes to critical bugs.  Failure to follow this rule
  (which can easily be verified using {\tt "svn log"} to look for
  sandbox history on bugfree snapshots) WILL lead to demotion off the
  power developer list.
  
  In the event of competing {\tt "svn ci"} commands, one developer
  will succeed, the other will be told by svn to first {\tt "svn
    update"} his working copy.  The second developer will thus have
  more work to do, as he is reponsible to make sure his stuff still
  works with the newer bugfree code.
  
  If a problem is found, it must be fixed ASAP, by either reverting to
  a pre-commit state or by applying the appropriate fix.  A commit may
  be rolled back because of unclean code or poor programming
  practices.  In such cases, an email should be sent to the
  sablevm-developer list explaining the problem so that everyone can
  learn.
  
  In theory, egagnon should be able to take a snapshot of bugfree at
  any point and make it into a new *stable* release, if he feels like
  it.  In practice he will probably take an experimental tag that has
  tested well for a few weeks, but this is NO REASON to commit
  unstable things to bugfree.
  
  Bugfree is really there so that {\tt egagnon}'s busy schedule does
  not halt public releases of stable code (because of lack of time to
  review changes).  It is not meant for day-to-day commit of
  non-prime-time code, which typically breaks everybody else's work.
  Everyday development should happen within your sandbox (which could
  be an "svn cp" of bugfree).  If a more casual shared writing area is
  needed (to collectively work on a not yet prime-time JIT, for
  example), we could add other branches.

\item {\tt /sablevm/branches/frozen}
  
  {\tt X.even.0} releases are based on a previous {\tt X.odd.Z}
  release that is seen as a good candidate for migration to trunk.
  When such a version is identified, and *if* the team feels it still
  needs additional testing just to make sure (even though it is
  already very stable code), a {\tt /sablevm/branches/frozen} branch
  is created.  Tags on this branch are called {\tt X.even-beta.V} where
  {\tt V=0,1,2,...}
  
  Freezing is optional, and DOES NOT affect the ability to continue
  adding to bugfree, nor the creation of new {\tt X.odd.Z++} releases.
  
  It is only when {\tt X.even.0} is created that bugfree is re-created
  appropriately to be based on the new trunk head and any addition to
  bugfree between freeze and stable release is foward-applied to to
  the re-created bugfree branch.
  
  As for a temporary freeze for "experimental" releases, there is no
  reason for it, as the code should have been tested internally
  (within the development team) before being added to bugfree.
 
\item {\tt /sablevm/branches/staging} Staging is a real ``developers
  merging branch''.  This has the same definition to bugfree, except
  that it doesn't have to be in a {\it releasable} state all the time.
  All other restrictions apply, common sense applies too.
  
  For example, if a bug is found in staging, where the code naturally
  gets wider testing (amongst developers, if no-one else), the
  developer should make all efforts to fix the bug as soon as
  possible, but it is not critical to do so in the same way that a bug
  in bugfree is critical.  Nevertheless, all of the responsible
  developer's changes should be reverted if the bug is not fixed in
  reasonably short time.
  
  All things getting to {\tt bugfree} have to go thru {\tt staging},
  with the exception of trivial but critical fixes when we don't want
  to revert whole pile of changes made to {\tt bugfree} just because
  of a missing semicolon or something.
  
  So, in general, the code flow is as follows:
  
  $sandbox~\longrightarrow~staging~\longrightarrow~bugfree~
  \longrightarrow~trunk$
  
  Ordinary developers that wish to add code to {\tt staging} prepare a
  private tag and communicate it to a power developer.  The power
  developer reviews the changes and if they are acceptable (i.e.
  apparently STABLE), uses {\tt svn merge} to incorporate the changes
  (preserving sandbox history).  Grzegorz Prokopski ({\tt gadek}) is a
  permanent power developer, and will be able to let you know who the
  other power developers are if need be.
\end{enumerate}

\section{Coding Style}
\label{sec:coding}

\begin{enumerate}
\item Change calls to {\tt $\_$svmf$\_$printf()} to use {\tt stderr} instead
of {stdout}.  This means unbuffered output in the event of a segfault,
so you should get more.  It also lets you differentiate between
application output and debugging output.  There is a call to {\tt
  fflush()} in {\tt $\_$svmf$\_$printf()} if debugging is enabled.

\item On a similar note, when you notice it, put the {\tt
    env->thread.id} at the beginning of {\tt $\_$svmf$\_$printf()} output,
  as in:

\begin{verbatim}
$\_$svmf$\_$printf(env, stderr, "T%d: ...", env->thread.id).  
\end{verbatim}
  
  This is almost essential debugging multithreading problems.
  
\item Avoid calls to {\tt printf()}, use {\tt $\_$svmf$\_$printf()} whenever
  possible.
  
\item When you make comments, mark them with your full initials.  If
  you notice them, do the same for other authors (e.g. Greg (GBP),
  David (DPB), Etienne (EMG, and Chris (CJFP)).  It helps tremendously
  to know who made a comment.  If you make a comment amending an
  existing comment, differentiate between your text and the text of
  the previous comment (possible by adding that commenter's initials).
  
\item {\tt s/if(cond)/if(cond == JNI$\_$TRUE)/}, and also use {\tt
    JNI$\_$FALSE} and {\tt JNI$\_$TRUE} for boolean values instead of 0 and
  1, in all cases.
 
\item Return {\tt JNI$\_$ERR} or {\tt JNI$\_$OK} and not -1, 0, or 1 from a
  function.
  
\item Always make {}'s explicit, e.g.

\begin{verbatim}
  if (cond)
    m1();
  else
    m2();

 ----------->
   
  if (cond)
    {
      m1();
    }
  else
    {
      m2();
    }
\end{verbatim}
  
\item Avoid global variables.  SableVM is intended for use as a
  library as well as a stand-alone application.
  
\item No constant array sizes.  This is a critical bug, and all
  constants should go in sablevm/src/libsablevm/constants.h
  
\item Use assertions to state assumptions.  These are only turned on
  in debugging mode, so don't worry about them slowing down your code.
\end{enumerate}

In general, as with any software project, try to program in a style
that is consistent with the rest of SableVM.

\end{document}
