Add-on workflow question

I’m trying to figure out the best way to work on various add-ons via the SVN repository at http://svn.modxcms.com/svn/modx-components. I figured I’d expose my ignorance here so others can be helped by the answers.

If I check out the add-on files into an existing MODx install, the support files for the add-on won’t be where I need them to be for the add-on to function.

All I can come up with is to check them out to an arbitrary directory (let’s call it "work") inside the MODx install, do a build, and then install the package in the manager.

After working on the add-on, I’d then transfer the changes manually to the components in the "work" directory and commit. Then I’d need to do a build, copy the zip file, do another install (overwriting my work -- possibly with errors) in order to make sure the new version is safe to distribute.

Since the MODx install is tied to a different repository, I’d need to do an SVN switch to the component repository before I commit or do a diff. Then, if I forget to "switch" back, my updates, commits, and diffs on the rest of the MODx install will go haywire.

I can keep the "work" directory outside the MODx install and solve some of these problems but it’s less convenient to transfer the changes. I can do the test install to a different MODx implementation but that’s less convenient too.

Is there a better way to do all this?

Also, I don’t understand how the changes get from the add-on repository to the package zip file in the WTF.

Quote from: BobRay at Sep 24, 2008, 05:30 PM

I’m trying to figure out the best way to work on various add-ons via the SVN repository at http://svn.modxcms.com/svn/modx-components. I figured I’d expose my ignorance here so others can be helped by the answers.
...

Is there a better way to do all this?

Well, here’s how I do it.  I try to keep this simple, but it’s hard to communicate all the details sometimes.  This is with the assumption that I’ve built something to a point where I’m ready to commit it as a project in modx-components.

First, I have the modx-components project checked out in a separate directory from any Revolution checkout.  This way I can quickly have access to the source projects and build scripts for each component.  So step one is to branch the component-template/ to create your own component at the same level as component-template/.  This will setup your branches/tags/trunk structure complete with a _build directory, sample transport build script, and even an example structure for including lexicons.

Second, and most importantly, is the build.config.php (which you can copy from other projects you are working on).  Since the build script needs a MODx core workspace to get access to the modX and the modTransportBuilder framework, as well as the packages directory to compile it in, your build script should simply use your local build.config.php to point you at the core you want to work with.  Notice that this build.config.php is in the svn:ignore properties of the _build directory so you aren’t inclined to add/commit this file (another reason to always branch from the component-template/.

At this point building the package, installing, uninstalling, upgrading, etc. can be easily tested in your target install by building the package and performing those tasks inside your target MODx installation.  If I have to fix something, I simply change it, test it, and then replicate whatever that change was back in my working copy under modx-components.


Quote from: BobRay at Sep 24, 2008, 05:30 PM

Also, I don’t understand how the changes get from the add-on repository to the package zip file in the WTF.

This is being developed as part of the new component package repository called ReleaseMe.  The WTF site will go away, and wtf.modxcms.com will become the web service that provides transport packages from the new ReleaseMe repository that will be featured on the main modxcms.com domain.

And if you really want to "check it out" directly into your MODx working copy during part of the workflow, use svn:externals to include and work on the parts you need without messing up your MODx working copy.  You can see how parts of xPDO itself are included into the MODx core/ directory (as well as core/docs/tutorials/) in this manner.

I take a slightly different approach - I have it setup so I can work and run straight out of the files in the modx-components svn checkout i have, which is separate from the core.

I create a central class for handling my component, which then has a $this->config array of options within it, which I can store paths into. For example, in ReleaseMe (the repository manager that Jason was talking about), I have a ReleaseMe class that I instantiate when I start the component. In that component, I have these lines at the beginning of the initialize() function, which is called right after instantiating the ReleaseMe object:



This references the function ReleaseMe->checkDev(), which looks like this:



Note that I’ve already defined RM_BASE_PATH elsewhere, usually at the beginning of the file that is first loaded in the component.
Note also that this references the build config script...but first checks to see if it’s there, so that it wont fail after you’ve built the package, and that once you’ve built the package, the file wont be there - and that means that the script will run normally.
So, let’s look at my build config script, as I’ve made some changes:



Note the if statement. This prevents double-defining, since MODx has already defined those defines in the case of running this script with Dev Mode on. Below it is crucial - I’ve defined a specific-to-this-component URL define. I’ll use this define to run ReleaseMe from the modx-components URL rather than the MODx Revolution URL.

I’ll later use RM_BASE_URL to reference any absolute URLs that I need, should that case arise (javascripts, css files, images, etc).

So basically, with a simple few lines of code (which I can easily take out when I’m ready to finalize the package and release it!) I’ve created a full-fledged dev mode for my package, that’s straight in SVN - with no need to double-copy files once I’m ready to commit changes!

@OpenGeek

That’s really helpful. Thanks. 

If I’m understanding you, you don’t duplicate the config file but just reference the one in the MODx _build dir. in the build script?

I can see where using svn:externals could get me into trouble, so it sounds like your first scenario makes the most sense (especially in Revolution where the checked out add-on won’t actually function).

I’m still a little hazy on maintaining both Evolution and Revolution add-on versions. Looking at the add-on repo, it looks like each version is in a separate branch.  What, then, is in the trunk? It seems to me that it would make more sense to have a separate directory in the repository (complete with trunk, tags, and branches) for the Evolution and Revolution versions (e.g. Ditto-Evolution & Ditto-Revolution) so I’m probably missing something. The current system makes it inefficient to set tags and I see that most, if not all, tags directories are empty. It also makes it harder to retrieve earlier releases of add-ons by name, which would be easy with tags.

@splittingred

That looks very slick.

If I’m getting it, the support files are installed with the package in the MODx installation but aren’t actually used by the add-on which pulls them from comp-repo.

And you have to be really careful not to accidentally include build.config.php in the package (which I guess you’d do anyway).

I’m still confused on one point. The add-on runs from comp-repo until it’s built and installed, but how can it run without being built and installed first? Do you install it and then put a dummy build.config.php in (and risk committing it)?

The only down side I can see is that if you take the lines out for the release version, you can’t work on the add-on any more unless you put them back in. OTOH, leaving them in could confuse people and slow things down slightly, especially for a plugin listening to a common event.

Quote from: BobRay at Sep 25, 2008, 12:44 AM

And you have to be really careful not to accidentally include build.config.php in the package (which I guess you’d do anyway).

Well, you wont have to worry - since the build.config.php is in the _build dir, which you shouldn’t be packaging anyway.

I’m still confused on one point. The add-on runs from comp-repo until it’s built and installed, but how can it run without being built and installed first? Do you install it and then put a dummy build.config.php in (and risk committing it)?

You don’t need to install it - you just run it as-is, from the comp-repo. Why would you need to install it first?

The only down side I can see is that if you take the lines out for the release version, you can’t work on the add-on any more unless you put them back in. OTOH, leaving them in could confuse people and slow things down slightly, especially for a plugin listening to a common event.

Yeah, but the overhead for one file_exists check isn’t that bad.

Quote from: BobRay at Sep 25, 2008, 12:13 AM

If I’m understanding you, you don’t duplicate the config file but just reference the one in the MODx _build dir. in the build script?

Well, once I have a config file, I can copy it into any _build directory for any component to build against a particular Revolution instance. Again, the build.config.php is only for the purpose of building the transport package.

Quote from: BobRay at Sep 25, 2008, 12:13 AM

I can see where using svn:externals could get me into trouble, so it sounds like your first scenario makes the most sense (especially in Revolution where the checked out add-on won’t actually function).

Agreed. It can become unruly with complex components which may install files into several locations; you’d have to maintain and be sure not to commit all the svn:property changes.

Quote from: BobRay at Sep 25, 2008, 12:13 AM

I’m still a little hazy on maintaining both Evolution and Revolution add-on versions. Looking at the add-on repo, it looks like each version is in a separate branch. What, then, is in the trunk? It seems to me that it would make more sense to have a separate directory in the repository (complete with trunk, tags, and branches) for the Evolution and Revolution versions (e.g. Ditto-Evolution & Ditto-Revolution) so I’m probably missing something. The current system makes it inefficient to set tags and I see that most, if not all, tags directories are empty. It also makes it harder to retrieve earlier releases of add-ons by name, which would be easy with tags.

Tagging a release is simple. You just copy the trunk or branch to a tag; where is the inefficiency? I never intended this repository to hold Evolution components; it is here to support Revolution component building on "reference" projects (ones that are officially reviewed and endorsed by the MODx Team), but keeping a version of the component that works in Evolution should be no different than maintaining multiple versions for Revolution; they are just version numbers. What we should avoid is using the same version number for a component with different targets; Ditto 2.0.1 should not have versions for Evolution and Revolution. It should be Ditto 2.0.1 for Evo and likely 3.0 for Revo.

Quote from: splittingred at Sep 25, 2008, 08:16 AM

[

I’m still confused on one point. The add-on runs from comp-repo until it’s built and installed, but how can it run without being built and installed first? Do you install it and then put a dummy build.config.php in (and risk committing it)?

You don’t need to install it - you just run it as-is, from the comp-repo. Why would you need to install it first?

Um ... because if it’s a component, the core doesn’t know it exists until you install it?

Quote from: OpenGeek at Sep 25, 2008, 10:33 AM

Quote from: BobRay at Sep 25, 2008, 12:13 AM

I’m still a little hazy on maintaining both Evolution and Revolution add-on versions. Looking at the add-on repo, it looks like each version is in a separate branch. What, then, is in the trunk? It seems to me that it would make more sense to have a separate directory in the repository (complete with trunk, tags, and branches) for the Evolution and Revolution versions (e.g. Ditto-Evolution & Ditto-Revolution) so I’m probably missing something. The current system makes it inefficient to set tags and I see that most, if not all, tags directories are empty. It also makes it harder to retrieve earlier releases of add-ons by name, which would be easy with tags.

Tagging a release is simple. You just copy the trunk or branch to a tag; where is the inefficiency? I never intended this repository to hold Evolution components; it is here to support Revolution component building on "reference" projects (ones that are officially reviewed and endorsed by the MODx Team), but keeping a version of the component that works in Evolution should be no different than maintaining multiple versions for Revolution; they are just version numbers. What we should avoid is using the same version number for a component with different targets; Ditto 2.0.1 should not have versions for Evolution and Revolution. It should be Ditto 2.0.1 for Evo and likely 3.0 for Revo.

I get it now. I was slow to realize that the repo wasn’t for Evo stuff (duh). In my comment on the inefficiency, I was thinking that having a series of tags to diverging development branches (Evo and Revo) would lose the "cheap copies" aspect of tags. Now that I’ve had a night’s sleep, though, I don’t even think that.

Is there a similar add-on repository I could use for Evo versions?