Posting Checklist

From OSDev.wiki
Jump to navigation Jump to search

Many questions on the forums are not answerable straight away due to a wide variety of reasons. It is in part a nature of the subject - remember that in OS development everything depends on everything and small errors in the foundations can mean huge untraceable problems in later stages. A lot of the queries are however quite preventable.

Trivialities that get bugs fixed

Things that give apparently random results are typically the result of one of the following:

  1. Your build calls "gcc" and/or "ld". That's not how you should use a compiler. Sadly, this practice also breaks several tutorials in the wild.
  2. You are using outdated versions of Bochs or QEMU. In particular, do not use the versions bundled with your Linux distribution.
  3. You forgot to check the VM log. Especially in the case of Bochs, the exact error cause is often printed in there.

When you ask

  1. Currently, one out of five new people blatantly violates the forum rules on the first post, and for roughly half the newcomers it is questionable if they have actually read it instead of acting on autopilot. Don't waste our time, or more importantly your own time: it contains all sorts of pointers, including a few that might answer the question already.
  2. Don't guess anything. Stick to the facts. If you have pending questions that prevents you from understanding what you are doing, consider making the initial problem the background story to your lack of understanding.
  3. Include the name and version of the emulator(s) and virtual machine(s) you are using. Mention your architecture (protected mode, long mode, raspberry etc), and whatever bootloader you are using.
  4. Do mention any noticeable differences between different VMs and real hardware. Your OS should work the same everywhere and these things are important cues.
  5. If you run your code in a VM, show any log lines produced by your code.
  6. Reduce the code to the smallest set that exhibits the bug, and post it. Don't waste a day for a query from us to "post your code" when you could have done it straight away. Translate where applicable.

After replies

  1. Don't blindly follow suggestions. Learn what they are meant to do.
  2. There might be multiple issues with your code. Fix them all, and ask for elaboration on all comments you don't understand. Sometimes you need to fix more than one thing to get it working, and sometimes one thing might not contribute right now, but it might be an issue later. This also has another effect, caused by the fact that many software developers are inherently trained to stop reading after the first bug they encounter. If your code has several (possibly minor) issues, you'll only get the first few issues, and not the ones that matter the most at that time. until you do follow up and explain what you did and that it still doesn't work.
  3. There are a lot of people trying to help, but you'll find that some people post arbitrary suggestions based on their own lack of understanding. Again, if you don't understand why, you are better to question the suggestion for elaboration and understand what's really happening.
  4. Be courteous and write a brief summary of what you've learned.