Software Público Brasileiro

= Noosfero: a free web-based social platform

== Setting up a Noosfero development/test environment

Noosfero is written in Ruby with the "Rails framework":http://www.rubyonrails.org,
so the process of setting it up is pretty similar to other Rails applications.

=== Requirements

noosfero is intended to be run in Debian stable. It can work in other environments, but we do not test on them.

You need to have git installed, as well as:

* Ruby: http://www.ruby-lang.org/
* Rake: http://rake.rubyforge.org/
* Ruby-GetText: http://www.yotabanana.com/hiki/ruby-gettext.html?ruby-gettext (at least version 1.9.0)
* Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
* rcov: http://eigenclass.org/hiki/rcov
* Ferret: http://ferret.davebalmain.com/trac
* RMagick: http://rmagick.rubyforge.org/
* RedCloth: http://whytheluckystiff.net/ruby/redcloth/
* will_paginate: http://github.com/mislav/will_paginate/wikis
* contacts: http://github.com/cardmagic/contacts/tree/master
* iso-codes: http://pkg-isocodes.alioth.debian.org/
* feedparser: http://packages.debian.org/sid/libfeedparser-ruby
* Mongrel: http://mongrel.rubyforge.org/
* tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library

There are Debian packages available for all of them but contacts. Try:

 # aptitude install subversion ruby rake libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby mongrel mongrel-cluster tango-icon-theme

To install contacts, you need to either use gem (gem install contacts), or you can just download the tarball from github or rubyforge and copy the contents of lib/ under noosfero's lib/ directory.

If you have problems with the setup, use the development mailing list. In
special its possible that the requirements list above is not complete.

=== Setting up a production environment

* copy config/ferret_server.yml.dist to config/ferret_server.yml.dist
* configure the mongrel cluster: `mongrel_rails cluster::configure`
** then edit config/mongrel_cluster.yml to suit your environment. Make sure your apache configuration matches the mongrel cluster configuration, specially in respect to the ports and numbers of mongrel instances.
* create needed temporary directories:
  mkdir tmp
  mkdir tmp/pids
  mkdir log
* create database (example using PostgreSQL, YMMV)

  root user
  =========
  # sudo apt-get install postgresql libpgsql-ruby
  # su - postgres

  postgres user
  =============
  postgres@HOST:~$ createuser noosfero
  Shall the new role be a superuser? (y/n) n
  Shall the new role be allowed to create databases? (y/n) y
  Shall the new role be allowed to create more new roles? (y/n) n

  noosfero_user
  =============
  createdb noosfero_production
  createdb noosfero_development
  createdb noosfero_test

* configure database access in config/database.yml

* test database access:
** first create the development database
   rake db:schema:load  
** if everything goes right, then create the production database:
   RAILS_ENV=production rake db:schema:load

* create sample data:
  RAILS_ENV=production rake db:populate

* compile the translations:
  rake makemo

* start the server:
  ./script/production start

* to stop the server:

  ./script/production stop

* to restart the server:

  ./script/production restart

=== Boostraping a test environment

You can copy and paste the commands below into a terminal (please review the
commands and make sure you understand what you are doing):

 # checkout the code from repository
 git clone git://git.colivre.coop.br/noosfero.git
 # enter the directory
 cd noosfero
 # copy a sample config file
 cp config/database.yml.sqlite3 config/database.yml
 # create the database:
 rake db:migrate      
 # compile translations:
 rake makemo
 # create some test data:
 ./script/populate
 # install the test dependences:
 aptitude install libtidy-ruby libhpricot-ruby libmocha-ruby imagemagick
 # run the automated test suite to make sure your environment is sane:
 rake test

You should now be ready to go. Issue the following command to start the Rails
development server:

 ./script/server

The server will be available at http://localhost:3000/ . If you want to use
another port than 3000, you can use the -p option of ./script/server:

 ./script/server -p 9999

The above command makes the server available at http://localhost:9999/

The populate script creates some test users, one of them has login 'ze' and
password 'test'. You can use it or you can register a new user.

== Reporting bugs

Use Noosfero Tracker application at http://www.colivre.coop.br/Noosfero.

== Helping with development

* It's recommended that you subscribe to the development mailing
  list: http://ynternet.net/mailman/listinfo/noosfero
* If you have a patch, create an appropriate action item
  (bugs/requirement/enhancement) in the Tracker web (see "Reporting bugs"
  above) of type.

== Releasing noosfero

To prepare a release of noosfero, you must follow the steps below:

* finish all requirements and bugs assigned to the to-be-released version
* make sure all tests pass
* write release notes at the version's wiki topic.
* generate package with <tt>rake package</tt>. Your tarball will be under the pkg/
  directory, named as noosfero-${VERSION}.tar.gz
* test that the package contains everything that is needed: explode the tarball
  in a temporary directory, copy config/database.yml.sqlite3 to
  config/database.yml, and make <tt>rake db:migrate</tt> and <tt>rake test</tt>. If
  everything is ok, you are done. If not, maybe some files are not going into
  the tarball. See lib/tasks/package.rake, probably you'll need to change it.
* Go to the version's wiki topic and edit it to reflect the new reality.
* Attach the generated package to that topic. Before attaching calculate the md5 of the package (with mu5sum and paste the MD5 hash as comment in the attachment form)
* Download the attached and verify the MD5 hash
* create a git tag for the released version with <tt>git tag</tt>.
* IMMEDIATELY change the version in lib/noosfero.rb to the next version. (e.g.
  0.2.0 -> 0.3.0)
* update an eventual demonstration version that you run.
* write an announcement e-mail to the relevant maimling lists pointing to the release notes, and maybe to the demonstration version.

If you had any problem during these steps, you can do <tt>rake clobber_package</tt> to
completely delete the generated packages and start the process again.

== Working with translations

* Update translation files: <tt>rake updatepo</tt>. Then <tt>git commit</tt> them.
* Send the PO files to the translators.
* Get the PO files back from translators, put in po/ under the correct language
  name (e.,g. po/pt_BR/) and <tt>git commit</tt>.
* test translations: <tt>rake makemo</tt> and browse the application on the web.