How to structure the tutorial's chapter progression

[Rangi42]

Some of my recent issues and PRs, in particular #146 and the disagreement around when to introduce the relative-jump jr instruction, have sparked some broader discussion about the vision for what the completed tutorial will look like, and what sort of concepts it's meant to teach people.

Not to put words in @ISSOtm 's mouth, but my understanding of his long-term plan has been:

1. The "Hello World" project is meant to teach the minimum of concepts necessary to get something working on-screen in an emulator. That includes of course setting up your toolchain, as well as just enough SM83 and RGBDS material to get some static graphics. It doesn't have to be idiomatic code, it just has to build and run.
2. The subsequent two games are meant to teacher better habits -- although they were planned to do so by doing things "wrong" non-idiomatically/inefficiently at first, which provides motivation for why better approaches will be used later, even if those better approaches are more complicated or difficult.

Personally I don't want to count on a long-term plan being successfully executed, and would rather make some smaller changes in the near term, with the goal of teaching more idiomatic code right off the bat:

1. I would introduce more concepts even in the "Hello World" project. The default main.asm in rgbds-live demonstrates most of them (jr and local labels in particular -- not actually call+ret, initializing sp and using the stack is too much complexity at that point, that's fine where it is in the Unbricked project). I would also at least consider introducing INCBIN and RGBGFX, even if it has to be manually invoked to create the graphics files, because it's just too cumbersome and unidiomatic to deal with dbed graphical data.
2. I'd like a structure of "odd chapters introduce a project, even chapters review and polish it". So Chapter I can stay as a jp-only, global-label-only, minimal project, just for the sake of getting something on-screen; but then Chapter II would critique its code and introduce better concepts right away, before the worse alternatives have set in as bad habits. And that way, the subsequent Unbricked and Galactic Armada projects would be able to use jr, .locals, etc, without having to pause and explain them.
3. Overall I want to teach as much as possible about basic SM83 and RGBDS stuff in the "Hello World" step, since it's a small toy project where the focus is on the assembly syntax itself. Then the whole-game projects can focus on larger issues, like how to deal with multiple files in a game project, how to keep updating frames based on player input, what BG and OB graphics are for, etc.

(Well, "I want to teach" is overstating it -- I am not interested in becoming an indefinite long-term maintainer for the whole gb-asm-tutorial. I think there's an opportunity here for some targeted finite changes to the existing structure, which would leave the existing "incomplete" tutorial better as a resource for teaching the sort of code that you actually see in real projects, and would hopefully make it easier for more authors to contribute to the tutorial, since they don't have to abide by so many restrictions around what hasn't been taught yet.)

[Rangi42]

@ISSOtm Given that you were positive about this when we discussed it, I'd prefer to leave the initial steps to you.

Basically:

• Revising Chapter I to trim the "extraneous detail" (as per Document the jr instruction and use it in hello-world.asm #151 (comment)).
• Inserting a new Chapter II where the Hello World project gets revised one step at a time to be more idiomatic.
• I didn't have any ideas about Unbricked or Galactic Armada anyway, but those two points would provide a basis for anyone else who comes along and wants to similarly add a "look back on the game we made and fix its pain points with more advanced teachings" chapter after either of those.

[Rangi42]

@avivace @ISSOtm Please note that I don't plan to be making these changes myself right now, because I don't think I can usefully contribute to gb-asm-tutorial in its current state. We have policies and expectations around how "maintainers" are responsible for approving PRs and being given time to do so, but as far as I can tell, the maintenance of gb-asm-tutorial is undefined.

• Is ISSOtm a maintainer, or just the original author who's no longer working on it?
• Is avivace a maintainer, or just someone involved with gbdev in general and its other projects (like me with rgbds, hardware.inc, etc)?
• Is quinnyo a maintainer of the whole repo, or just a contributor to the Part II for Unbricked?
• Are any other recent committers maintainers? For the whole tutorial or even just for their authored parts of it?
• Is anyone even actively maintaining gb-asm-tutorial, with a long-term view for how it should be improved? Or do we all just have mild interest/engagement with it at this point? (I know ISSOtm had/has such a long-term plan when the project first started, but besides the spike of commits in December, it's been mostly left alone for the past year.)

Right now I do not know what long-term vision I should be targeting when making changes, because I suspect there isn't one, or that the contributors have disagreements about it. And if the contributors disagree about changes I propose or PR, it's not clear to me who's actually able to respnsible for rejecting and closing it (or dismissing the disagreeing comments and approving it). (Yes, @avivace and I both technically can merge on our own; this is a question about governance/responsibility being confusing.)

I don't want to start fights and drama, I want to contribute to a better tutorial, that we have a consensus on as far as what counts as "better".

[avivace]

For the past two years, I’ve been the only active maintainer of gb-asm-tutorial. We’re looking for additional maintainers: people with an established contribution history who are willing to take on ongoing responsibility.

Over that time, contributions have continued to come in, and I’ve worked to ensure they don’t get lost: triaging, assigning bounties, and moving changes forward. Sometimes that has meant merging solutions that aren’t perfect yet, with the expectation that we can iterate on them later.

ISSO explicitly asked to step back from any responsibilities due to burnout and other commitments they couldn’t sustain. Their vision often broadened the scope of work, which led to open-ended, unmanageable efforts driven by unrealistic and frequently non-actionable objectives. They then disengaged after introducing additional constraints. I don’t want this to happen again (nor want to provide additional sensitive details about their situation).

We don’t have the resources to pursue that broader (irrealistic, IMO) vision without repeatedly draining contributor motivation and turning routine contributions into blocking meta-discussions.

While we seem to have plenty of capacity to write long descriptions of what the tutorial should do, we don’t have the energy to turn those into concrete, actionable, contributor-friendly tasks. I don’t want to discourage the former, but I also don’t want it to become a constant, unmanageable backlog that drains momentum and stalls progress. This was the case in the past and I invested a great quantity of time to make sure we kept moving, adopting a different approach.

If the discussion doesn’t translate into a practical contribution - or isn’t followed through by the author with the work needed to realize/enable that vision - then it shouldn’t block the contributions we’re already making. It can continue in parallel, but not as a gate on progress.

This is exactly the shift toward a more pragmatic approach: merging changes more quickly and more frequently, while clearly documenting any known shortcomings or needed follow-up work. The goal is to keep momentum, avoid turning every contribution into a prolonged debate, and prevent incoming interest from stalling out or losing motivation. The tutorial has a moving target and we're figuring things out as we go. It is now a community project, and it’s essential to keep it approachable, tractable, and easy to contribute to for the widest possible audience.

Write/repo roles unfortunately aren’t updated very often, so gb-asm-tutorial likely started out with the RGBDS maintainer group by default. In practice, I also already have enough trusted people with write access to handle emergencies.
Going forward, I’ll start adding a MAINTAINERS.md file to each repository to make roles and responsibilities explicit.

Please also note that I have no interest whatsoever to engage in this drama any further.

[Rangi42]

I came across Modern Java (via lobste.rs), which may be useful for borrowing some structural ideas.

In particular:

• "Lies": "If there are five ways to do something, I might pretend that there is only one way to do it until I give you enough context so that I can talk about the other four." This is basically the approach that I understand @ISSOtm originally planned for gb-asm-tutorial, and although we might not want to take that approach any more, we'll probably have to have some level of simplification/omission to teach the basics.
• "The Terminal": Given how important tooling is, and how unfamiliar POSIX/WSL will be for a lot of Windows users in particular, I like the idea of devoting a whole chapter to it. We could at least find a third-party tutorial to vouch for and link to, so ls and cd and "typing commands into this weird black-and-white hacker-esque notepad" don't confuse people too much. (I've linked to LinuxCommand.org before, but maybe there's a better one.)
• In general, having more smaller sections might be a good idea. Like a whole one just for "Comments", which would give us an opportunity to explain when they're useful (and when they're not, e.g. add a, 5 ; adds five to a). Pacing sections more slowly like that would IMO make it easier to cover more material overall. The "Assembly basics" section could especially be broken up.