Beta Testing Harmony
We need your help!
Harmony v2.3-prerelease.2 is the first public test release of Harmony. Although each community does their own testing, this page tries to outline the focus of what testing is needed and how to give feedback on it.
Normally Harmony is pretty good in maintaining backwards compatibility but sometimes bigger changes are unavoidable and introduce bigger risks of regression (read: to break things that worked before). That's when a pre-release comes in. Its purpose is to give a group of people access to the new version without involving all users at once. The pre-release should be used only up to the point where it is replaced by a new pre-release or the final version.
To make this process as smooth and effective as possible, this page tries to document three things:
- the changes in Harmony
- the purpose and focus of testing
- how to use the new release
- how to best report problems
Thank you for your cooperation and time. Open source can be a challenge but if everyone helps a bit things are very much managable.
Why are we testing Harmony? The answer is that since a while ago Harmony has moved the low level patching job to a shared dependency between it and the MonoMod team. That team has recently reorganized their code and rewritten a large portion of their solution and their utility functions - of which Harmony uses what was called MonoMod.Common. That dependency was responsible for doing the low level tinkering with assembler code for patching methods at runtime.
That dependency was now refactored to offer more flexibility in patching, especially newer .NET versions and support for more modern concepts like re-jitting. Lots of technical details that for the purpose of testing don't matter much. The problem that we are facing now is that these changes can break things we don't know yet. In this release, the public API hasn't changed much so its all about making sure everything still works as before - or better.
For more details on the changes, please visit the Harmony v2.3-prerelease.2 page.
While the code base is tested in Azure on many platforms, there is a clear risk of Harmony not working on some combination of OS (Win, Mac, Linux), .NET version (net35 - net7) and processor architecture (x86, x64, arm, 32bit, 64bit).
Therefore, the focus should be on exposing Harmony to as many patch scenarios as possible on as much different hardware.
Installation is pretty simple: simply replace the old Harmony lib with the new one as a runtime dependency. It should be API compatible. For example, in RimWorld it comes with a new version of the Harmony mod (which bascially does nothing else than to contain the Harmony library). Simply installing it offline and replacing the normal version is good enough.
Download HarmonyMod and install it according to the usual mod structure. For RimWorld, it will show in the upper right corner like this:
If you find abnormalities or want to report/discuss problems then there are a couple of ways to do that:
- File an Issue in the Harmony repo
- Join the official Harmony discord and write about it in the beta-testing channel
- If you have a local test group, make sure I (Brrainz) am member and report the problem there
- Send me an email (only if there is no other way)
Make sure you add as many technical details as possible:
- Hardware: processor architecture + operating system
- Harmony version
- .NET version (Runtime!)
- Which game
- Stacktrace and/or logs
- For hard crashes the crash log
If your time allows it, try to create a minimal test case that reproduces the problem. This step is essential!