Read Me

0. In this document
===============================================================================
  1. Subversion structure
  2. The rules of the SVN club
  3. How to checkout the latest trunk/ of development?
  4. How to develop a disruptive piece of functionality?
  5. How to creat a patch to close a Bug ticket in SourceForge
  6. How to upgrade to Rails X.Y.Z
  7. References


1. Subversion structure
===============================================================================

Welcome to the dradis SVN repository, these are the modules:

client/
  dradis client, all files and libraries needed to run the console and 
wxWidgets interfaces

installer/
  Configuration files for the windows NSIS installer

launcher/
  The launcher is a small app that is meant to ease the process of 
launching dradis components (server & client)

server/
  The Rails application that is the backend of the dradis framework. This 
app stores its information in a sqlite3 db.

meta/
  Contains *meta* files that don't fit in any of the other modules. These are
usually files that are included in the released packages but that for their 
very nature are not tied to client/ or server/. For instace: LICENSE, 
RELEASE_NOTES, etc.


2. The rules of the SVN club:
===============================================================================
We try to follow a Branch-When-Needed system as described in [i]. In a 
nutshell:

    * Users commit their day-to-day work on /trunk.
    * Rule #1: /trunk must compile and pass regression tests at all times. 
      Committers who violate this rule are publically humiliated.
    * Rule #2: a single commit (changeset) must not be so large so as to 
      discourage peer-review.
    * Rule #3: if rules #1 and #2 come into conflict (i.e. it's impossible to 
      make a series of small commits without disrupting the trunk), then the 
      user should create a branch and commit a series of smaller changesets 
      there. This allows peer-review without disrupting the stability of /trunk.

2.1 How to create a new release

Is explained in a separate file HOWTO.release. Find the latest copy at [ii].


3. How to checkout the latest trunk/ of development?
===============================================================================
  $ mkdir dradis-trunk
  $ cd dradis-trunk/
  $ svn co https://dradis.svn.sourceforge.net/svnroot/dradis/server/trunk server
  $ cd server/
  $ thor dradis:reset 

4. How to develop a disruptive piece of functionality?
===============================================================================
As described above, when there is some specially disrupting piece of 
functionality that needs to be coded / refactored the recommended approach is
to branch out, make the changes in the branch (commiting as often as usual) and
then merge back to the trunk/

$ svn cp trunk/ branches/experimental/YYYY-MM_<description_of_changes>-<author>
$ svn commit -m 'Add a experimental branch to refactor <descr.>'
# note the revision number, it will be what we call X
$ ... # commit, commit, commit
# note the last revision commited to the branch, we will call it Y
$ svn merge -r X:Y branches/experimental/2009-06_refactorWordExport-etd/ trunk/
$ svn commit -m 'Merging back the branch created for <description>, from 
revisions X through Y.'

For example, on July 2009 we did:
$ svn cp trunk/ branches/experimental/2009-06_refactorWordExport-etd/
$ ... # commit, commit, commit
$ svn merge -r 1198:1206 branches/experimental/2009-06_refactorWordExport-etd/ trunk/
$ svn commit -m 'Merging back the branch created for <description>, from 
revisions X through Y.'

5. How to creat a patch to close a Bug ticket in SourceForge
===============================================================================
0.- Note the Bug ticket ID

1.- Make sure you start with the latest version of the code:
$ svn update

2.- Patch the issue

3.- After identifying the solution and fixing the code, create a patch file. Go
to the top level folder of the relevant module and:

$ svn diff > ~/fix_<bugID>.diff

4.- Upload the patch to SourceForge. Explain the cause/source of the problem 
and the mitigation before closing the ticket. Provide a brief description of 
what the patch does in the file's description field.

5.- Commit your fixes to subversion

6.- Update the CHANGELOG file of the module to include this bug ID in the list
of fixes.


6. How to upgrade to Rails X.Y.Z
===============================================================================
0.- Install the latest Rails gem

# gem install rails --no-ri --no-rdoc

1.- Create a new experimental branch (see Section 4 of this document)

2.- Unfreeze the gems and delete the vendor/rails/ folder:
$ rake rails:unfreeze
$ svn del vendor/rails/
$ svn commit -m 'Remove the old Rails A.B.C directory'

3.- Update the application

$ rake rails:update
$ svn commit -m 'Update the application after running: rake rails:update'

4.- Freeze the new gems:

$ rake rails:freeze:gems
$ svn commit -m 'Add the new Rails gems for version X.Y.Z'

5.- Ensure that the default port and bind address are 127.0.0.1:3004. Check 
vendor/rails/railties/lib/commands/server.rb:15. Update the default 
configuration setting, the inline help message and the default banner (https)

$ svn commit vendor/rails/railties/lib/commands/server.rb -m 'Ensure that by \
default we bind to the local loopback and port 3004'

6.- Ensure that Webrick starts in SSL mode. Remember to "require 'webrick/https' 
and pass the relevant options (vendor/rails/railties/lib/commands/server.rb:16):

options = {
  #...
  # Options for WEBrick SSL
  :SSLEnable => true,
  :SSLVerifyClient => OpenSSL::SSL::VERIFY_NONE,
  :SSLCertificate => OpenSSL::X509::Certificate.new(File.open('config/ssl/server.crt').read),
  :SSLPrivateKey => OpenSSL::PKey::RSA.new(File.open('config/ssl/server.key.insecure').read),
  :SSLCertName => [
    [ 'CN', 'dradis.' + WEBrick::Utils::getservername ]
    #[ 'O', 'dradis framework [dradis.sourceforge.net]'],
    #[ 'OU', 'dradis server' ]
  ],
  #...
}

$ svn commit vendor/rails/ -m 'Ensure that webrick starts in SSL mode'


7.- Ensure that Webrick starts even if Mongrel is istalled
vendor/rails/railties/lib/commands/server.rb:45

$ svn commit vendor/rails -m 'Ensure that WEBrick starts even if Mongrel is available'

8.- Exclude the templates/ folder of the different generators from the RDoc 
tasks at lib/tasks/documentation.rake:12
rdoc.rdoc_files.exclude('lib/generators/**/templates/')

$ svn commit vendor/rails/railties/lib/tasks/documentation.rake -m 'Exclude the \
templates/ folder of our plugin generators from the Rdoc documentation'

9.- Review config/environment.rb and match it against a fresh copy (generated 
using "rails foobar"). Consider updating the file

10.- Keep an eye on the contents of config/initializers/ or other folders in config/

11.- Update verify.sh to ensure that any new dependencies are checked for


7. References
===============================================================================
 [i] http://svn.collab.net/repos/svn/trunk/doc/user/svn-best-practices.html
[ii] http://dradis.svn.sourceforge.net/viewvc/dradis/HOWTO.release