Update HOW-TO-REPORT-A-BUG.md

rocky · web-flow · commit ec8e45bad197 · 2025-09-29T05:35:04.000-04:00
diff --git a/HOW-TO-REPORT-A-BUG.md b/HOW-TO-REPORT-A-BUG.md
@@ -10,7 +10,7 @@
 - [What to send (minimum requirements)](#what-to-send-minimum-requirements)
 - [What to send (additional helpful information)](#what-to-send-additional-helpful-information)
     - [But I don't *have* the source code!](#but-i-dont-have-the-source-code)
-        - [But I don't *have* the source code and am incapable of figuring how to do a hand disassembly!](#but-i-dont-have-the-source-code-and-am-incapable-of-figuring-how-to-do-a-hand-disassembly)
+        - [But I don't *have* the source code and am incapable of figuring out how to do a hand disassembly!](#but-i-dont-have-the-source-code-and-am-incapable-of-figuring-how-to-do-a-hand-disassembly)
 - [Narrowing the problem](#narrowing-the-problem)
 - [Karma](#karma)
 - [Confidentiality of Bug Reports](#confidentiality-of-bug-reports)
@@ -20,32 +20,32 @@
 TL;DR (too long; didn't read)
 
 * Don't do something illegal. And don't ask me to do something illegal or help you do something illegal.
-* We already have an infinite supply of decompilation bugs that need fixing, and an automated mechanism for finding more. Decompilation bugs get addressed by easiness to fix and by whim. If you expect yours to be fixed ahead of those, you need to justify why. You can ask for a hand-assisted decompilation, but that is expensive and beyond what most are willing to spend. A $100 fee is needed just to look at the bytecode.
+* We already have an infinite supply of decompilation bugs that need fixing, and an automated mechanism for finding more. Decompilation bugs get addressed by ease to fix and by whim. If you expect yours to be fixed ahead of those, you need to justify why. You can ask for a hand-assisted decompilation, but that is expensive and beyond what most are willing to spend. A $100 fee is needed just to look at the bytecode.
 * When asking for help, you may be asked for what you've tried on your own first. There are plenty of sources of information about this code.
 * Bugs get fixed, slowly. Sometimes on the order of months or years. If you are looking for *timely* help or support, that is typically known as a _paid_ service.
-* Submitting a bug or issue report that is likely to get acted upon may require a bit of effort on your part to make it easy for the problem solver. If you are not willing to do that, please don't waste your or our time. Bug report may be closed with about as much thought and care as apparent in the effort to create the bug. Supporting the project however, does increase the likelihood of your issue getting noticed and acted upon.
+* Submitting a bug or issue report that is likely to get acted upon may require a bit of effort on your part to make it easy for the problem solver. If you are not willing to do that, please don't waste your or our time. Bug reports may be closed with about as much thought and care as apparent in the effort to create the bug. Supporting the project, however, does increase the likelihood of your issue getting noticed and acted upon.
 
 # Ethics
 
-Do not use this program for unethical or illegal purposes. More detestable, at least to me, is asking for help to assist you in something that might not legitimate.
+Do not use this program for unethical or illegal purposes. More detestable, at least to me, is asking for help to assist you in something that might not be legitimate.
 
 Don't use the issue tracker for such unethical or illegal solicitations. To try to stave off illegitimate behavior, you should note that the issue tracker, the code, and bugs mentioned in that are in the open: there is no
-confidentiality. You may be asked about the authorship or claimed ownership of the bytecode. If I think something is not quite right, I may label the issue questionable which may make the it easier those who are looking for illegal activity.
+confidentiality. You may be asked about the authorship or claimed ownership of the bytecode. If I think something is not quite right, I may label the issue questionable, which may make it easier for those who are looking for illegal activity.
 
 
 # The importance of your bug report
 
-For many open-source projects bugs where the expectation is that bugs are rare, reporting bugs in a *thoughtful* way can be helpful. See also [How to Ask Questions the Smart Way](http://www.catb.org/~esr/faqs/smart-questions.html).
+For many open-source projects, where the expectation is that bugs are rare, reporting bugs in a *thoughtful* way can be helpful. See also [How to Ask Questions the Smart Way](http://www.catb.org/~esr/faqs/smart-questions.html).
 
-In this project though, most of the bug reports boil down to the something like: I am trying to reverse engineer some code that I am not the author/owner and that person doesn't want me to have access to. I am hitting a problem somewhere along the line which might have to do with decompilation. But it could be something else like how the bytecode was extracted, some problem in deliberately obfuscated code, or the use some kind of Python bytecode version that isn't supported by the decompiler. Gee this stuff is complicated, here's an open source project, so maybe someone there will help me figure stuff out.
+In this project, though, most of the bug reports boil down to something like: I am trying to reverse engineer some code that I am not the author/owner of, and that person doesn't want me to have access to. I am hitting a problem somewhere along the line, which might have to do with decompilation. But it could be something else, like how the bytecode was extracted, some problem in deliberately obfuscated code, or the use of some kind of Python bytecode version that isn't supported by the decompiler. Gee, this stuff is complicated. Here's an open source project, so maybe someone there will help me figure stuff out.
 
-While you are free to report bugs, unless you sponsor the project, I may close them with about the same amount of effort spent that I think was used to open the report for them. And if you spent a considerable amount of time to create the bug report but didn't follow instructions given here and in the issue template, I am sorry in advance. Just go back, read, and follow instructions.
+While you are free to report bugs, unless you sponsor the project, I may close them with about the same amount of effort that I think was used to open the report for them. And if you spent a considerable amount of time creating the bug report but didn't follow the instructions given here and in the issue template, I am sorry in advance. Just go back, read, and follow instructions.
 
-This project already has an infinite supply of bugs that have been narrowed to the most minimal form and where I have source code to compare against. And in the unlikely event this supply runs out, I have automated means for generating *another* infinite supply.
+This project already has an infinite supply of bugs that have been narrowed to the most minimal form, and I have source code to compare against. And in the unlikely event this supply runs out, I have automated means for generating *another* infinite supply.
 
 The task of justifying why addressing your bug is of use to the community, and why it should be prioritized over the others, is the bug reporter's responsibility.
 
-While in the abstract, I have no problem answering questions about how to read a Python traceback or install Python software, or trying to understand what is going wrong in your particular setup, I am not a paid support person and there other things I'd rather be doing with my limited volunteer time. So save us both time, effort, and aggravation: use other avenues like StackOverflow. Again, justifying why you should receive unpaid help is the help requester's responsibility.
+While in the abstract, I have no problem answering questions about how to read a Python traceback or install Python software, or trying to understand what is going wrong in your particular setup, I am not a paid support person, and there are  other things I'd rather be doing with my limited volunteer time. So save us both time, effort, and aggravation: use other avenues like StackOverflow or ChatGPT. Again, justifying why you should receive unpaid help is the help requester's responsibility.
 
 
 # The difficulty of the problem and your bug
@@ -74,20 +74,20 @@ 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 called `pydisasm`. Using that with the `-F extended` option, generally provides a more comprehensive disassembly than is provided by other disassemblers.
+disassembler called `pydisasm`. Using that with the `-F extended` option generally provides a more comprehensive disassembly than is provided by other disassemblers.
 
 ## Semantic equivalence vs. exact source code
 
-Consider how Python compiles something like "(x*y) + 5". Early on Python creates an "abstract syntax tree" (AST) for this. And this is "abstract" in the sense that unimportant, redundant or unnecessary items have been removed. Here, this means that any notion that you wrote "x+y" in parenthesis is lost, since in this context they are unneeded. Also lost is the fact that the multiplication didn't have spaces around it while the addition did. It should not come as a surprise then that the bytecode which is derived from the AST also has no notion of such possible variation. Generally this kind of thing isn't noticed since the Python community has laid out a very rigid set of formatting guidelines; and it has largely beaten the community into compliance.
+Consider how Python compiles something like "(x*y) + 5". Early on, Python creates an "abstract syntax tree" (AST) for this. And this is "abstract" in the sense that unimportant, redundant, or unnecessary items have been removed. Here, this means that any notion that you wrote "x+y" in parentheses is lost, since in this context they are unneeded. Also lost is the fact that the multiplication didn't have spaces around it, while the addition did. It should not come as a surprise, then, that the bytecode which is derived from the AST also has no notion of such possible variation. Generally, this kind of thing isn't noticed since the Python community has laid out a very rigid set of formatting guidelines, and it has largely beaten the community into compliance.
 
 Almost all versions of Python can perform some sort of code
-improvement that can't be undone. In earlier versions of Python it is
+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
+For example, the code might be:
 
 ```python
 if a:
@@ -113,7 +113,7 @@ else:
 may come out as `elif` or vice versa.
 
 
-As mentioned in the README, It is possible that Python changes what
+As mentioned in the README, Python may change what
 you write to be more efficient. For example, for:
 
 
@@ -150,18 +150,16 @@ The basic requirement is pretty simple:
 
 Please don't put files on download services that one has to register
 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
+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.
+Also, try to narrow down 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
+Some kind folks also give the invocation they used and the output, 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 *uncompyle6* was used. Therefore, if you _don't_
-provide the input command and the output from that, please give:
+and what version of *uncompyle6* 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
@@ -170,69 +168,66 @@ provide the input command and the output from that, please give:
 
 ## But I don't *have* the source code!
 
-There is Python assembly code on parse errors, so simply by hand decompile that. To get a full disassembly, use `pydisasm` from the [xdis](https://pypi.python.org/pypi/xdis) package. Opcodes are described in the documentation for the [dis](https://docs.python.org/3.6/library/dis.html) module.
+There is Python assembly code on parse errors, so simply hand-decompile that. To get a full disassembly, use `pydisasm` from the [xdis](https://pypi.python.org/pypi/xdis) package. Opcodes are described in the documentation for the [dis](https://docs.python.org/3.6/library/dis.html) module.
 
-### But I don't *have* the source code and am incapable of figuring how to do a hand disassembly!
+### But I don't *have* the source code and am incapable of figuring out how to do a hand disassembly!
 
 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 you might consider [sponsoring](https://github.com/sponsors/rocky) the project. [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.) Don't be surprised if I ask you to pay for work (if I think the work is ethical) when you want me to work on your problem that I think isn't of interest or benefit to anyone but yourself or a small limited number of people, or I think the need is questionable.
+If this is too difficult, or too time-consuming, or not of interest to you, then you might consider [sponsoring](https://github.com/sponsors/rocky) the project. [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.) Don't be surprised if I ask you to pay for work (if I think the work is ethical) when you want me to work on your problem that I think isn't of interest or benefit to anyone but yourself or a small, limited number of people, or I think the need is questionable.
 
 # Narrowing the problem
 
-I don't need or want the entire source code base for the file(s) or module(s) can't be decompiled. I just need those file(s) or module(s). If there are problems in several files, file a bug report for each file.
+I don't need or want the entire source code base for the file(s) or module(s) that can't be decompiled. I just need those file(s) or module(s). If there are problems in 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
+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
 the functions or classes. So please chop down the source code by
-removing those parts that do to decompile properly.
+removing those parts that do not decompile properly.
 
-By doing this, you'll probably have a better sense of what exactly is
-the problem. Perhaps you can find the boundary of what decompiles, and
+By doing this, you'll probably have a better sense of what exactly the problem is. Perhaps you can find the boundary of what decompiles and
 what doesn't. That is useful. Or maybe the same file will decompile
 properly on a neighboring version of Python. That is helpful too.
 
-In sum, the more you can isolate or narrow the problem, the more
-likely the problem will be fixed and fixed sooner.
+In sum, the more you can isolate or narrow the problem, the more likely the problem will be fixed and fixed sooner.
 
 # Karma
 
 I realize that following the instructions given herein puts a bit of
 burden on the bug reporter. This is justified since it attempts to balance
 the burden and effort needed to fix the bug with the amount of effort to report the problem. And it attempts
-to balance number of would-be bug reporters with the number of bug
-fixers. Better bug reporters are more likely to move in the category
+to balance the number of would-be bug reporters with the number of bug
+fixers. Better bug reporters are more likely to move into the category
 of bug fixers.
 
 The barrier to reporting a big is pretty small: all you really need is
-a github account, and the ability to type something after clicking
+a GitHub account, and the ability to type something after clicking
 some buttons. So the reality is that many people just don't bother to
-read these instructions, let alone follow it to any simulacrum.
+read these instructions, let alone follow them to any simulacrum.
 
 That said, bugs sometimes get fixed even though these instructions are not followed.
 
-I may take into consideration is the bug reporter's karma.
+I may take into consideration the bug reporter's karma.
 
-* Have you demonstrably contributed to open source? I may look at your github profile to see what contributions you have made, how popular those contributions are, or how popular you are.
-* How appreciative are you? Have you starred this project that you are seeking help from? Have you starred _any_ github project? And the above two kind of feed into ...
+* Have you demonstrably contributed to open source? I may look at your GitHub profile to see what contributions you have made, how popular those contributions are, or how popular you are.
+* How appreciative are you? Have you starred this project that you are seeking help from? Have you starred _any_ GitHub project? And the above two kinds of feed into ...
 * Attitude. Some people feel that they are doing me and the world a
-  great favor by just pointing out that there is a problem whose
-  solution would greatly benefit them. (This might account partially
-  for the fact that those that have this attitude often don't read or
+  great favor by just pointing out that there is a problem whose solution would greatly benefit them. (This might account partially
+  for the fact that those who have this attitude often don't read or
   follow instructions such as those given here.)
 
 
 # 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 of the little that
+code and the bytecode. However, I would imagine that if you have
+narrowed the problem sufficiently, the confidentiality of the little that
 remains would not be an issue.
 
-However feel free to remove any comments, and modify variable names
+However, feel free to remove any comments and modify variable names
 or constants in the source code.
 
-If there is some legitimate reason to keep confidentiality, you can contact me by email to explain the extenuating circumstances. However I tend to discard without reading anonymous email.
+If there is some legitimate reason to keep confidentiality, you can contact me by email to explain the extenuating circumstances. However, I tend to discard without reading anonymous emails.
 
 Private consulting available via https://calendly.com/rb3216 rates: $150 for 30 minutes; $250 for 60 minutes.
