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

On Mon, Feb 16, 2015 at 5:30 PM, Andrew Eddie <mamboblue AT gmail.com> wrote:

## Consolidated Code Repository

I personally don't think this is optimum. While, sure, it makes checking out the Framework easy, it does complicate matters.

It doesn't promote isolation of the code (we've had cases where tests passed in the full stack, but didn't on an individual package because some test scaffolding bled into other tests).

It makes the tests for each package longer to run (if I want to make a quick fix to Keychain, I have to wait for all the other tests to run first).

It doesn't allow for incremental changes to individual packages to happen when they are needed (for example, many packages could go 2.0 right now, but it's not happening because some packages are not quite ready).

My personal preference, and it's come from working in both the Composer and NPM universes, is that individual package are the point of truth, manage their own dependencies (the less the better) and their own lifecycle (some packages will get a lot of support and change a lot, some won't - so be it).

In terms of being able to download the whole Framework, this can be done with Composer's create-project feature. In fact, you don't want to do that at all. You want to spin up a half-dozen examples of starter applications (command line, REST, web site, et al) that people can pull down and have a skeleton application up-and-running very quickly.

Some of my griping about the current structure is based on how disconnected everything feels 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. 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, 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.

## Documentation

Given the previous comment, I feel strongly that documentation should still live with each package.

However, the intention was always so be able to build the programmers API into one site (from the DocBlocks), and also compile all of the package documentation into one master site (something like what Laravel does would be what I would aim for).

The advantage of leaving the docs in the same repo as the code is that you only need one pull request to check that the documentation has been adjusted appropriately for any given code change.

To put it another way, it's easy to automated collecting docs from several sources. It's not easy to automate checks that there is a PR for code (and tests), and a PR for docs. The split strategy has never, ever worked for the CMS, but having docs and code in one contributor PR has worked in the Framework for many years.

That works well for package specific documentation. Where do you put documentation on general best practices for the entire code stack, or tutorials on building applications or resources with our code? The only points of truth we have right now are the API site (with the automated doc block parsing) and the 3 dozen README files. 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.

I don't think we need automated checks on whether a pull request has documentation either. What we do need is an established contributor workflow that is crystal clear on all requirements. Symfony has it right (http://symfony.com/doc/current/contributing/code/patches.html) IMO; I spent longer writing the documentation pull request than I did putting together my first code pull request because of how well everything was explained.