Bug report: installs as "stable"

[Wincent Colaiuta]

Hi,

I just installed Haml into an existing Rails app for the first time
and I'm looking forward to trying it out.

I wanted to report what looks like a bug in the installation
instructions at <http://haml.hamptoncatlin.com/download/>.
Specifically, they state that you install by doing the following:

script/plugin install http://svn.hamptoncatlin.com/haml/tags/stable

This will check out a copy of Haml into:

vendors/plugins/stable

But it seems to me that a more correct installation path would be:

vendors/plugins/haml

So I installed by doing a manual export like this instead:

svn export http://svn.hamptoncatlin.com/haml/tags/stable vendor/
plugins/haml

So I think the instructions probably need to be updated and possibly
the repository layout as well; the stable version of the plugin should
probably live at:

http://svn.hamptoncatlin.com/haml/branches/stable/haml

And specific releases should probably have paths like:

http://svn.hamptoncatlin.com/haml/tags/rel_1-5-2/haml

Cheers,
Wincent

[Nathan Weizenbaum]

This has been discussed before, but it's really more of a problem with
the Rails installer than Haml... Haml uses a very common repository
structure, but script/plugin doesn't have a way of either detecting this
layout or manually setting the folder name. If we were to change the
repository layout now, it would break existing checkouts, which would be
bad.

That said, it may be a good idea to change the install instructions to
have users use

mv vendor/plugins/{stable,haml}

- Nathan

[Wincent Colaiuta]

On Jun 4, 4:14 pm, Nathan Weizenbaum <nex...@gmail.com> wrote:
> This has been discussed before, but it's really more of a problem with
> the Rails installer than Haml... Haml uses a very common repository
> structure

What other plug-in projects are you aware of that check out as
"stable"? If there are any, it won't be possible to have them
installed along with Haml at the same time. I only have a couple of
plug-ins installed myself, and they install as "rspec" and
"rspec_on_rails" respectively.

> but script/plugin doesn't have a way of either detecting this
> layout or manually setting the folder name.

I found an older article <http://unspace.ca/discover/haml/> that seems
to suggest that it *used* to work that way, but I tried it out and it
doesn't work any more, at least as of Rails 1.2.3.

> If we were to change the
> repository layout now, it would break existing checkouts, which would be
> bad.

If you're worried about breakage then you could hold off until 2.0
before making the change. Or you could just provide clear upgrade
instructions with the version that makes the switch.

In any case if you change from

haml/tags/stable

to:

haml/branches/stable/haml

There won't be any breakage as such, merely that people doing an "svn
up" won't get the new version unless you keep the old URL synchronized
with it as well (which could easily be done but I think that just
documenting the upgrade procedure is a better option).

> That said, it may be a good idea to change the install instructions to
> have users use
>
> mv vendor/plugins/{stable,haml}

Most definitely. Although if you're going to ask users to do a "script/
plugin install" followed by a manual "mv" then you may as well just
advise them to install in one step using "svn" directly... But I think
that reorganizing the repository is still the best way to go.

Cheers,
Wincent

[Nathan Weizenbaum]

Wincent Colaiuta wrote:
> What other plug-in projects are you aware of that check out as
> "stable"? If there are any, it won't be possible to have them
> installed along with Haml at the same time. I only have a couple of
> plug-ins installed myself, and they install as "rspec" and
> "rspec_on_rails" respectively.
>

Most Rails plugins are specifically/only available for Rails, and aren't
large enough to warrant branching/tagging. Thus, they design their
repository structure around Rails. Not so for Haml.

> I found an older article <http://unspace.ca/discover/haml/> that seems
> to suggest that it *used* to work that way, but I tried it out and it
> doesn't work any more, at least as of Rails 1.2.3.
>

Unfortunately, that syntax never worked. It was a weird amalgamation of
"svn co" and "script/plugin" syntax.

> If you're worried about breakage then you could hold off until 2.0
> before making the change. Or you could just provide clear upgrade
> instructions with the version that makes the switch.
>
> In any case if you change from
>
> haml/tags/stable
>
> to:
>
> haml/branches/stable/haml
>
> There won't be any breakage as such, merely that people doing an "svn
> up" won't get the new version unless you keep the old URL synchronized
> with it as well (which could easily be done but I think that just
> documenting the upgrade procedure is a better option).
>

There are a couple issues with that. First, I don't really want to leave
around old, dead repository paths; nor do I want to delete them and
break stuff. Second, it doesn't fix the issue for trunk.

The problem with documentation is that most people who use Haml as a
plugin don't check *anything* relating to it with any sort of
regularity. There's no way we could notify them other than just breaking
their plugin installation.

> Most definitely. Although if you're going to ask users to do a "script/
> plugin install" followed by a manual "mv" then you may as well just
> advise them to install in one step using "svn" directly... But I think
> that reorganizing the repository is still the best way to go.
>
> Cheers,
> Wincent

Actually, if you do use script/plugin with a svn:// URL, Rails is smart
enough to work around this, but that requires that people have
Subversion installed, which isn't the case (as we discovered when we got
bug reports from having a svn:// URL in the download instructions).

- Nathan