Additional Developer “Getting Started” Documentation

[Snowleopard-osu]

Describe the new feature:
Adding some extra documentation and overviews of the codebase to make it easier for a new contributor to jump in without spending a lot of time blindly sifting through code. What is being looked for here is more general diagrams and/or descriptions of the stack, how code is organized (ie which groups of files do X, and where to look when wanting to make changes to Y), and other helpful suggestions on getting started.

This is being requested to aid developers who are newer to this project and/or who don’t have the free time to carefully analyze the entire codebase just to get started.

Proposal designs of the feature:
There already are some good diagrams such as Gameplay Clocks and Hitobject sample lookups but obviously these are on fairly specific topics. Additional diagrams like these both about other specific topics and (more importantly) the general stack as a whole would be great.

This request is for all of lazer/the codebase as a whole, but also I am personally interested in contributing to the Lazer Tournament client, so it would be awesome if some consideration could be made there as well when making this documentation.

[frenzibyte]

You don't really need to analyze the entire codebase, I personally believe there are two things enough for a new contributor (who of course knows C# and has a basic knowledge of game development) to get familiar with osu!lazer codebase:

1. reading the osu!framework wiki to understand where osu!lazer runs from (read Getting started section) and having good knowledge on developing games with osu!framework. (e.g. input handling, screens and screen stacking system, layout system, debugging and logging, visual component testing, etc...)
2. then having a couple of reads on osu!lazer codebase with the knowledge gained from osu!framework wiki to understand how specific things work in osu!lazer and having simple knowledge on them (doesn't need to take long, the familiarizing part comes mostly from fixing simple first issues).

after that, all that's left for the new contributor is reading on the https://github.com/ppy/osu/issues?q=is%3Aopen+is%3Aissue+label%3Agood-first-issue list as a good start and attempt fixing them, by debugging on the relevant parts of the codebase, understanding what's wrong, attempt fixing, testing by adding a test method case in the relevant test scene, or create one if there's none, and finally PR the fix.

[bdach]

While I can sympathise with the feeling of being daunted with the codebase at first (and there are things that need more documentation, especially framework-side), I don't think the current state is so bad that you would have to "blindly" look through code to find some place. Namespacing, string searching, looking at tests should all help locate the particular area you are looking for with relative ease. Those are generally the best techniques when coming into a codebase of this size; you shouldn't be looking to instantly be productive.

The thing with documentation is that it comes with an upkeep price. The project is slowly transitioning out of the rapid phase of development, but that phase is not over yet. Having docs detailed to the point you seem to desire comes with a significant upkeep cost, and I'd argue that it's impractical in the long term with the resources that we have. (I'm also skeptical as to how much diagrams are worth, but I suppose that's a personal opinion.)

Also, as mentioned in the contribution guidelines, you are free to ask for advice both in issue threads and on the osu!dev discord.

[Snowleopard-osu]

Yea that is true, I suppose I should have worded it more as a list of good things to document and request that some pieces to be selected. My goal wasn’t suggesting a full detailed documentation of everything, just some key overviews to jump start the process. I did eventually find the framework page which does actually have some good information there, perhaps a good start would be to add a more clear link of that to the project readme.

[bdach]

Framework-side there is an issue open tracking areas that need more docs (ppy/osu-framework#3233). I guess this could be one for the game itself if needed.

[peppy]

It would be helpful if you mention exactly what you were struggling to find so we can either add xmldoc or point you in the right direction.

[Flutterish]

As someone who jumped blindly into the code to make a ruleset all my issues were resolved by just F12ing to understand how a given group of classes work. Not that docs aren't useful, but I believe the current naming is sufficient to quickly understand how the code works.

[Snowleopard-osu]

What I was looking for was something similar style to this diagram from k3s.io

Obviously osu and a kubernetes cluster are nothing alike, but that general idea of “here’s all of the main components, here’s how they all fit together in the bigger picture”.

I think the documentation in osu-framework does cover a lot of this material, but at time of original post I hadn’t stumbled across it yet. Partially because it’s in an entirely separate project, but also because the link to those doc pages from this project is buried a few clicks deep. As a quick fix I think the link to those docs could be added to the contributing or development section of this project’s readme. However, it still would be nice to have a diagram similar to the example I gave above.