commit cba9671ea52e3e2eda880d46fbca02fad01af5f6 Author: juga0 <juga@riseup.net> Date: Thu Feb 27 16:54:15 2020 +0000 fix: doc: Document why ersioneer to obtain version --- docs/source/implementation.rst | 98 ++++++++++++++++++++++++++++++++++++++++++ docs/source/index.rst | 1 + 2 files changed, 99 insertions(+) diff --git a/docs/source/implementation.rst b/docs/source/implementation.rst new file mode 100644 index 0000000..7470b62 --- /dev/null +++ b/docs/source/implementation.rst @@ -0,0 +1,98 @@ +Implementation decissions +========================= + +Dependencies +------------ + +When a needed feature is already implemented in some other software, there're +usually some things to consider whether to use that software as dependency or +re-implement the feature: + +Possible advantages using other software: + +- zero maintainance +- not reinventing the wheel + +Possible disadvantages using other software: + +- maybe too big +- maybe introduce security issues +- maybe is not maintaned + +sbws version +```````````` + +Because some bwauths install sbws from the git repository, it is useful to +know from which git revision they install it from. +We'd prefer to do not see the git revision when it is installed from a git +tag or Debian package (which is usually built from a git tag or git archive +release). + +A first solution would be to obtain the git revision at runtime, but: + +- sbws is not usually running from the same directory as the git repository, + as the installation might install it in other directory. +- if some other git repository is the current path, sbws might be obtaining + the git revision of that other repository. + +So next solution was to obtain the git revision at build/install time. +To achive this, an script should be call from the installer or at runtime +whenever `__version__` needs to be read. + +While it could be implemented by us, there're two external tools that achive +this. + +setuptools_scm +~~~~~~~~~~~~~~ + +https://github.com/pypa/setuptools_scm/ + +Advantages: + +- does what we want, for 19 commits after 1.1.0 tag it'd add an string like + `'1.1.1.dev19+g76ef2fe0.d20200221`. + We don't need the date, but it can probably be removed and it does not hurt. +- we don't need to maintain it. + +Disadvantages: + +- it adds the extra dependency setuptools_scm. +- it does not obtain the version from a git archive, though there's other tool + that does that. +- the version reported comes only from build time, so if we make a commit + without running `setup.py`, sbws will not report the new version. + +versioneer +~~~~~~~~~~ + +https://github.com/warner/python-versioneer + +Advantages: + +- it does not add any extra dependency. The first time, versioneer needs to + be installed. When run, it will generate `versioneer.py` and `_version.py`, + which are created from versioneer itself. Then it can be uninstall +- does what we want, for 19 commits after 1.1.0 tag it'd add an string like + `1.1.0+19.g76ef2fe0`. Note the difference with `1.1.0` from he `1.1.1` + generated by +- we don't need to maintain it. +- it is also capable to obtain the version from a git archive. +- the version reported at build time and runtime is the same. + +Disadvantages: + +- it adds extra code to sbws and it's quite a lot +- the generated code is independent from the upstream and loses the tests. +- does not seem maintained. + +Conclussion +~~~~~~~~~~~ + +Because `setuptools_scm` gives only the version at build time, we decided to +use `versioneer`. +We might need to change it in the future if starts giving problems with other +git or python versions or we find a way to make `setuptools_scm` to detect +the same version at buildtime and runtime. + +See `<https://github.com/MartinThoma/MartinThoma.github.io/blob/1235fcdecda4d71b42fc07bfe7db327a27e7bcde/content/2018-11-13-python-package-versions.md>`_ +for other comparative versioning python packages. \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 9806ef3..342e857 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -45,6 +45,7 @@ Included in the config config_tor sbws + implementation bandwidth_distribution tor_bandwidth_files bandwidth_authorities