34. It’s tested
• ~95% test coverage
• Narrative documentation included
• Continuous Integration
35.
36. Import and Usage style
from plone import api
portal = api.portal.get()
user = api.user.create(username='bob')
api.content.move(
source=portal['blog'],
id='old-blog',
)
44. api.role
with api.role('Manager'):
# do something bypassing all
# constraints, permissions, etc.
with api.role('Reviewer'):
# do something as a reviewer to see
# if permissions are set correctly
48. Help us!
• Translating documentation into your language
• Multilingual Sphinx on RTD anyone?
• Show us your home-baked maintenance
scripts
• All this and more, at the post-conference sprint
49. Post-Conference sprint
• TodoApp coding dojo
• Implement remaining plone.api methods
• Get the test coverage even higher!
• Native speakers’ love to our docs
• Let’s get beta release out there!
52. Thanks!
Give it a spin!
propose ideas!
Join the sprint!
http://github.com/plone/plone.api
Editor's Notes
\n
- non-coders sit down\n- from where to import getToolByName\n- get site root\n- copy content object\n
Hi, I’m Nejc and this is a story about how Plone development went to a dark place ... and what we are doing to bring it back!\n
\n
we were building a portal for a student organization\n
The workshop was organized by EESTEC.\nEESTEC = electrical engineering students in 53 universities,\nAll event applications go through eestec.net, a Plone portal.\nMultiple events per year, more than 2000 users\n
More than 25 hundred EE students using Plone, many of them programmers.\n\n
Out of that 25 hundred potential Plonistas how many did we manage to keep in the eestec.net development team?\n\n\n
Two. Less than 0.1 percent of potential pool of students and 50+ of them attending week-long eestec.net development workshops. \n\n
Main reason? This thing.\n
Plone 3, for us, made it:\n
Now, Plone 4 did make *a lot* of things easier. But numerous problems still persist:\n
All the time you need to search for where does that one thing import from\n
There are many ways to achieve tasks: how to know which is correct?\n
Manipulating objects is not trivial, you need to search for code.\n
Let’s look at workflow states: you *have* to Google for snippets.\n\nThe list goes on an on.\n
This is BAD. This is why we couldn’t keep developers in. This is why our documentation is hard to follow. This is why it’s hard to train.\n
Enter plone.api. An elegant and simple API,\nbuilt for humans wishing to develop with Plone\n
The initiative for having a unified API for common Plone tasks started this year at the Plone Konferenz in Munich\n\n- Antwerp Beer Sprint: teaching students how to develop with Plone -> when stumbled upon a part that was ugly, a team of Ploners made a plone.api method for it\n\n- +15 commiters\n\n
Explicit is better than implicit.\nReadability counts.\nThere should be only one way to do it.\nNow is better than never.\nWe only want to cover the most common tasks and use-cases, not all.\n\n
Looking back to the question of from where to import that thing?\n
\n
\n
\n
\n
\n
And one of my favorites, as I could *never* remember how to do it.\n
It’s now this simple to do it.\n
\n
Document Driven Development\n- plenty of room for discussion\n- not much to re-program if we fail with the first try\n- a nice looking and usable api because we already used it (in the docs)\n\n(NEXT SLIDE HERE!)\n\n
Plone.api comes with narrative documentation,\nthat guides you through common use-cases of how to use the api.\n\nNarrative documentation means written in a way that guides you through how you can\nuse the API, but does not cover all use-cases, to keep text simple.\n\nHowever, if you click on one of these links, you get to the full-spec advanced documentation\n
Besides that you have the full-specs documentation of every method.\nWith all possible parameters and edge-cases explained.\n\nThe information here is pulled directly from the code, so it is always up-to-date.\n\nIt describes all possible parameters you can pass to a method, its return value, etc.\n\nExample links back to narrative documentation from the previous slide.\n
\n
* high test coverage\n * all code examples in the narrative documentation is also tested so we make sure the examples actually work\n * everytime there is a commit, an online service called Travis CI runs all tests (more about Travis in my talk tomorrow morning)\n
here it is, history of builds and their statuses\n
Methods are grouped by their field of usage:\nPortal, Content, Users and Groups.\n
\n
\n
\n
\n
\n
Integration: project specific, you know the stakes.\nAdd-on: very likely you may use it, but maybe you’ll have to use some underlying APIs later on to cover edge cases\nCore code: Nope, core code needs to cover *all* possible scenarios.\n
However, our work is far from finished.\nYou can expect the following features in the future:\n
- maintenance tasks and scripts\n- tests!\n
- for debugging addons\n- for tests\n- for code dependant on Plone version\n
\n
Now this is a HUGE one!\n
Sysadmins I’m looking at you!\n
- todo-app coding dojo to go through the tutorial and test it while learning sth. new\n- coding new plone.api methods -- doable by human-only developers\n- increasing test-coverage\n- we need a native english speaker that is a solid in writing to go through our narrative text and give it some love\n
What if someday, plone.api is widely used in most of integration code and add-ons. \nImagine:\n- a non-suicidal learning curve\n- single point of reference for common tasks\n- standardized AJAX/WebServices access\n- upgrades to Plone core code would keep add-ons working!\n
Let’s start living this dream.\n\nCrying over how Plone is getting impossible to work with is not enough.\n\nFight for your rights as a developer. Do something to make your\nday-to-day Plone experience better. Let’s live the utopia.\n\nGive plone.api a spin, report bugs, propose ideas, join our sprint!\n
It’s now up to you, humans using Plone, to\n - try out plone.api\n - shout out what bothers you or what is missing\n - and help with development\n