From 5cddf8cd2a2be84ea73ea93057133d24e484bf70 Mon Sep 17 00:00:00 2001
From: Lumir Balhar <lbalhar@redhat.com>
Date: Aug 27 2020 16:20:58 +0000
Subject: Document py_reproducible_pyc_path macro


---

diff --git a/guidelines/modules/ROOT/pages/Python_Appendix.adoc b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
index 5d9b56c..35dfeb1 100644
--- a/guidelines/modules/ROOT/pages/Python_Appendix.adoc
+++ b/guidelines/modules/ROOT/pages/Python_Appendix.adoc
@@ -418,3 +418,23 @@ make install DESTDIR=%{buildroot}
 ....
 
 Note that this *does disable* the compilation of files in `+/usr/lib(64)?/pythonX.Y/+`.
+
+== Byte compilation reproducibility
+
+For two Python files with the exact same content and metadata, byte compilation might produce different results.
+The resulting `.pyc` files are functionally identical but are not bit-by-bit identical.
+In most cases, internal Python refference counter is here to blame because it might have a different internal state during each byte compilation.
+If you want a deeper explanation, take a look at https://bugzilla.redhat.com/show_bug.cgi?id=1686078#c2[this Bugzilla comment].
+
+This inconvenience might cause a problem in Koji where noarch packages built as a part of an arch build might be rejected because they have different content.
+
+To workaround this issue, BuildRequire marshalparser `BuildRequires: /usr/bin/marshalparser` (a tool that makes `.pyc` files more reproducible)
+and instruct it to process the `.pyc` files in certain paths by setting the `%py_reproducible_pyc_path` macro:
+
+....
+%global py_reproducible_pyc_path %{buildroot}%{_datadir}/llamafarm/plugins
+....
+
+With that setting, marshalparser recursively finds all byte-compiled Python files in `%{buildroot}%{_datadir}/llamafarm/plugins` and tries to fix them.
+This happens at the very end of the build process when all previous byte compilation steps are finished.
+If marshalparser cannot parse some of the cache files, the build fails.