Consolidating duplication

Now that 1.9 has been released, I think we need to step back from new features and start consolidating the developer experience. We have a *lot* of duplication in this project:

  • 2 Change logs
  • 2 build scripts
  • 2 sets of documentation
  • 2 PHP test frameworks (Evan made some promising headway)
  • 2 JS engines
  • 2 class loaders

I know some of this is due to BC, but a lot of this can and should be fixed. I think the biggest offenders are the documentation and JS.

For docs, we don't have much of an excuse to have two of them still, other than we haven't had the time to migrate the old one. It's arguable that we shouldn't have launched the RTD version (even though it's an improvement) if we didn't have a time to properly migrate the existing docs.

For JS, I understand we needed to keep our Elgg JS object in 1.9 for BC, but we should have updated our JS to be AMD compatible. It's confusing for new devs to see us recommend using AMD but that not be reflected in our own code.

I know we're all interested in forward momentum toward 2.0, but we've been putting some of these off for so long that first impressions of Elgg to new devs are not what I think we would all want them to be.

  • Fine with this, but we need to be willing to fix it up for them. 

    Right, that's what I meant by this. We'd agree to put the onus of keeping the commit message format on the merger instead of the PR author.

    For the single plugin as gold standard, which did you have in mind? I'm thinking discussions/groups, because of its heavy use on the community site

    I don't have a big preference, but I was thinking about blogs since it's a bit of an oddball already. Discussions would be fine, too. The important part is that we collaborate to make The Plugin then publish and apply those guidelines to the rest of the bundled plugins.

  • Cool. Anyone else have opinions on which plugin we focus on cleaning up?

  • I was thinking blog as well because:

    • it seems to be the most commonly referenced core plugin when people are looking for examples
    • it's a pretty basic concept that people can understand right off the bat
    • it covers creating a new content type by extending ElggObject
    • it covers pagehandling, views, notifications, translations
    • there is a js component
  • Groups plugin is mentioned from time to time, as the plugin which lagged behind most, compared to the improvements in Elgg in recent years. I am not sure if this is a good example but things like it does not lend itself to cloning etc.

    Probably it is also a challenging one to work on for "Gold Standard". But probably will need to be tackled one day.

  • I'm not sure if it would be necessary to have a lesser standard for commit messages for PRs upgrading docs. While there are already (some very brief) instructions on how to provide PRs for Elgg core in general it might be worth expanding these instructions to provide some step-by-step instructions on the fork/clone/fetch/commit/push/make PR workflow "for dummies" (and I include myself in the group of dummies!). If there would be some more details explanations created once the work necessary to fix errors in PRs might be much reduced in the following.

    If anyone interested, I've recently created a github tasks workflow for personal use to have the necessary steps and commands involved when making a PR available when needed. It does not yet include any specific details that might have to be considered addtionally when making a PR for Elgg core, but it might be of some use and maybe could expanded where necessary.

  • Probably it is also a challenging one to work on for "Gold Standard". But probably will need to be tackled one day

    The idea is to apply the guidelines created to all the bundled plugins, so no matter which we pick to start with, they will all benefit.

  • I would vote for the discussion plugin. It requires a new plugin, so better work on that. I think the blog plugin is not complex enough to be a good sample. Discussion has objects, annotations, custom classes, migration scripts, deactivate/activate scripts, actions, pagehandlers, events and hooks, so it covers all the framework features.

    Important would be to write down the best practices and to discuss some choices, like file naming conventions, folder structures, registering action inside init or outside, placing events functions in start or in separate lib files, etcetera

  • I do like the idea of being able to start totally from scratch with the discussions plugin, too.

    One concern I have is that if nothing significant is going to change about the plugin api, do we really think this effort is going to turn out significantly better? The initial list of issues that started this thread won't be improved just by naming things better. If we could rewrite the plugin assuming that the dependency injection system is available and that we could define actions/forms via classes, now that would make a real difference in quality IMO, because we'd actually be able to write tests for the rewritten code. That's also something worth documenting, since it provides the practical benefit of stability to developers who have never had it before.

    The untestability of plugins is a major shortcoming of the project and any plugin refresh we embark on should take this problem seriously. The irony of course is that this would effectively be a second way of writing plugins... so we'd have to be pretty committed to following through and converting all core plugins to the new standard once we've figured it out...

  • I think a number of problems in Elgg have stemmed from the "we don't need to fix this now because we're going to change it later" mentality. My point is that currently there is no good example of a plugin. Our docs say to do things Way X, but the bundled plugins do it Way Y because we're planning to change to Way Z in the future.

    Our users need an example of good code in the current API. For this effort, we need to approach plugin development as 3rd party developers, not core devs who can change the API.

  • I doubt that any single plugin can cover all possible use cases. So, I think any plugin selected will have it's pros and cons. Maybe the approach should be: correct (and suffieciently complete) documentation first, implementing in an example code / example plugin later. Then it would be at least possible to refer to the documentation first instead of suggesting to look into the code of a specific plugin as example. And at writing the documentation it might be possible to sort out contradicting implementation details on a more general level than within a single plugin.

    For an example plugin using an existing plugin as starting point as opposed to creating a new one would have the advantage that it might provide some different point of view if the existing code is compared with the (newly written) docs and some of the API functions used within the plugin turn out to be "private" API functions. ;-) Can the plugin be rewritten without the use of any private API functions or will it be necessary to make some of the private functions public functions...

Feedback and Planning

Feedback and Planning

Discussions about the past, present, and future of Elgg and this community site.