where is database description for ez publish??

Author Message

zurgutt -

Tuesday 19 May 2009 12:14:30 pm

Now and then again i have to debug some sql error. Like now. There is a duplicate key error while inserting an object and i cant figure out what parts of the query really mean. What are the table fields for, what is the relation to other tables and content objects? Pretty much impossible to figure out problem without any information about fields.

Low level database structure seems to be a closely guarded secret. The closest thing anyone has seen is a 5 years old gif that has very little info on it and has been obsolete for years. Still, documentation about must exist in ez systems otherwise it would not be possible to develop ez publish by anyone else besides few level 52 immortal gurus who levitate in front of their computers and know every line by heart.

Could you share it? It would be so much easier to develop and fix bugs..

Certified eZ developer looking for projects.
zurgutt at gg.ee

Heath

Wednesday 20 May 2009 3:43:39 am

Agreed! I was just wishing for this <i>again</i> last week.

Cheers,
Heath

Brookins Consulting | http://brookinsconsulting.com/
Certified | http://auth.ez.no/certification/verify/380350
Solutions | http://projects.ez.no/users/community/brookins_consulting
eZpedia community documentation project | http://ezpedia.org

André R.

Wednesday 20 May 2009 4:31:48 am

> Could you share it? It would be so much easier to develop and fix bugs..

Share what? Do you really think we have or own secret documentation that we don't want to share with you?

But thanks for bringing it up, we will try to generate a new one even though the one generating the old one is long gone and we're not sure how it was generated (there are several programs around to generate it, so hopefully not to much work so we can do it more frequently).

eZ Online Editor 5: http://projects.ez.no/ezoe || eZJSCore (Ajax): http://projects.ez.no/ezjscore || eZ Publish EE http://ez.no/eZPublish/eZ-Publish-Enterprise-Subscription
@: http://twitter.com/andrerom

Arnoud van Steen

Wednesday 20 May 2009 7:11:47 am

<i>quoting André R.</i>
Share what? Do you really think we have or own secret documentation that we don't want to share with you?
<i>End of quoting André R.</i>

I've been developing on Ez Publish for a while now (since april), and find that the documentation is seriously lacking in many aspects. Now I have not looked at the datamodel really as I have not needed to delve into that yet. I've been working with the ContentObjects, Treenodes etc. And the code documentation is lacking proper explanation of the parameters needed for a function and especially their type and the explanation of that type. Plus the return values are never given, it sometimes gives an idea by saying what the result will be, but there's no explanation again of the type to expect from a function call. Neither does it give the return value in case of errors or results other then what the function normally would return.
I actually have to dig into the code (!!) to find what I normally would want to read in the documentation of a function. And this is costing me a lot of time.

This lack of proper documentation makes Ez Publish extremely frustrating to develop on at times. So to be honest, I can hardly imagine developers working on further developing this piece of software without proper documentation. Which, sorry to say, leads to the assumption that it must be there somewhere with Ez Publish, but might be kept back to gain partners? And to emphasize, this is the feeling I get after working on Ez Publish for a while, I'm in no way trying to accuse Ez Publish of anything. ;)

It also leads me to the question of what the benefits of becoming a partner of Ez Publish are, does this mean that you receive better documentation to help development on the platform? And this is an honest question I have at this time.

zurgutt -

Monday 25 May 2009 1:33:42 am

<i>Do you really think we have or own secret documentation that we don't want to share with you?</i>
Well.. i dont really want to believe that but its hard to imagine how you could develop without having any documentation on database setup...

Perhaps you have something that is not perfect, still its better that nothing and could be shared. Otherwise it will be years until it happens. Or forever.

Does someone know good opensource program to document mysql database? Keys, relations, comments on fields and tables, good visual output. There should be some around, please suggest, so there is no excuse to hold anything back :)

<i>
I've been developing on Ez Publish for a while now (since april), and find that the documentation is seriously lacking in many aspects.
</i>
You have been working with it for a month? Someone once said to me it takes half a year to grok it and he was right. Of course there was less documentation then and IRC channel was inactive. Have you been to IRC? You should. I think part of the problems you are having comes from misunderstandings. Learning curve is steep.

That said, it is true that documentation is not perfect but i have come more or less accept it. Way it seems to me, there is actually lots of information out there but its poorly referenced, hard to find and most importantly it is missing the "how to find out about stuff" reference for newbies.

Certified eZ developer looking for projects.
zurgutt at gg.ee

Łukasz Serwatka

Monday 25 May 2009 2:09:22 am

<i>
Perhaps you have something that is not perfect, still its better that nothing and could be shared. Otherwise it will be years until it happens. Or forever.

Does someone know good opensource program to document mysql database? Keys, relations, comments on fields and tables, good visual output. There should be some around, please suggest, so there is no excuse to hold anything back :)
</i>

You can create your own DB visualisation with MySQL Workbench http://dev.mysql.com/downloads/workbench/5.1.html

Creating tables overview is not a problem, relations are a problem. And those has to be added manually same as was done with the old DB diagram. Basically it has to be extended for support of new tables.

eZ Publish uses PersistentObject as most of the relations is defined as foreign_attribute and foreign_class so looking on those information, it should be easy to figure out the relations between tables. Keep in mind also that cascading operations in eZ Publish almost does not exist. As simple thing, what would you do if a user is deleted from the system? We do not delete all content where foreign creator_id key exists for removed user. eZ Publish is very complex in regard to the DB relations, unfortunately only manual maintenance is possible at the moment.

Personal website -> http://serwatka.net
Blog (about eZ Publish) -> http://serwatka.net/blog

Igor Vrdoljak

Monday 25 May 2009 5:45:29 am

I agree that proper visual database model would be of great help when working with guts of eZ Publish, together with relationships and (where needed) a short explanation.

As for partners having extra documentation, I can tell you that (unfortunately :-) we do not, at least not at Bronze and Silver level (Netgen is a Silver level partner). For now we are extracting datatables using Visio and figuring out relationships ourselves.

<i>Keep in mind also that cascading operations in eZ Publish almost does not exist. As simple thing, what would you do if a user is deleted from the system? We do not delete all content where foreign creator_id key exists for removed user. eZ Publish is very complex in regard to the DB relations, unfortunately only manual maintenance is possible at the moment.</i>

I can see your reasoning there, but still some kind of maintenance script for cleaning up garbage from database would be of great help, especially for large, community driven websites.

http://www.netgen.hr/eng
http://twitter.com/ivrdoljak

Jérôme Renard

Monday 25 May 2009 8:17:13 am

Let's make it clear :

- there is no hidden document at all, wether you are a gold/silver/gold/platinium/diamond/uranium partner or not
- the public documentation is the one we use every day

Learning eZ Publish is hard and the documentation sometimes (often ?) may not help you (I am not saying it is a good thing), that is a fact. If ever you have any question or if there is anything not clear to you feel free to ask a question in the forums.

Sorry for being harsh here but at least it is clear.

Best Regards.

kracker (the)

Monday 25 May 2009 9:20:46 am

Oh really?

Their is no way in this life or the next that a company like eZ Systems could function without owning additional documentation (large or small) on their own products. Period. Your just not telling the full truth if you defend yourself on this one ...

Ever wonder why the lowest levels of the kernel, db and eZ internals have little documentation? I did for a long time. You have to keep the customers happy with some kind of always incomplete public documentation but don't give away too much about the internals.

In this way when new developers work with the php layers of eZ they will desire like madd rabid animals further knowledge. This is the future evolution of non-free/proprietary (I think), Open Product + Excessive Architecture + Hidden Knowledge.

Not only does eZ Systems have epic fail volumes of important information withheld they profiteer based off the very careful dissemination and distribution of eZ knowledge (re: eZ Training).

eZ Training documentation for example. I think the community itself would benefit from new kinds of documentation similar to the kinds of information only shared in eZ Training (Did I tell you they -only- hand out binary documentation during training!)

eZ Systems is a knowledge monopoly growing larger each each year. It is interesting to watch though a little disgusting to stomach. You can't win against a company like eZ, you can only do your own thing (what ever you want to call that), payout or cash out.

Good luck. You'll need it. They don't help people they encumber them. Ever want to push someone to hurting themselves give them a copy of eZ and tell them their livelyhood and pride surround the mastering this product without outside assistance.

All that said (it was fun), we live in an imperfect world and we are all imperfect flawed humans trying to better ourselves. I love eZ but love does not preclude very strong criticism/slander.

I'll owe Zurgutt a beer the day I find out that eZ publicly releases an updated copy of the requested diagram cause frankly 7 years of experience with this product and company have lead me to believe in eZ's 'Good Intentions' like I would believe in Dexter Morgan wanted to be my friend, figure it out.

<i>Cheers,
//kracker

Kingspade : Who runs this?
Dirtball : Self Made ...
Twisted : How I live ...</i>

Member since: 2001.07.13 || http://ezpedia.se7enx.com/

Arnoud van Steen

Monday 25 May 2009 9:53:50 am

<i>Quoting zurgutt</i>
You have been working with it for a month? Someone once said to me it takes half a year to grok it and he was right. Of course there was less documentation then and IRC channel was inactive. Have you been to IRC? You should. I think part of the problems you are having comes from misunderstandings. Learning curve is steep.
<i>End Quote</i>

Actually two months now.. Probably a short while indeed, but its long enough to see the consistent lack of proper documentation in the API and code itself.
I've not had a whole lot of questions to ask really, but found answers for those I had on the forums.
The problem is not directly finding answers to questions, but as I mentioned about, the problems that come from having inadequate API documentation, resulting in me having to spend a whole lot of time just to figure out what I need to supply to functions and what the exact result will be when I do call them with those parameters.
I do not see IRC being useful for getting that kind of information. Asking in there for every function call I will have to make on the objects in Ez Publish.

Every self respecting programmer adds at the very least basic information like:
@param ..... explain
@return ..... explain

Steven E. Bailey

Monday 25 May 2009 10:30:02 am

As far as Gold Partner goes, we didn't get any additional documentation with it... actually I'm still trying to figure out what Gold Partner got us at all.

Anyway, I once ran some database program that made a nice huge png of an eZPublish database (after segfaulting a few times first) but it turned out to be mostly useless because it didn't have any of the relations. I guess someone who actually understands the database well enough would have to draw in the relations - frankly I don't think anyone actually does understand it enough to do that.

The documentation. Yeah, it's been 4 years and most of the time I'm looking in the code to figure out what is actually going on.

Which is frustrating at times, but, hey, on some level that's what people pay me to do. So, in a way, it's job security for all of us.

Certified eZPublish developer
http://ez.no/certification/verify/396111

Available for ezpublish troubleshooting, hosting and custom extension development: http://www.leidentech.com

Jérôme Renard

Tuesday 26 May 2009 2:29:46 am

Kracker,

Oh really?

really.

Their is no way in this life or the next that a company like eZ Systems could function without owning additional documentation (large or small) on their own products. Period. Your just not telling the full truth if you defend yourself on this one ...

Yes and I come from Mars as well...
Code is public, documentation is public we use the same tools as the community does, period. We apply the rules as everyone does: RTFM (Read That Fucking Manual) and RTFC (Read That Fucking Code). If you are not able to understand that, then there is nothing I can for your. You can say I am a liar then I challenge you to prove I did not say the truth.

Bertrand Dunogier

Tuesday 26 May 2009 2:34:11 am

I think you made Jérôme a bit mad... good luck with that.

But honestly, he's right: we don't have more documentation than what you can find, and trust me, we do keep a strong focus on documentation (err... API documentation. End user one is another matter...) these days, and I believe you can see that by looking at the inline code of recent developements.

We perfectly know that lack of documentation can be extremely frustrating, but we really really don't need to hold information back, trust me.

Bertrand Dunogier
eZ Systems Engineering, Lyon
http://twitter.com/bdunogier
http://gplus.to/BertrandDunogier

André R.

Tuesday 26 May 2009 3:06:37 am

The truth is the knowledge is shared among the devs that work on eZ Publish and its extensions, we use jabber / irc / skype to ask each other questions all the time, since some guys are more knowledgeable on some parts of the code then others. In other words, it's not written down, it exists in our head. We are very aware of this being an issue, as we feel the pain every time some dev leaves the company, that for instance was the guy that knew most about the template parser/compiler for instance...

We do try to document all new code (ref autload.php and ezcontetclassattribute.php::classAttributeIdentifiersHash for instance) and re factored code (ezsession.php).
But as of now we'll try to document at least minimal description / @param / @return doc on all methods we need to read the code of to understand as well.

Some of us also try to compensate for missing doc by being active in the forum, and give in depth answer whenever we have the time. And yes, we should have a faq where we place the answers, at least the ones that are in depth and highly descriptive, but that is slightly off topic.

So please stop this pointless word fight, its unproductive and as far as I know ezp is open source so we should maybe instead discuss how the community incl partners can contribute more directly in a re-viewable way as you need to read the code quite often as well it seems.

Good thing eZ Coding standard is quite strict though.. :)

eZ Online Editor 5: http://projects.ez.no/ezoe || eZJSCore (Ajax): http://projects.ez.no/ezjscore || eZ Publish EE http://ez.no/eZPublish/eZ-Publish-Enterprise-Subscription
@: http://twitter.com/andrerom

Björn Dieding@xrow.de

Tuesday 26 May 2009 3:19:50 pm

I will moderate starting from this post onwards. Flames will get deleted.

Looking for a new job? http://www.xrow.com/xrow-GmbH/Jobs
Looking for hosting? http://hostingezpublish.com
-----------------------------------------------------------------------------
GMT +01:00 Hannover, Germany
Web: http://www.xrow.com/

Paul Wilson

Tuesday 26 May 2009 9:35:17 pm

I suggest the key message here is that we need better ways to work together.

I’ve helped design regional and national programs to help people find new and better ways to do this. A whole-systems approach is needed. I won’t go into details here.

The problems expressed here and in Kristof Cooman’s recent blog entry are all symptoms of this need.

Finding a better way forward is in everyone’s best interests – and doing nothing is likely to lead to progressively more and more problems.

The success and future of both eZ Systems and the eZ community are clearly interwoven. This is why it is useful to think in terms of an overall eZ ecosystem and to solve problems / create value at that level.

At the moment I don’t think eZ has quite come to terms with what this means or what to do about it. Neither, perhaps understandably, has the eZ community. In any case, it is how these groups work together that is important.

eZ Crew, please contact me if you would like to discuss this more. There are clear and practical ways to help the entire eZ ecosystem.

Wei Dai

Tuesday 26 May 2009 11:50:18 pm

Hi, I suggest that in future eZ Publish, e.g. maybe eZ Publish 5, rework the code based on the eZ Components. Then update a whole new documentation Is it possible?

Of course, a clear document of database schema and description is critical.

:)

Certified eZ Publish 4 developer looking for develop information & collaboration.

André R.

Wednesday 27 May 2009 1:24:10 am

Paul Wilson: That sounds like a commercial message... :)

Wei Dai: You are talking about project V, its off topic but more importantly we would need to find solutions for how we can better work together before that.

eZ Online Editor 5: http://projects.ez.no/ezoe || eZJSCore (Ajax): http://projects.ez.no/ezjscore || eZ Publish EE http://ez.no/eZPublish/eZ-Publish-Enterprise-Subscription
@: http://twitter.com/andrerom

Felix Laate

Wednesday 27 May 2009 1:28:28 am

There is a price for everything. And the price for using open source stuff is often imperfect nice enduser-documentation. Why? Because its expensive.

On the other hand, the code is open and actually quite readable. And the API-documentation is not bad. Not bad at all. Only a pitty thats its somewhat hidden.

A company like eZ needs like any company to make money. The eZ Crew need to feed their kids like anybody else. Thats not a crime.

On the other side, we would all benefit if eZ would let the community get involved in the real development processes.

Suggestion: eZ should make a developer-blog where they communicate their development (e.g. whats up with project V, why stuff is delayed, where to find info).

Publlic Relations Manager
Greater Stavanger
www.greaterstavanger.com

Gaetano Giunta

Wednesday 27 May 2009 2:06:48 am

@kracker: <i>(Did I tell you they -only- hand out binary documentation during training!)</i>

For all trainings I have delivered personally or seen delivered from eZ Systems-WE, the deliverables included a complete copy of the slides and and the training exercices in pdf format. I do not know what other format you would expect, but please share any ideas.

What's more, most of the material that makes up the slides is quite similar to the online manual that is available for free to anybody - the added value of the "basics" training being the presence of the instructor, the exercises, and the completeness of the program.

@arnoud: <i>Every self respecting programmer adds at the very least basic information like...</i>

The problem is this "very least" stuff is quite new in terms of computing practices, and a lot of eZP code is old, ie. it was written before javadocs and unit tests where commonplace. Documenting new code is easy, documenting old one is much harder. But sometimes people do: http://pubsvn.ez.no/websvn2/revision.php?repname=nextgen&path=%2Ftrunk%2F&rev=23604

@Łukasz <i>Creating tables overview is not a problem, relations are a problem</i>

I have had this crazy idea lingering in the back of my head for a while: what about finding out those foreign keys and test implementing them in the db, using not on-delete-cascade? Since eZ code takes care currently od deleteing relations in the proper order, almost everything should work, and the parts that do not are spots where we should improve the code. Anybody has ever tried that?

@Wei: a big-switch over to ezc code was considered and rejected, as it would take too long to recode everything and it would be too risky and too harsh on existing extensions / sites. The switch will happen, but gradually.

Principal Consultant International Business
Member of the Community Project Board

Powered by eZ Publish™ CMS Open Source Web Content Management. Copyright © 1999-2014 eZ Systems AS (except where otherwise noted). All rights reserved.