This page introduces Commit Tool which stores Business Commits. Business Commits will be used to store changes made on objects in erp5 and hence track Business Templates.
Table of Contents
Portal Types¶
With the new specification, Business Templates will now be managed by 2 tools : Template Tool and Commit Tool. Template Tool stores the list of Business Templates and Commit Tool stores the list of Business Commits and Business Snapshots. Business Commit is single change unit and it is the object where we store addition/modification of ERP5 objects thanks to Business Item and Business Property Item. Let's have a look at the definition for the portal types of these objects.
Business Item¶
Business Item¶ is an ERP5 Folder object to store an ERP5 object at given path. It is denoted by (p, s, l, v) which stands for path, sign, layer and value respectively. Business Item is stored inside a Business Commit and it is being built from ZODB as soon as we add the path of the object.
Path is the path of the object which we want to store in this Business Item.
Value for a Business Item is the object which is stored in it. This object is build from ZODB at the time of creating this Business Item. It is the copy of the object at ZODB which is stored as a sub-object for Business Item.
Layer (0, 1, 2, 3, etc) defines the priority of the Business Item during its installation. For example, if there are multiple Business Item at same path getting installed together, the one with the higher layer would be preferred.
Sign has two options: +1/-1. If s=-1, it should read as: there should be no path p on layer l with any of values of v. If s=1, it should read as: there should be a path p on layer l with value set to one of values of v.
Follow Up Business Template: A Business Template related to this Business Item. The path of this Business Item will be stored in item_path_list of the follow_up Business Template. This signifies that whenever we install the follow up Business Template, this Business Item will also be installed.
Business Property Item¶
Business Property Item¶ is similar to Business Item except that the path here if not of an ERP5 object but of a property of an object. For example : portal_catalog/erp5_mysql_innodb#sql_catalog_search_keys_list denotes sql_catalog_search_keys_list property of the object portal_catalog/erp5_mysql_innodb). It has similar properties such as sign and layer, and a relation to follow up Business Template. For value though, we save the property name, property type and value of the property of the given object at ZODB.
Business Commit¶
It contains a few Business Item(s)/ Business Property Item(s) that have been changed as part of an atomic development process step. The ID for each commit will be an UUID so for reducing the chances of conflict between commits, Single unit of changes in some paths which would be pushed to remote erp5 central repository (Nexedi ERP5). Every commit will have a predecessor commit(except the first one) which points to the last commit. It has a business_commit_validation_workflow
Business Snapshot¶
It contains hard-links to each Business Item/ Business Property Item currently installed or to be installed in ZODB (which means thousands of hard links). Every snapshot will have an equivalent commit which is the UUID of the commit based on which this snapshot was created.
Business Template¶
Contains the specification of Business Template, i.e, dependency_list, provisions, paths of objects and properties which can be installed. It will store item_path_list in a property. There won't be any sub-objects for Business Template. From the meta-data we can find out all the Business Item and Business Property Item which have their follow_up relation to this Business Template.
Workflows¶
There is a need for well defined workflow as we have multiple relations between the objects. For ex: we need interaction workflow for managing the interaction between a Business Item or Business Property Item and a follow_up Business Template for this object.
Business Template¶ Validation Workflow
This workflow defines the state to find out if the Business Template is available for installation. The state and transition graph is shown in the figure.
available: A Business Template which has been committed would be in available state. This means it is available for installation but not for modification.
draft: A newly created BT should be in draft state. It needs to be installed to be available for follow_up list. So, the steps for it would be to commit the Business Template(making it available), then install it and then add modification on it and commit them.
installable: The installable state means that we can now add commits which makes updates on the Business Template. Or that we can modify the Business Template. An installable Business Template is already installed, but now we can add modification on it. Also, while installing a Business Commit, only the changes made to installable Business Template are applied. NOTE: The naming for this state is confusing. We are open to changes in naming for it.
Whenever one fetch all the Business Templates from remote repo, they will always be in available state at first. Also, we do not commit the workflow state of the Business Template, in fact we do not commit the workflow state(and some other useless properties for every value in Business Item).
Business Commit¶ Validation Workflow
A newly created Business Commit will be in draft state. It can be committed after adding atleast one Business Item/ Business Property Item. NOTE: one cannot make any change after committing a Business Commit). This commit can be pushed to remote repository. It isn't possible to create new commits unless you commit the last draft one.
A Business Item would be build automatically whenever you create the object inside the Business Commit. TODO: We can also rebuild the BI later before committing the BC to check the changes done in ZODB on the BI(s) in the commit.
Business Snapshot¶ Validation Workflow
Only one snapshot can be installed at one point. A newly installed snapshot should always change the state of old installed snapshot to replaced (thanks to interaction workflow). A newly created/snapshot (using view) would be in state draft. Snapshot generated from current state of Commit Tool graph should be in state not_installed.There is no concept of uninstall of snapshot - it can only be replaced. Uninstall is basically replacement of snapshot with a new desired snapshot.
Business Commit¶ Interaction Workflow
Manages interaction between Business Commit and the BTs affected by it (BI and BPI mentioned in it). After we commit a new BT (which should always have a follow_up to erp5_index BT(read Bootstrapping ERP5 - Site¶)), thanks to this workflow, the status of the BT is updated to available.
Business Item¶ / Business Property Item Interaction Workflow
Manages interaction between Business Item/Property Item and Business Template which is the follow up of the BI. After we create a Business Item with a follow up BT, the item_path_list of the BT is updated thanks to the interaction workflow.
Installation¶
The basic of installation is simple: Always first build the desired state in a snapshot, then apply.
There should always be 3 way comparison. Snapshot(To be installed) <> ZODB state <> Snapshot(Last Installed)
- Business Commit¶ Installation:
Whenever we install a Business Commit, we create a snapshot with items of the given commit and predecessors that belong to installed business templates (i.e. business templates with state = installable).
- Business Template¶ Installation:
If we decide to install a new BT5 at the same commit, we create a new snapshot with the items related to the BT and the items at the BC and then install the snapshot.
So, installing a BC doesn't ensure that all the BTs affected by it would be installed.
Also, installing a BT won't ensure that the BC would be installed. Simply, installing a BC is an action which has no effect on its state whatsoever. You just get a new snapshot with an installed state which will have its 'similar' to the commit on which install action was called.
Comparing items while installation¶
While comparing items while installation, we will always give priority to not lose user/developer changes. So, while displaying the changes we prefer to show in perspective of ZODB state. For example: If there is some object A installed, and a user changed it to B, and re-installation is trying to change it back to A, we should be showing 'Error (Modified by N.S)' where N.S is 'New Snapshot State'.
| Old State |
New State |
ZODB state |
Result |
| - |
- |
- |
- |
| - |
- |
A |
A (New added by ZODB) |
| - |
A |
A |
A (No change) |
| A |
A |
A |
A (No change) |
| A |
- |
- |
A (No change) |
| A |
A |
- |
Error (Removed at ZODB)
|
| A |
- |
A |
Error (Trying to remove by N.S) |
| - |
A |
- |
A (New added by N.S) |
| - |
A |
B |
Error (Modified by N.S) |
| A |
A |
B |
Error (Modified by N.S) |
| A |
B |
B |
B |
| A |
B |
A |
Error (Modified by N.S) |
| A |
- |
B |
Error (Trying to remove by N.S) |
Desired Snapshot¶
Snapshots are collection of hardlinks to BI/BPI. A snapshot can have multiple BI/BPI for single path. There is an underlying arithmetic on how to handle installation in such cases:
p : Path
s : Sign (+1/-1)
l : layer (0, 1, 2, 3, etc.)
v : value (set of picklable values)
Adding same path with different values leads to union of values:
[(p, s, l, (a, b, c))] + [(p, s, l, (d, e))] = [(p, s, l, (a, b, c, d, e))]
Subtracting a business item inverts its sign:
-[(p, s, l, v)] = [(p, -s, l, v)]
Subtracting a path with same value produces an empty set:
[(p, s, l, v)] - [(p, s, l, v)] = []
Subtracting two lists with intersection removes all intersecting values:
[(p, s, l, (a, b, c))] - [(p, s, l, (c, d, e))] = [(p, s, l, (a, b)), (p, s, -l, (d, e))]
Reduction¶
Reduction¶ is a function that takes a Business Snapshot as input and returns a smaller business snapshot by taking out values with lower priority layers. Two path on different layer are reduced as a single path with the highest layer:
if l1 > l2 -> reduce([(p, s, l1, (a, b, c)), (p, s, l2, (d, e))]) = [(p, s, l1, merge(a, b, c))]
Where the merge is a monotonic commutative function that depends on the type of a, b and c:
- if a, b and c are sets, merge = union
- if a, b and c are lists, merge = ordered concatenation (XXX can be discussed and probably wrong) ?? Use Business Patch Item otherwise
- if a, b and c are objects, merge = the object created the last (XXX can be discussed)
- else merge = MAX (XXX can be discussed)
A business snapshot is said to be reduced if and only if : reduce(BS) = BS
Bootstrapping ERP5 - Site¶
erp5_index BT : Business Template to store the index of all available BT. Every time, we create a new BT on our site and want to commit the working copy for this BT, we will need to give the follow_up as erp5_index. In this way, erp5_index will be a collection of index of all BT which can be populated in portal_templates.
Bootstrap will first create an erp5_index BT (which will have an empty item_path_list) and make it installable. Then we download the list of commits available for the repository. For an erp5_repository, there will be a root commit where we have erp5_index committed with no follow_up BT for it. From the HEAD Business Commit, we will create a snapshot and install it. This will basically update the erp5_index BT with index of all Business Templates as erp5_index is the only BT which is in installable state. Also, this will populate the portal_templates with all the available Business Templates. Now, we can install the Business Templates required for bootstrap using template tool in normal way it is done now.
XXX explain more the bootstrap and how it works by installing a kind of index bt and root commit from which everything can be installed.