[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [jfw] Re: Discussion - Framework v2 Roadmap

On Tue, Feb 17, 2015 at 5:11 PM, Andrew Eddie <mamboblue AT gmail.com> wrote:
On 18 February 2015 at 00:28, Michael Babker <michael.babker AT gmail.com> wrote:
> Some of my griping about the current structure is based on how disconnected
> everything feels

It should if you are adhering ruthlessly to the Single Responsibility
Principle. That's actually a really good problem to have :)

The packages themselves are fine in terms of dependencies and independent use/testing.  But there's 30+ resources moving in 30+ directions with no cohesion between them.  It feels like to me we have a collection of packages that are thrown under a brand name for the sake of grouping them.  PHP League already has claim to that organizational structure and are doing great things with it ;-)

> and how difficult it is in this structure to get attention
> around updates.  Since Framework 1.0 was released, there have been a grand
> total of zero announcements regarding package updates.

I believe I sent in PR to move Keychain to 2.0 some time ago ;)

You did.  And I pretty much sat on it for the sole reason that it was at a point in time where I was getting burned out by the project, by life circumstances, and felt like I was the only person really using or maintaining the code.  And there was a good chunk of time where I really considered just pulling the plug on it all and getting what we could reintegrated to the non-namespaced CMS classes and letting someone else absorb what was salvageable (maybe the League could have absorbed our GitHub, & Profiler packages, the former with a bit of retooling).  Right now I feel a little better about things.

> Granted, it's as
> much my fault as anyone's (if not more), but it's really difficult to
> promote package releases when effectively what we're doing is "hey, we
> merged a pull request, here's an updated package!".  I doubt anyone wants to
> see 3 dozen "Framework <Package> 2.0 Released" tweets,

No, that's not what I'm thinking at all, except perhaps for day 0.
After that, each package is master of its own destiny, which may
include bumping major versions from time to time, or accepting that
its season of usefulness is at an end.

> nor would it do well
> for us to have a single "Framework 2.0 Released" announcement when a
> majority of the stack has had 2.0 for potentially weeks or months (the
> DateTime package from last year's GSoC was released as 2.0 in September with
> no fanfare).  The only unifying thing about our present structure is the
> brand name, and I'd go so far as to say what we have isn't framework
> material nor is it being managed in a way where it could be considered such.

No, and I think a mindset change is needed. The overriding fact is we
are never going to have the resources to do a full-stack framework -
and that's mostly due to the fact that we have no major corporate
users to back the Framework up.

A lot of my gripe in this block is all around marketing, believe it or not.  How do we promote the Framework, updates of the code, or highlight new features when everything is moving at its own pace and everything basically equates to a merged PR is a new release?  There is just no feasible way right now to gather any attention around what is happening in the code.  You can't run posts like https://make.wordpress.org/core/2015/02/09/emoji-feature-plugin-for-4-2/ or http://symfony.com/blog/a-week-of-symfony-424-9-15-february-2015 highlighting anything and there's no enticement from third parties to follow a blog feed for the Framework or any social media outlet if people are just going to be told "follow GitHub, it's our only communication source" (I know that isn't the case, but dumbing things down to a least effort required scenario).  Short of spamming the Twitter feed with the GitHub activity, I don't have an answer to "how can we promote this project".

You say we can't do a full-stack framework.  I say we can.  Joomla's been doing it for the last decade.  Granted, that framework has been geared toward a more specific purpose and implementation (the CMS), but we already have the baseline of tools needed to build from.  What needs to happen is some of that code just needs some cleaning up to be less coupled to its original implementation in the CMS (I think the Form package is the most guilty of this right now) and we need to be looking at ways to improve the code which helps our packages evolve and in turn creates a stronger developer API for the CMS.  Regardless of the Framework existing or not, our database package needs a lot of work as it pertains to database schemas and handling schema updates between application releases; there is no good reason to require raw SQL as the schema manager in today's ecosystem.

To solve that, I think you need to change tack and use the Framework
to upgrade the CMS one package at a time, using a 1.5-style legacy
layer to bridge the changes. That way, the CMS is using the code and
there is no stupid argument about whether the Framework deserves to
have the name Joomla.

Already working on that where we can.  3.4 got a handful of Framework packages (ones that were in essence straight drop-in replacements).  So far they've been simple exercises.  I'm interested in stepping up the complexity another level; how can we integrate packages which don't have a strict hierarchy without breaking compatibility in the CMS?  This excludes the application and database classes at the moment, but I'm thinking we could integrate other packages (Date or Language for example) in a way similar to how we handled the URI package (dropping it in, keeping the JUri class for CMS features, and relying on the rest to come from the Framework package).

Yes, that was how Platform 11.1 was supposed to work but the problem
with that was the monolithic release system. Composer support for the
CMS fixes that, but I still think trying to synchronise the versions
of 30 packages, where there is mostly no change in any of the
packages, is a messy system to support.

If you go fully modular, a bug fix for a package can be merged and
released on the same day - simple! And semantic versioning is easy to
work out. The alternative, which is the current situation, is PR's
wait until you get to a point where you "feel" like a release is
needed, or you are constantly argue to delay the release to slip in
another fix. Why not just fix each package and bump the package's
version when you need to?

What we end up with in a fully modular scenario isn't a framework, and if that's the direction we're heading then we need some re-branding to not use that term to describe what we're doing.  Which is in essence where we are today and have been since Framework 1.1's release.  Everything has been moving at its own pace (if even moving at all) and we depend almost entirely on Packagist and Google searches to even find us or what's going on with our code.

>> ## Documentation
> Laravel
> (https://github.com/laravel/docs) and Symfony
> (https://github.com/symfony/symfony-docs) both maintain docs in a
> consolidated location on GitHub and publish them via their main website.

Yes, and both of those projects have solid companies backing them so
they have the resources to maintain superb docs. They are also mature,
full stack offerings. The Joomla Framework isn't anywhere close to
being able to claim that. When the CMS is entirely built off Framework
packages, we can revise the status :)

Anyway, the extra docs you talk about go into the framework.joomla.org
site itself, separate from the individual package docs. That site
aggregates both the PHPDoc API pages and also package docs themselves.

I'd suggest just writing the documentation before figuring out how many places we want to duplicate it in.  And I would seriously argue against duplicating the PHPDoc stuff between the API & Framework sites; we already have enough problems with Joomla related content being spread across too many domains, let's not add to that.

Building applications, using the database API, or working with the Crypt package requires you to reverse engineer the code to figure out how to implement the tools.  It's been an issue for years and we just keep saying "well we'll require docs with new code"; nobody is addressing the decade of missing documentation we have in the project and short of doing a code-freeze until everything is properly documented, I don't see it happening anytime this decade.

That way, the rules of contribution are simple:

1. The developer MUST include DocBlocks (that pass linting rules).
2. The developer MUST provide explanatory notes about the basic usage
of the package with the PR.
3. The developer MAY choose to add additional user tutorials for one
or a combination of many packages.

It's that MAY that gets us.  I can almost guarantee you that next to nobody is aware that Registry 1.3 (included in CMS 3.4) can be iterated over or counted, or that outputting the data to a PHP file now supports namespaced classes, and the only way to figure that out is to follow the commit history.  But all of those changes meet the MUSTs of your list of rules.

At the end of the day, I could live with docs all in one repo,
providing reviewing strictly enforces that docs are a requirement with
code changes. But, I think a solid README is still vitally important
for the developer doing a search on Packagist.org and coming to the
package on Github and finding out what it does. If Packagist follows
the NPM example, it will eventually start consuming, and potentially
indexing that content (at least, that's what I'd do).

Personally, I don't think a README file (or doc blocks) should be the point of truth for documentation on any code.  IMO a repo's README file should be an executive summary of what the package is doing, what you need in order to use the package, and links to appropriate resources (full documentation, third party APIs, example applications, support queues, etc.).  Cramming everything into a README is just piss-poor documentation management IMO, and if you actually have a strong level of documentation (something 90% of our code lacks), those files are going to be excessively long and have conflicts all the time if the Framework code repos were a quarter as active as the CMS or any other proper Framework stack.

Framework source code: https://github.com/joomla-framework
Visit http://developer.joomla.org for more information about developing with Joomla!
You received this message because you are subscribed to the Google Groups "Joomla! Framework Development" group.
To unsubscribe from this group and stop receiving emails from it, send an email to joomla-dev-framework+unsubscribe AT googlegroups.com.
Visit this group at http://groups.google.com/group/joomla-dev-framework.