WIP: feature buildout hash readme
README.update-hash.rst 0 → 100644
1 update-hash 2 =========== 3 4 ``update-hash`` is a development tool to automatically work with 5 ``buildout.hash.cfg`` files.
``update-hash`` is a tool to assist software release developers in the management of ``buldout.hash.cfg`` files.
Or add a short introduction explaining the problem this tool is addressing (but this introduction might already going too much in details):
Recipes taking external resources as input, such as
slapos.recipe.template, usually support an
md5sumoption that should be set to the checksum of the content of the resource. This way, recipe can verify resource integrity and also be re-installed when the option changed.
Often, the external resources are stored in the same directory in slapos git repository than the profile using them and the profile include them as a relative URL, using
update-hashis a tool that assist profile authors in this situation, it automates the task of updating the profile with the new checksum when a resource is modified.
This way, recipe can verify resource integrity and also be re-installed when the option changed.
To me the latter is the only actually relevant reason. Integrity checking is only secondary, and only when considering "natural occurrences" (file actually changed, or some rare corruption during transit) and never ever against malicious activity (which would need something much more recent, like the SHA2 family).
Often, the external resources are stored in the same directory in slapos git repository than the profile using them
The actual reason update-hash strongly discourages directories is that it needed a value which can be both a local file path and an URL path. Filesystem directory separators being non-portable (unlike URL directory separators), directories are discouraged. If update-hash needs to convert between path schemes, it needs to do it consistently with how the recipe would, which may not be trivial (filesystems and OSs have their own restrictions on which chars can be used and which chars are equivalent, and we need to specify for which OS the path has been written...).
And this limitation does not bother me, because I see having a subfolder for 4 templates as a waste of time when looking for a piece of an SR or when getting an overview of its content.
Shouldn't we say a few words about:
- integration as a git commit hook ( https://lab.nexedi.com/nexedi/slapos/blob/55aa57b4ae05447ba6bf78b2bb8174183e6c724e/update-hash#L3-34 or !424 )
- merge tool for buildout.hash.cfg !273