Technical Documentation - Pistos/diaspora GitHub Wiki

This documentation is for developers and podmins. It describes how to make your pod use my fork, and also how to contribute to my fork. Recently added: API documentation.

Using the diaspora-pistos release series

Knowledge Prerequisites

It's probably not safe for you to use my branch if you aren't comfortable with the following things. You should:

  • know how to switch between git branches (such as to switch back to a previously used branch if something goes wrong)
  • know what webserver you're using (thin, unicorn, mongrel, etc.)
  • know how to restart your webserver process(es)

First-time actions

The first time you do this, you should:

  1. Make a backup of your database.
  2. git remote add Pistos git://github.com/Pistos/diaspora.git

If you do not have an existing pod, and are starting from scratch, it is strongly recommended that you use PostgreSQL as your RDBMS, not MySQL. This is for future compatibility reasons (I may stop supporting MySQL).

Upgrading

Every time you want to update to a newer version of diaspora-pistos:

  1. Make a backup of your database.
  2. Ensure your production checkout is clean (no modified files shown in git status), unless you know what you're doing.
  3. Freshen up from my fork: git fetch Pistos
  4. Get the latest version of the branch series. For example, for version 1.0.7: git checkout -t Pistos/diaspora-pistos-1.0.7
  5. Update all gems if the Gemfile has changed: bundle update (safe to run every time)
  6. If there are new migrations: bundle exec rake db:migrate (safe to run every time if you're not sure)
  7. Restart your webserver process(es). That means your thins, unicorns, mongrels, whatever you're using.
  8. Restart your Resque workers if there have been changes to Resque job code (it's safe to restart every time if you're not sure).
  9. Restart your websocket_server.rb if there have been changes to socket code (it's safe to restart every time if you're not sure).
  10. Update your config/application.yml if needed or desired. Changes in configuration options will be described in the release announcement. To see differences for yourself, run: gitdiff diaspora-pistos-1.0.1:config/application.yml.example diaspora-pistos-1.0.2:config/application.yml.example using the two version numbers you want to compare.
  11. If there have been CSS or Javascript changes: bundle exec jammit (safe to run every time if you're not sure)

I make release announcements for the diaspora-pistos branch on Diaspora using the #diasporapistos hashtag, so you can follow that if you want to stay up-to-date. My own pod is more cutting-edge, and I release features there before I incorporate them into diaspora-pistos-*, so you can follow the #diasp0raca hashtag if you want to know ahead of time what will soon trickle down to diaspora-pistos.

Developing off Pistos/diaspora

If you're going to work on topic branches and issue pull requests against this fork (instead of the fork of Diaspora Inc.), please create your branches off the stable branch, not off the master branch. master is used to follow upstream (diaspora/diaspora) development.