Contributing to Streamlined

We love it when somebody cares enough about Streamlined to make it better. If you want to contribute to the code base, please follow the instructions below (with thanks to the Instiki team for the writeup).

Steps:

1. Create a Ticket describing the bug or proposed features. Let's say the Trac ticket has ID 12345.

To rely on someone else to (maybe) make the changes, stop here. If instead, you'd like to help us help you, continue with the following steps, to create a patch. This process should be used for code, artwork, stylesheet, and any other changes.

2. Ensure you've got the pre-requisites required to run the Streamlined unit tests. A MySQL instance is required, which we will populate in step 4. (It would be nice if someone could make the tests run using SQLite.) The latest versions of the FlexMock and rcov gems are also required:

$ gem install flexmock
$ gem install rcov

3. Check out the latest sources from the Subversion repository:

$ svn co http://svn.streamlinedframework.org/edge/streamlined/ streamlined
...
Checked out revision 511.
$ cd streamlined

If you want to use this copy of Streamlined in your Rails project, you could link it in with something like this:

$ ln -s /path/to/this_copy_of/streamlined /path/to/rails_project/vendor/plugins/streamlined

Then from within your Rails project, issue this command to copy some files where they need to be:

$ rake streamlined:install_files

4. Configure the database by copying config/database_example.yml to config/database.yml and customizing it for your own environment. Then run:

$ rake test:build_mysql_databases

5. Run the automated tests, to ensure that they're all passing: †

$ rake
...
Finished in 0.907 seconds.
118 tests, 513 assertions, 0 failures, 0 errors

6. Make the changes you want. Be sure to follow coding conventions that you spot, and add/update unit/functional tests for any code you add, or your patch will likely not be accepted.

7. Run the automated tests again.

$ rake
Finished in 0.929 seconds.

119 tests, 516 assertions, 0 failures, 0 errors

8. Create a patch:

svn diff > patch.12345.diff

Please follow this naming convention for your patches:

patch.12345.diff - first patch for the ticket #12345
patch.12345.diff.2 - second patch (maybe first failed)
patch.12345.diff.3 - third... (it better stop here!)

NOTE: I found that removing the first 2 lines of the patch will allow Trac to display the diff if only 1 file was changed. However, the patches uploaded by the developers seem to keep the first 2 lines. I believe the patch program will work either way.

9. Upload the patch to the corresponding ticket.

10. Add the prefix [PATCH] to the ticket title, to make it show up in the patches report.

That's all!

† It is important to make sure the copy of Streamlined you pull out from the repository actually passes all of its tests without any of your changes. This will prevent you from spending endless hours of trying to find where that bug is in your code if it really isn't in your code. As of 2007-06-10, you'll need to apply the patch from Bug #52 in order to pass all the tests. As of 2007-06-20, you'll need to apply a similar patch to author_ui.rb.