Chapter 4, Transactions

ZODB.org is having problems with git integration. We are temporarily moving to http://readthedocs.org to have documents built on commit. Please give us feedback!

This is the first comprehensive documentation on the transaction package.

ACID (atomicity, consistency, isolation, durability) is a very convienent feature of ZODB. Along with transactions it makes programming ZODB an enjoyable experience for the Python programmer. All persistent ZODB operations are controlled by commit/abort using the transaction package. Carlos describes integration points including datamanagers, synchronizers, and commithooks -- all integration points to wire custom code into participating with transactions. One such integration is zope.sqlalchemy which provides coordination of transactions between ZODB and SQLAlchemy data sources.

This chapter is longer than all three of the preceding chapters. It is the first comprehensive documentation on the transaction package. And it's the first chapter to use our favorite web framework Pyramid to demonstrate usage in a web context. Remember the transaction package does not depend on the ZODB. Spread the word.

Now Updated Daily on zodb.org

Carlos has been busy polishing up for release the 3rd chapter. As I understand this is the last of the introduction to ZODB. Now the next chapters are more detailed about theory and implementation of ZODB. Explanation of MVCC, transactions, etc. You can see the latest sphinx documentation at http://www.zodb.org/zodbbook/.

Another killer feature of the sphinx documentation is that Disqus has now been integrated into the HTML rendering of the pages. You can comment on each of the pages directly. Very cool. You can also see the magic which enables Disqus/Sphinx integration on github. http://github.com/cguardia/ZODB-Documentation/blob/master/book/_templates/page.html I have not seen Disqus being used with sphinx. But I hope it catches on.

Thanks to Carlos and Jens for making the ZODB book building daily on zodb.org and enabling disqus on the pages. The bar for participating is very low -- please participate. Add a comment. Even if you like it. We need to hear more peoples thoughts.

Chapter 3 draft ready, book text online

The draft for chapter three of the ZODB book is now in the github repository. There is now enough material that we felt ready to put it up somewhere for easy reading and possibly a bit of discussion. Jens Vagelpohl helped me get it up on the zodb.org web site and I added Disqus comments to the text. We'd very much appreciate any feedback on the work so far.

Chapter 2 draft and some words about the plan

August saw no advance on the book due to vacation time and the mad overwork period that usually follows. However, the draft for chapter two is now available on github, for those who'd like to review it.

A word of warning, though. People with experience on the ZODB will most likely find the material and tone are way too entry-level to be useful for them. That is because the audience that we will try to reach with part one of the book are Python developers in general. We assume no knowledge of the ZODB, not even of its existence.

If you look at the book outline, you'll see that the book is divided in three parts. The first part is this beginners guide, while the second part will contain much more detailed and advanced information. So, what I'm saying is, please be patient. I'll try to get going something from the second part for the next update.

Introductory chapter draft available on GitHub

A draft of the first chapter of the ZODB book has been committed to our GitHub repository. It's just the introductory chapter, so it might not seem like much. However, the introduction is very important when starting a technical book, since it sets the tone and helps define the audience more clearly.

If you can spend a few minutes to read it and comment, that would be very helpful.

By the way, there is now a portlet at the top right of the blog that shows the latest commits to the repository. This may make it easier to keep track of the book's progress.

GitHub project created

After considering where to host the code I decided that GitHub is a very good option to allow easy participation from any interested members of the community.

I created a repository with two Sphinx projects, one for articles and one for the book. In the future, demonstration source code will be included there as well.

The repository is at http://github.com/cguardia/ZODB-Documentation. If you are among the volunteers that will be writing articles for this blog, I suggest you strongly consider cloning the repository and doing your work there.

At this moment the repository is empty, except for the book outline, but this will be changing soon.

Tools for the writing process

Now that the ZODB book is on the planning stages and writing will start soon, it's a good time to think about what tools will be used for writing it.

I propose to use Sphinx to generate the documentation. The text will probably be stored in a Subversion repository, which could be svn.zope.org, for example. All of the book code will also live in a repository. I'm not opposed to the use of Github or Bitbucket if most people think that's the way to go, but personally I find I can get by with the above mentioned tools.

After we have at least a couple of chapters in a presentable state, the documentation could be automatically generated every day, so we can start to have a (slightly) useful resource well before the book is finished. We might be able to give the book a home like book.zodb.org or something.

Right now I'm not sure about whether we should use a wiki or an issue tracker, but it's something that could become useful if more people participate as voluntary reviewers of the book.

Well, this is how I see the writing process at the moment. Am I missing something? Do you have any ideas or suggestions? I'm willing to consider other options if that would get more people participating in the process.