The Code Can't Be Wrong

How often have you heard "the code is fine, must be your setup"? Or perhaps you yourself are working on a "bug" 🐞 but every time you run it, it works. How could this happen? What can we do to stop it?

What Can Maintainers Do?

Dev Setup Scripts

Pick your poison. Chocolatey, Scoop, apt,HomeBrew, pip, npm, or yarn the package manager doesn't matter as long as it works across the target platforms And includes the build tools it should do fine. A reproducible setup script removes the possibility that someone is using the wrong version of a build tool or has a configuration set wrong.

But what if the setup script fails? It happens, and I've had it happen to me. But luckily we have the script itself to see what should be done and how. Using that we can work through the setup manually.

I had an issue a while back with a Silverlight project that required a specific installation order of plugins, SDK's and proprietary client libraries with license managers. Any of this was done without the proper reboots, in the wrong order or with the wrong update installed and it would never work. Setting up a new Dev environment took days of trial and error then updating the documentation with anything that the previous victim had forgotten to list. It was dreadful and costly.

There are pitfalls a plenty in this route, but the rewards are great. You're dependent in part on shiver maintains the scripts for those tools and problems on individual machines can still cause issues if they have residual configurations or cache problems.

Build Scripts

So the dev environment is setup and I have the code opened. But the executables aren't getting created when I build?

A good build script, whether created by your IDE or hand written, is a lifesaver when it comes to building software. My first forest into .Net was filled with people expecting me to know that I needed to copy files from A to B or a lot of the features would crash the application without so much as a log file or event viewer entry. These were a set of pre-req files referenced by the code but not copied to the output for various reasons.

That's not good. It makes it harder to onboard new developers and it takes longer to produce working builds from a fresh dev environment. It used build scripts (project files) but specific requirements for a working build were documented but only as a manual requirement.

Use CI/CD

Developer tests their code, confirms with QA that their tests passed as well and pushes it up. Release starts and...💥

Forgetting to commit a file, or not building in the right configuration could cause unforeseen problems that can't be tested in the same environment that authored the changes. A good CI/CD setup will fail tests or fail to build/deploy if these problems occur.

Deterministic Builds

Package managers such as Yarn, npm, or NuGet do not always pull down the exact same dependencies. Using a build system that always resolves the same way will go a long way to help reduce unexplainable build issues and unexpected end user issues.

Yarn provides an options like Zero-Installs that prevent any changes to dependencies before building. This way you know the versions you tested are the same as the ones that get deployed.

Write The Manual

Good documentation can cover a lot of problems as a last resort. Listing environment dependencies and advice for troubleshooting both the dev environment and the usage of the software will go a long way towards helping them help themselves.

What About End Users?

End users may often get the short end of the stick here. The developer may have done everything above and you still have an issue they can't reproduce.

Read The Manual

Documentation is often forgotten and neglected but there is little to wonder about when many forego reading the supplied documentation before filing a bug ticket or reaching out to support. Many times reading the documentation or even a spelunking through the code can lead you to an answer that lets you fix the issue or file a ticket that makes the fix trivial for the maintainers.

Clean Environment

If possible, test the problem you have in a virtual machine that had just been setup using the instructions from the maintainer. This way you can even build the tool yourself (hopefully using the build scripts provided by the maintainer).

If you don't know enough to build their project (they probably didn't read the sections above), then you will at least be able to test it in a fresh OS untainted by your normal setup.

If you don't have a virtual machine or can't set one up, try on a different computer. Compare them and see what the difference is. Sometimes it's as simple as realizing your desktop is on a different subnet or that your laptop isn't on the domain.

Be As Verbose As Possible

Sometimes the problem isn't related to the environment. It could be a miscommunication. Giving as much detail as you can about what the error is and what you are doing when it occurs will help them to reproduce edge case issues that they aren't testing for. They may not even consider it a use case at all.

The worst thing that can happen is you report a bug and either side just stops responding. Constant pestering with no additional details isn't helpful either.

Try listing:

• Current version you are using
• An example (video, gif, code snippet).
• Other methods of attempting the behavior
• Other versions of the software tried
• Any errors or logs that you can find that seem related