Patrick Hurley Monogame Documentation Fix
What is MonoGame?
For my contribution, I decided to contribute to the MonoGame game engine. MonoGame is a framework built off of Microsoft’s now deprecated XNA Framework, and has been used to create many titles such as Celeste, Stardew Valley, and Barotrauma. I decided to contribute to MonoGame because I’ve used it before, for a group game project I made in my freshman year, giving me some familiarity with how the engine works. It also has a large amount of issue labels for easier categorizing and searching, with “Good First Issues” being the one I primarily used.
Mini Comm Arch evaluation
MonoGame is a large and active repository comprised of a few dedicated multi-commit contributors and a large volume of drive by contributors. The project’s code of conduct is both easy to find and easy to comprehend, and the community as a whole seems very kind. The project itself is growing in popularity, too, and is run as a Federation.
Choosing an Issue
To find what issue I wanted to contribute to, I first checked the issues under the Good First Issues label, and settled on Issue #4856 because it seemed like it wouldn’t require an obscene amount of time to fix.
Little did I know, it also required knowledge of 3d transformations and matrices, which were the one topic in calculus that I almost failed. Not really understanding what the issue actually required me to document, I had the idea to look for other documentation-related issues, as I had already read every issue marked Good First Issues, and at the bottom of the conversation under Issue #4856 was a link to a project in the repository named Improving the documentation and samples. Looking through the issues there, I found Issue #4804, which is about writing documentation for a bug concerning how MonoGame’s vsync settings interact with end user graphics driver hacks that can force different types of vsync.
How was it ‘fixed?’
As the issue I chose was related to writing documentation for an already discovered and diagnosed issue with graphics card drivers, I didn’t have much to actually code myself. I updated the <remarks> tag inside the comment for the SynchronizeWithVerticalRetrace method to specify that it could cause issues like multiple update calls per draw call, and that was it. Then came the roadblock. Or at least, the part I way over-analyzed, only to find out it was all unnecessary.
I had the changes in code pushed to my fork, but I wanted to know how to get those changes reflected in the project’s documentation too, so I went there. First I checked the readme of the documentation repo, which strangely didn’t link to the repo’s contributing page. Because I didn’t know the repo had one, I spent the next hour looking through the code in the repositiory trying to find out what I would need to change to add my part to the documentation, also checking the framework that the documentation was built off of, docfx. Still couldn’t figure it out, until I noticed the contributing.md file tucked away in the root folder of the repo, which mentions that the documentation is automatically “rebuilt when the code changes and is published nightly to the website.” So that was a fun way to spend an hour. After that, I made a pull request, and within a day recieved an approval from one of the project’s maintainers and most active contributors, dellis1972.
As of April 9th at 6pm, my change has not yet been merged into MonoGame’s development branch, and judging by how old some other pull requests are, it’s anybodies guess how long it may stay that way.