#6896 Developer architecture docs

v1.1.0
closed
General
2015-08-20
2013-11-19
No

It'd be useful to have some high-level docs for developers that are getting started with Allura. And update/overhaul our current developer-oriented doc pages. I think we should cover things like: how the code is organized, what technology is used (paster, TG, EW, jinja, etc), how to log & debug, how tests work, etc.

Discussion

  • Tim Van Steenburgh

    • assigned_to: Tim Van Steenburgh
     
  • Dave Brondsema

    Dave Brondsema - 2013-12-03
    • Milestone: limbo --> forge-dec-27
     
  • Dave Brondsema

    Dave Brondsema - 2013-12-10

    Here's a few paragraphs that I have used in private conversations to help explain how to get started in Allura:

    To run our test suite, you can run ./run_tests in the top-level of the allura code. That is a wrapper around "nosetests" which you can use to run tests for individual packages or files.

    http://allura.sourceforge.net/docs/platform_tour.html covers some aspects. Besides that, the top-level directories are for each separate tool, so there's some organization there. The Allura directory has the main code, which dispatches out to each tool as needed. And individual tools will use common classes and functions from the Allura package.

    The entry point for everything is in Allura/allura/controllers/root.py The controllers use object dispatch, see http://turbogears.readthedocs.org/en/tg2.3.0b2/turbogears/objectdispatch.html So every method and attribute in a controller maps to a URL. Pretty quickly, though, it gets dynamic and dispatches to neighborhoods which dispatch to projects which dispatch to tools. Each tool's entry point is going to be in a file named something like wiki_main.py In it there's a ForgeWikiApp which defines the tool. That class specifies self.root = RootController() so the RootController class is where you'll find all the URL handling for a wiki. At the end of the day, using grep or some other search tool is often key to finding where something is :)

    As far as tech goes, mongodb is probably the best thing to learn. It is used throughout Allura. We use a library called Ming, on top of pymongo, to map to objects and such. http://merciless.sourceforge.net/tour.html

     
  • Dave Brondsema

    Dave Brondsema - 2013-12-13
    • Size: --> 4
     
  • Tim Van Steenburgh

    • status: open --> in-progress
     
  • Tim Van Steenburgh

    • status: in-progress --> code-review
     
  • Tim Van Steenburgh

    allura:tv/6896

     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02
    • Milestone: forge-dec-27 --> forge-jan-10
     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02
    • QA: Dave Brondsema
     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02

    testing.rst has very old example code within def setUp Should we update that now too?

    I think we should highlight the 'bitesize' ticket label on the mailing list, so other devs know about it and start using it. Perhaps link to it from the wiki too. At the very least on the wiki https://forge-allura.apache.org/p/allura/wiki/Contributing%20Code/ should gain a link to this new doc once its published.

    Forking on forge-allura.apache.org doesn't work currently since we're not running git on that server. I don't know what we should suggest at this point. But probably not something that doesn't work :(

     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02
    • status: code-review --> in-progress
     
  • Tim Van Steenburgh

    1. Yeah, I'll update that code.
    2. Definitely, I'll do these as soon as this is published.
    3. What do you think about using the SF link for now? Seems like we need to either do that, or setup git on the apache server. Not sure what's involved there, or how much work it'll be.
     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02

    3. The SF repo is currently hidden to non-admins. I did that a few weeks ago, to reduce confusion/duplication. We could use it again though. Setting up git on the apache server would be better I think, but would take some work. And probably some customization so that the /p/allura repo path and checkout command can be different from forks in /u/*

     
  • Dave Brondsema

    Dave Brondsema - 2014-01-02

    Perhaps just omit that section from the docs for now? We don't have very frequent new contributors so it may be fine for a while. Folks can come and ask if/when they get to that point

     
  • Tim Van Steenburgh

    • status: in-progress --> code-review
     
  • Tim Van Steenburgh

    To https://git-wip-us.apache.org/repos/asf/incubator-allura.git
       2822658..99e3c9a  tv/6896 -> tv/6896
    
     
  • Dave Brondsema

    Dave Brondsema - 2014-01-03
    • status: code-review --> closed
     

Log in to post a comment.