This explanation is intended to show how maintainer scripts work, in a more graphical manner than the one explained in the Debian Policy. It's not intended as a replacement, but as a clarification.
For that purpose, this is going to be illustrated with several diagrams (made with dia). In the figures, the maintainer scripts called and their params are showed inside boxes, the possible outcomes ("OK" or "FAILED") lead to different consequences. External actions to the maintainer scripts are showed in italics, while the package ending status is showed in bold.
Let's start with the most simple example: the installation of a new package, one that wasn't installed first.
Let's explain this figure a little bit: when a package is being installed, first preinst install is called, then postinst configure. If all goes well, then the status of the package is Installed.
But, if something in the preinst install fails, then postrm abort-install is called. If this goes ok, the user will get an error message, and the package will be left in a Not Installed state. But if the postrm abort-install also fails, the package will be left in a nasty state: Half Installed, Reinst required. This means that the package needs to be reinstalled even if you want to remove it.
If something in the postinst configure fails, then the user is shown an error message, and the package is left in Failed-Config state.
The rest of the figures follow the same pattern, the explanations will be less verbose from now on.
When removing a package that was previously installed, if everything goes well, the package will be left in the Config Files state, this means that it needs to be purged before it is in the Not installed state.
If something goes wrong at the postrm stage, and the postinst abort-remove script is called, then the package might be left in a strange state: it is still Installed, but the files are not there anymore. If any of the processes fails, when the package removal is tried again, it will resume from where it left (i.e. if the prerm worked and the postrm didn't, it'll resume from the postrm).
If a package that is in state Config Files has to be purged, the cycle is really simple: the conffiles are deleted and then postrm purge is called.
Removing and Purging
If the package is to be removed and purged at the same time, both diagrams combine, forming a diagram in which the package passes to be Not installed if everything goes ok.
Installing from '''Config-Files''' state
If a package was installed and then removed, but not purged, it's left in Config-Files state. If the installation of a new version is attempted at that moment, the order of the scripts will be almost the same as the simple installation ones, but with a slight difference: the scripts receive a second parameter indicating the old version that used to be present.
The other difference is that if postrm abort-install is called, the package is left in the same state that was before the install was attempted (i.e Config-Files).
The next step in complexity (and it's a big step) is doing an install that is actually upgrading an already installed package.
As you can see from the diagram, if all goes well four scripts are called, but when things go wrong, it gets much more complicated, and the package might be left in many different states.
(No diagram for downgrading yet.)
Downgrading is generally unsafe, here's the sequence of calls when every script succeeds:
1.2-4->prerm upgrade 1.2-3
1.2-3->preinst upgrade 1.2-4
Files are unpacked
1.2-4->postrm upgrade 1.2-3
1.2-3->postinst configure 1.2-4
This is the same procedure as upgrading, but swapping versions.
The only thing left that is in the Policy and not in the previous diagram is when a package is being replaced by one that conflicts with it. I won't deal with it now and here, but if you are willing to do the tests and the diagrams yourself, you are free to edit this page and include them.
This site has diagrams regarding conflicting packages: http://people.debian.org/~srivasta/MaintainerScripts.html, albeit in a different style.
Sources for the diagrams
The diagrams used in this page were made with dia, and are available for download at: http://www.marga.com.ar/~marga/debian/diagrams/, all this documentation is GPLv2+ and you can make use of it for whatever you like.
This page was originally created as part of the Debian Women project wiki.