diff --git a/doc/README_FOR_APP b/doc/README_FOR_APP new file mode 100644 index 0000000..c377fdb --- /dev/null +++ b/doc/README_FOR_APP @@ -0,0 +1,174 @@ += 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 + +contacts is bundled together with noosfero for now, so you don't need to install it. + +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 + +* install memcached. Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. +* 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 rake package. 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 rake db:migrate and rake test. 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 git tag. +* 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 rake clobber_package to +completely delete the generated packages and start the process again. + +== Working with translations + +* Update translation files: rake updatepo. Then git commit 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 git commit. +* test translations: rake makemo and browse the application on the web. diff --git a/doc/README_FOR_APP.en b/doc/README_FOR_APP.en deleted file mode 100644 index c377fdb..0000000 --- a/doc/README_FOR_APP.en +++ /dev/null @@ -1,174 +0,0 @@ -= 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 - -contacts is bundled together with noosfero for now, so you don't need to install it. - -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 - -* install memcached. Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. -* 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 rake package. 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 rake db:migrate and rake test. 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 git tag. -* 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 rake clobber_package to -completely delete the generated packages and start the process again. - -== Working with translations - -* Update translation files: rake updatepo. Then git commit 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 git commit. -* test translations: rake makemo and browse the application on the web. -- libgit2 0.21.2