README

 
#
# Scale Stack
#
# Copyright 2010 Eric Day
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

Welcome!
--------

If you're reading this you probably have some idea what this project
is all about, but if not, check out http://scalestack.org/ for more
details. The website covers motivation and design principals for the
project, as well as more detailed use cases and application-specific
documentation. This document focuses on the basics of getting started
and how to contribute to the project. If you simply want to use the
software from a tarball distribution, getting started is as simple as:

./configure
make
make install

If you checked this out from Launchpad, you'll want to run the
following command before the commands above.

./config/autorun.sh


Resources
---------

Website: http://scalestack.org/
Project: https://launchpad.net/scalestack
IRC: #scalestack on irc.freenode.net
Mailing list: https://launchpad.net/~scalestack


Contributing
------------

All code is licensed under the Apache 2.0 license, and all
contributions will be taken under that license as well. Other licenses
may be considered for self-contained modules. No copyright assignment
is needed, you (or your employer) own your work. :)

To get started fixing bugs, improving existing modules, or adding
new modules, you'll want to register an account with Launchpad and
check out the source. This also requires having the Bazaar VCS (bzr)
installed. See https://help.launchpad.net/ for more details on the
Launchpad development process, but here is a crash-course. Once you
have an account and have setup your SSH key, tell bzr about it. This
only needs to be run once:

bzr lp-login johndoe
bzr whoami "John Doe "

To create a local repository and check out the trunk, run:

bzr init-repo scalestack
cd scalestack
bzr branch lp:scalestack

You now have a shared repository and the trunk. You generally never
want to make changes to trunk directly, so to start making changes,
create a branch:

bzr branch scalestack my-changes
cd my-changes

This will create another branch, my-changes, in the shared repository
directory. Make your changes there and commit them (remember to add
any new files). Once you think you have something ready to share, push
your branch back up to Launchpad (which requires a Launchpad account).

bzr add new_module
bzr commit -m "Comment describing my changes."
bzr push lp:~johndoe/scalestack/my-changes

You can then propose your branch for merging into trunk on the
Launchpad project page. This can be done on your branch page which
you can find linked from:

https://code.launchpad.net/scalestack

If you would like to add new modules, please do so in the scalestack
directory. The C++ namespace is directly translated to path names
there, so you'll find all code in that directory. Look around at the
other modules for examples on how to do so, but the minimum needed
is a plugin.ini and .cc file. Reading the documentation
in scalestack/kernel/module.h may be helpful as well.


Coding Style Guidelines
-----------------------

For the sake of brevity, the guidelines will follow the Google style
except for where it is immediately obvious in the code and the cases
mentioned below:

http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml

Exceptions to this guide include:

- Comments should follow Doxygen style formatting. See existing code
  for examples.

- Opening curly braces should appear on their own line.

- C++ exceptions are allowed if they derive from std::exception. Most
  exception throwing is hidden behind log_fatal messages, which throw
  scalestack::kernel::exception and contains custom messages. Use of
  this through module.log_fatal() in modules is preferred.

- All namespaces, classes, methods, and data members must be all
  lowercase and use '_' to separate words (like the C++ STL).

- Private method names should start with an underscore.

- Data members should always be private and start with an underscore.
  The leading underscores help to easily differentiate the class
  members from local method variables. Some data members may be under
  the protected section so derived classes can also access them.

- Header files should be ordered by system and then Scale Stack
  headers, with a empty line in between. Each set should be ordered
  alphabetically as well. The "config.h" include must be the first
  include for every non-header file, and should NEVER appear in any
  header files.

- You should only use 'using namespace ...;' in source files, never in
  header files. In source files, only specify 'using namespace std;'
  and 'using namespace scalestack;'. Beyond that, please write out
  the full namespace for objects.

- In general, do the most consistent thing given the existing code
  base. If something is not immediately obvious, is ambiguous, or
  if you feel is wrong, please bring it up on the mailing list or in
  IRC so we can clarify it and improve this document. :)