diff --git a/HOW-TO-REPORT-A-BUG.md b/HOW-TO-REPORT-A-BUG.md index 399b3f9e..b62dc951 100644 --- a/HOW-TO-REPORT-A-BUG.md +++ b/HOW-TO-REPORT-A-BUG.md @@ -21,13 +21,36 @@ doing me a favor by doing scans on your favorite sets of bytecode files. In sum, it is not uncommon that you will find a mistranslation in -decompiling. +decompiling. Furthermore, you may be expected to do some work in order +to have your bug worthy of being considered above other bugs. +No one is getting paid to work to work on this project, let alone bugs +you may have an interest in. If you require decompiling bytecode +immediately, consider using a decompilation service. ## Is it really a bug? + +### Do you have valid bytecode? + +As mentioned in README.rst, this project doesn't handle obfuscated +code. See README.rst for suggestions for how to remove some kinds of +obfuscation. + +Checking if bytecode is valid is pretty simple: disassemble the code. +Python comes with a disassembly module called `dis`. A prerequisite +module for this package, `xdis` has a cross-python version +disassembler. + +### Semantic equivalence vs. exact source code + +Almost all versions of Python can perform some sort of code +improvement that can't be undone. In earlier versions of Python it is +rare; in later Python versions, it is more common. + If the code emitted is semantically equivalent, then this isn't a bug. + For example the code might be ``` @@ -80,19 +103,19 @@ The basic requirement is pretty simple: * Python source text Please don't put files on download services that one has to register -for or can't get to by issuing curl or wget. If you can't attach it to -the issue, or create a github gist, then the code you are sending is -too large. +for or can't get to by issuing a simple `curl` or `wget`. If you can't +attach it to the issue, or create a github gist, then the code you are +sending is too large. Also try to narrow the bug. See below. ## What to send (additional helpful information) Some kind folks also give the invocation they used and the output -which usually includes an error message produced. This is helpful. I -can figure out what OS you are running this on and what version of -*uncomplye6* was used. Therefore, if you don't provide the input -command and the output from that, please give: +which usually includes an error message produced. This is +helpful. From this, I can figure out what OS you are running this on +and what version of *uncomplye6* was used. Therefore, if you don't +provide the input command and the output from that, please give: * _uncompyle6_ version used * OS that you used this on @@ -113,11 +136,17 @@ Well, you could learn. No one is born into this world knowing how to disassemble Python bytecode. And as Richard Feynman once said, "What one fool can learn, so can another." +If this is too difficult, or too time consuming, or not of interest to +you, then perhaps what require is a decompilation service. [Crazy +Compilers](http://www.crazy-compilers.com/decompyle/) offers a +byte-code decompiler service for versions of Python up to 2.6. (If +there are others around let me know and I'll list them here.) + ## Narrowing the problem I don't need or want the entire source code base for which one file or -module can't be decompiled. I just need that one file or module -only. If there are several files, file a bug report for each file. +module can't be decompiled. I just need those file(s) or module(s). +If there are several files, file a bug report for each file. Python modules can get quite large, and usually decompilation problems occur in a single function or maybe the main-line code but not any of @@ -131,3 +160,13 @@ properly on a neighboring version of Python. That is helpful too. In sum, the more you can isolate or narrow the problem, the more likley the problem will be fixed and fixed sooner. + +## Confidentiality of Bug Reports + +When you report a bug, you are giving up confidentiality to the source +code and the byte code. However, I would imagine that if you have +narrowed the problem sufficiently, confidentiality little that +remains would not be an issue. + +However feel free to remove any commments, and modify variable names +or constants in the source code.