can we tidy up? and keep on throwing out legacy? TL;DR



  • Digging into the codebase of Newscoop over the last days (trying to understand some of its guts and dealing with dependencies - see other thread) left me with a rather chaotic impression ;)


    I understand that Newscoop has grown organically over time, has a legacy with certain constraints, should try not to break backwards compatibility… wants to keep all kinds of audiences happy:users, developers, professionals and amateurs etc.


    What worries me most from a developers perspective, is that mix/or lack of conventions (folder structures and naming) different class loading approaches, code style, spreading dependencies throughout the project could evolve it into an unmaintainable unloved creature, cursed to die slowly.


    Who would want that?


    I think the decision to "refactor" the codebase towards ZendFramework and adopt patterns like MVC etc. was a good one. Having an old blogpost on refactoring in mindI would say its a tough (maybe binary) decision wether to rewrite or refactor. In the end it comes down to how. Its hard to not rewrite, when you go from oldschool php towards a zfApp. A smooth incremental transition from one state to the other is very desirable. But calling it a refactor(of a code monolith), avoiding/ignoring to rewrite (separate old and new app)... dont' know what exactly happened. maybe we are just stuck somewhere in between?


    Looking at it now, I would like to discuss some ideas (painful and maybe radical or just cosmetical?)


    SpringCleaning


    • remove,restructure and rename folders
    • unify class loading through composer (strip more require onces)
    • separate rewrite from legacy code (legacy lives in public?)
    • embrace github benefits(make git your primary upstream, use pull requests(tested on travis-ci))


    considerations / goals


    The developer
    looks at the README and should be able to

    • read-on (distribute source with proper (api)docs and manual don't just point to a 404 )
    • testdrive the application in no time
    • set up a proper development env to start contributing (not contaminating any existing environment)
    • understand the application structure (conventions)






    Devops/System Administrators


    • Newscoop should be deployable through git
    • have everything under version control (where it makes sense)
    • if files need to be written, do so in the appropriate place (/data or public/)
    • doing a git status on a deployed app currently leaves me with thousands of files not under version control/gitignore
    provide recipes to deploy to heroku, orchestra  







    Maintainers (packaging, distribution)


    • code duplication is a pain
    • one place for dependencies
    • one strategy to resolve dependencies
    • less clutter (cut legacy)


    lets follow some conventions and don't have nested multiples: ideally there is only one place (folder each) to look for


    • documentation
    • configuration
    • dependencies
    • executables
    • application code
    • templates
    • [zf]
    data/caches/generated content/public files









    • separation between public and non public file
    • publicly exposed (webroot) php files are potentially more exploitable
    • publicly exposed files should be reduced to a minimum
    • this should also help separating old legacy code from the ZF Application approach
    • hopefully prevents coupling of app and legacy code in the future


    Newscoop  mixes in some zf project directory conventions already - why not adopt them more consequently, where it makes sense http://framework.zend.com/manual/en/project-structure.project.html  I also find *nix naming like /bin /var /vendor tempting ;)


    We might end up with something like the following (see attachments) - please add your ideas and requirements


    in terms of conventions there probably is no perfect solution - one might even prefer the current dir structure over that suggested. Its also quite likely that I didnt think of requirements for distribution"/packaging" or certain stacks (like heroku requiring an /index.php which is stupid ;))

    For me, going into the direction described, would def. ease my pain in working with Newscoop. 

    I hope I am not stealing your time on this..

    Cheers, Leander

    By the way, the forum "WYSIWYG" editor is a lemon

    Post edited by Leander Damme at 2012-07-17 15:48:30
  • 2 Comments sorted by
  • Vote Up0Vote Down Paweł MikołajczukPaweł Mikołajczuk
    Posts: 72Member, Sourcefabric Team
    I really like your idea!

    For me the most important point is "understand the application structure (conventions)"
  • so far I have only understood some of the Zend Framework code (mostly backend code). The Frontend of Newscoop and especially the "plugins" architecture are rather mysterious to me. Plugins like debate seem to have a big impact on the frontend (provide a lot of its functionality - Shouldn't they be therefore called core-components ;) ?

    The only way to see what is really going on would be some profiling of the app (see attachment - don't be scared)

    Maybe I was too optimistic on the state of Newscoop and underestimating the amount of work to clean this up.
    3703 x 5219 - 928K