Developing

So you want to write code in Umlaut gem itself.

First, note that you may not have to for localization. The most common thing you'd want to do is add a new Service Plugin. You can add a new service plugin solely in your local app, and reference it in your umlaut_services.yml. However, if it's possibly useful to someone else, it would be great if you contributed it back to Umlaut, and that would require editing Umlaut source.

Or you may just want to explore the source and maybe even edit it experimentally, that's cool.

(Please note: You can edit Umlaut code to contribute a patch back to Umlaut, or experimentally. But you should not need to run your application live against locally edited Umlaut source code. If you do so, you have locally forked Umlaut, and it will make upgrading to future versions of Umlaut difficult. It should be possible to make any local changes you need with local configuration or over-rides located in your local app. If there's something that needs to be easier... well, that's indeed a reason to fix Umlaut to make it easier and contribute your fix back to Umlaut!)

So ordinarily when you install Umlaut into a local app, the actual Umlaut source is off in your system (or rvm, etc) gem repository, which is not a place you'd want to edit it.

You can use git to check out a copy of Umlaut source wherever you want from your github repo. But Umlaut's a gem, you can't actually run it to test it. How do you run an application against an arbitrary local umlaut version in your file system?

Two ways:

• In any arbitrary umlaut-using local app, you can simply point it to a local checkout of Umlaut in the app's Gemfile, using the :path option. Relative paths are fine.

  gem 'umlaut', :path => '../umlaut'
  

  You wouldn't want to actually deploy or run an app in production like this, it's best to deploy against actual released versions of Umlaut. But for testing and experimentation and development.

• The umlaut source comes with a very basic dummy app in ./test/dummy. There's no database.yml though. Create one, pointing to a local mysql database, run rake db:migrate, and you can just start the dummy app running against the checkout of umlaut in the directory that contains it. Edit the ./config/umlaut_services.yml if you want, etc.

  This dummy app was actually created by the rails plugin new generator for purpose of running automated tests against, see below.

Testing

Release a service plugin in a seperate gem?

Umlaut comes with a bunch of service plugins included.

You/we could instead release one or more service plugins as seperate gems, that depend on Umlaut. A user would need to install the umlaut_crazy_service gem, and then they'd have access to service plugin same as anything else. No special magic, the seperate gem just needs to depend on umlaut in it's gemspec, and include a class defining a service per Umlaut conventions.

Why might you want to do this?

• The service has a lot of dependencies that we don't want core umlaut to need to depend on
• You want to be able to release updates to the service plugin on it's own release schedule, not tied to updates of umlaut.
• You want to control the service yourself and do whatever you want with it, not subject to other umlaut developers ideas. Or you want/need to release it under a different license.

What are the downsides?

• A bit more apparatus to work with as a developer, a bit more confusing as a developer (not so much as a user), a bit more work to make sure the independent gem keeps working with Umlaut as umlaut evolves, keep track of what versions of Umlaut your independent gem works with, etc.

Submitting a change

So you're not an Umlaut committer, but you'd like to submit a change back to Umlaut.

Fork in github, create a new "feature" branch in your forked github, and commit your changes there.

Then submit a github pull request back to Umlaut. See also http://www.mikeball.us/blog/how-to-contribute-to-a-project-hosted-on-github

Small single purpose pull requests are better than massive conglomerations. If you need massive changes, try to break them into steps and submit pull requests for smaller changes at a time.

Please feel free to ask for feedback on the umlaut listserv on your general approach before embarking on a massive change, to make sure you're working in a direction likely to be accepted.

Once you've contributed a quality change or two to Umlaut, odds are we'll make you a committer.

Releasing an Umlaut gem

Generally only done by project lead or what have you. Needs to have permissions set on rubygems for the umlaut gem.

We use the bundler-supplied rake tasks for releasing the gem. Update ./lib/umlaut/version.rb to desired version.

Then simply run: rake release

This will create a tag with version in umlaut git repo, as well as release the new version to rubygems.org.