An Easier way to Build Packages, Version code, and contribute to existing projects

Just time -- I haven't had time to create one. It's a lot faster and easier to just create a form. IMO, launching the form by previewing a resource is about as easy as launching a CMP. Using a CMP makes it look slicker, but the extra isn't for use by clients, just MODX developers.

This looks like a cracking piece of work Everett, I love the concept.

Me and @SilentWorks have been working recently on a command line implementation of the concept and I think the two could really compliment each other well. That and a load of future tools that could really make development easier. And I agree that the core requirement for tools like this to work is a standardised style-guide for file structure and commenting in new developments.

I'm not sure how to kick this off (possibly a pull-request driven git repo) but I propose some sort of Standards Recommendation put together by the community (most likely those of us listed in this post) that outlines the ideal file structure and commenting syntax for creating new components. If we can come to an agreement on the best way to do this then any current or future tools built will all be able to work on the same packages - rather than having multiple tools all competing and being incompatible it will be possible to pick and choose the best tool for you, and not have to worry about whether a package was created with a different tool.

Can anyone suggest some collaborative way of the community designing the 'optimum' package structure? I'm not at all against Everett's proposals, but I feel that imposing standards should be a community effort rather than the opinions of a single user.

Nice! Yeah, a command-line tool here could be a real asset.

I've been reading about "Submodules" in Git (http://git-scm.com/book/en/Git-Tools-Submodules), and I think that's gonna be a good way to distribute a packaging helper utility: in a perfect world, the dev could just clone the repo as a submodule into their build directory OR simply move a copy of that code into their _build directory. Devs could pull down the latest updates as they're released, or they could simply do a vanilla copy and avoid the potential submodule headaches.

As for discussing standards, YES, this would be best if the community weighed in. The object parameters are pretty straight-forward -- it's mostly paint-by-numbers with room for some sweet spots (e.g. the plugin events outlined in the example here https://github.com/craftsmancoding/repoman/wiki), but perhaps the larger conversation is regarding folder structure.

There's some weird stuff out there with folder structure... e.g. elements/chunks/, elements/plugins/ etc. -- why should element objects be shepherded into their own sub-directory? And why don't the directory names match the object names (i.e. why not a directory for "modsnippet")? I think I can come up with a folder mapping that will catch most of the repos I've looked at, but what about standardizing less-common objects? E.g. where should a modMenu object be stored? Or a modResource? Or a modUserGroup?

And how about the model directory? Why the smurf do we have a smurf smurf repeated smurfing directory name like core/components/smurf/model/smurf/? Seems redundant. Why is it always done that way?

As long as the mapping can be customized for each package (i.e. if the build script looks for an optional customization file), then we should be able to move forward and change the exact settings as it becomes clearer what the standards should be. Many of the build scripts allow for this sort of customization already, so no need to stop.

This is a good conversation to have, regardless of which tool is involved.

The implementation we have of our CLI tool at present is added to system path and can be called from any directory (no reason not to add it as a composer/pear package down the line though I guess) and handles generation of basic file templates and (will) parsing files found in a dir into a transport package. It's comprised of two tools - the core PHP submodule classes for actual work and a CLI wrapper to interface with it. I would love to implement any proposed standards into the templates rather than making my own up! But i digress... This post should be about standards, not individual tools (sorry for hi-jacking your thread Everett)

Folder structure for elements... I think this is a good thing. It's all well and good calling the folder modChunk, but what happens down the line when (if/hopefuly/pleeeeeaaasssee) it becomes possible to class_key any element and create a modSmartyChunk? They are still chunks, so I think they should be filed together, but they are not modChunks anymore. I think the actual class key for an element should (if needed) be defined in the docBlock.

Models... i had a really good answer for your point until i sat down to type it. I think the reason for this is so you can have separate models bundled into one extra... You could load just the 'image gallery' models, or just the 'comments model' separately without needing to load them both into memory at the same time. The namespacing of models should be handled by the path you load them from but I'm not overly confident on this - need to find out if loading two identically named xPDO packages from different paths causes issues (almost certainly)

Customizable mapping... I think the simplest option would be to auto-search for a php file in the _build directory to run in the middle of the build script. Much like the middle part of the doodles build.transport.php, but without all the setup and teardown stuff wrapped around it. This would offer ultimate flexibility for devs wanting to do something crazy. [ed. note: alanpich last edited this post 13 years, 7 months ago.]

The standard organization was developed by splittingred (Shaun), who has been one of the most prolific extra developers we have. It's described in detail in many of the docs (e.g., the Doodles tutorial) and an awful lot of the GitHub repos I've looked at follow it exactly. I think there are reasons for most of it. For one thing, having those "smurf smurf repeated smurfing" directories allows you to have separate sub-parts within your project (see Shaun's Login package).

I think between us, Shaun, Mark Hamstra, and I have at least 100 packages (public and private) that match that structure pretty closely and I doubt if any of them will be reorganized.

I would like it if the element directories were called modSnippet, modChunk, etc., but converting 'snippets' to 'modSnippet' is a pretty easy transformation:



and going the other way:



Since we have a fairly well-documented structure that's in wide use, I would hate to see us get bogged down with trying to create a new one. Part of the reason I created MyComponent was to provide a tool that would create that structure for you automatically. If you install MyComponent and run Bootstrap, you'll get the Example project under assets/mycomponents/example and you can see that there's a place for just about everything you'd want to package except users and permissions (and they're on the roadmap).

It appears that RepoMan also follows that structure (though I haven't looked that closely at it). If so, I think with minor modifications MyComponent might work on RepoMan files and vice versa.

MyComponent puts all the information about your component objects and their relationships in a single config file, which is the only project file you have to edit, while RepoMan puts it in each of the source files. I think it would be possible to create a tool to generate the MyComponent config file from the comments in RepoMan files and a tool to put the RepoMan comments in the files based on the MyComponent config file.

The only hitch, as Everett pointed out, is what to do with objects like system settings, menus, contexts, namespaces, users, property sets, policies, policy templates, ACL entries, and all the other objects that traditionally don't have source files in a build package in the same sense that elements do. That's the main reason I went with the config file, where those objects can be described simply as PHP arrays, created based on the fields of those arrays, imported into MODX from the config file, and exported from MODX into their build files. That said, I don't see any reason why you couldn't put RepoMan comments right in the build files stored in standard locations under _build/data, though for something like users or property sets, the comments section would be bigger than the code section.

Agreed: there is a convention followed by a majority of the extras out there. I'm just not always clear on why it is the way it is (the smurf thing was just a joke to illustrate the repetitiveness: http://www.codinghorror.com/blog/2012/07/new-programming-jargon.html).

Re the $data array... that is a very good question. I haven't tackled that in my proof-of-concept here. Probably it's easiest to use the PHP arrays there since (that's a place where I don't think the doc block approach is as useful). So where's the best place to store that kind of data? If you have a _build directory that is cloned in its entirety from a helper-tool's repo, then it might be poor form to add objects/data directly into that folder (along the same lines as "don't modify the core code lest stuff break").

Standard-wise, I'm wondering if it might be better to use a data directory outside the _build directory, e.g.

• _build - contains a clone of a package tool (with room for customizations)
• assets - assets/components/my_pkg destined to be copied to your assets dir
• core - core/components/my_pkg destined to be copied to your core dir
• data - contains sub-directories for all other objects, e.g. system settings, menus, resources

The data directory could continue to live inside of the _build directory (with the help of .gitignore). I think this is really the crux of it (as Bob inferred) -- this is where standards could be the most helpful. All Elements could live inside the package's core/components/my_pkg/elements/ folder and they would be benefit the most from using the doc-blocks. It's those other object types that can fall through the cracks. E.g. here's a sample from Articles' _build/data/events/events.articles.php:



I'm not sure if it's best to store an array of events in a single file, or if it's better to use a one-file-per-object approach. I'm also not sure if "data/elements/" is the best name for that folder -- "pluginevents" is probably better so as not to be confused with modEvent objects. Perhaps you could reference it via a doc-block like this:



That way the build script would know when to include it. But what about other objects, as alanpich mentioned, e.g. modSomeCustomObject?

I propose that in most cases one-object-per-file is easier to work with. Just return the requisite array from a single file and a built script can automate its creation.

Lastly, the subtle problem here is with the order of the objects. E.g. if you have CustomObjectA which is dependent on CustomObjectB, then you'd have to have a way to configure the order of imports.... but I think that's all surmountable. [ed. note: Everettg_99 last edited this post 13 years, 7 months ago.]

IMO, having one file per object would not work very well in practice, for many reasons. It makes sense for Elements like snippets, chunks, plugins, and templates, which have significant content. It also makes sense for Resources (or actually, the resource content field), but not much else. There are a ton of existing extras out there and I've never seen one where events, properties, menus, contexts, or anything but resources and elements went in separate files. I there there are good reasons for wanting them that way.

As for file locations, I've assumed that when splittingred wrote his many extras and the official documentation on creating an extra, he spent a lot of time thinking about the best way to organize them. If you look at his packages at GitHub, you can find out the official location for pretty much any MODX object: https://github.com/splittingred?tab=repositories. I hope were'e not trying to reinvent the wheel here.