Dev Home

This page is a place to accumulate dev tips, setup guides etc. in an easily editable format. Feel free to add stuff!

If you haven't seen already, please see our general org-wide contribution guidelines.

We're very friendly and happy to give a hand to any potential contributors on our Discord, including any Git-related headaches. Just give us a shout in #tooling, and feel free to ping me (Tom @fingerprince) on Discord.

Avalonia & ReactiveUI

The Lumper.UI project is a significant step up in complexity compared with the rest of the codebase. Avalonia introduces XAML-based layouting, which is hopefully relatively intuitive has its quirks like Data Context and downright spooky stuff like the View locator. If you don't have any experience to Avalonia I'd suggest checking the ToDo List App tutorial on Avalonia's docs, for a gentle introduction, then taking a look at our codebase.

The scarier thing to get to grips with is ReactiveUI. This is what provides all the [Reactive]/then.WhenAnyValue observable stuff looks like magic/nonsense if you've never seen these kinds of programming patterns before. If that's the case, that's completely okay! "Reactive"/"functional reactive" programming is paradigmatically different from conventional C#, and is takes some getting used it. Reactive programming is basically about extra-spicy events. Rather imperatively call functions that call other functions when something happens in the program (say a user clicks a button), you describe how the effects of changes in one part of program state effect others, by treating the changes as streams of notifications and tying them together in a network. Thus you'll often see viewmodels compromised on a bunch of reactive properties (i.e. properties that emit change notifications when their setters are called), then a fuck-off massive constructor containing a bunch of observables chains (see e.g. EntityEditorViewModel), and nothing else in the class.

If this is all total new to you, and you want to get actively involved in the UI parts of Lumper, I highly recommend reading up on reactive programming a bit first. I've not read the whole thing, but Intro to Rx.NET seems very solid, I recommend that over the related MSDN pages. Once you feel like you have a grasp on that (don't worry if you don't feel super confident - this stuff is hard!), check out the ReactiveUI docs. Their "handbook" is very good, but the pages aren't ordered. Whilst you don't need to read everything in great detail, I'd check out these pages, in these order:

• Intro/"Compelling Example"
• WhenAny
• View Models - note our ViewModel class is just a alias of ReactiveObject!
  • View Models - Boilerplate Code - what the spooky [Reactive] and [ObservableAsPropertyHelper] attributes are doing
• Data Binding
  • Data Binding - Avalonia - Avalonia has its flaws but its excellent support for ReactiveUI is a huge perk
• Collections - If you get this far hopefully our codebase starts to make a lot of sense. Things like our lump viewmodels e.g. EntityLumpViewModel are all about managing a SourceList/SourceCaches of the underlying BSP model.

Again, this stuff is complicated and a lot to get into if you're not familiar, don't worry if it makes no sense at first. Reactive programming/observables took a good while to click with me at first, but having mostly gotten the hang of it, I absolutely love reactive programming. It's also really nice that many of the core ideas here are shared with Angular (TypeScript web framework) which we use for our frontend (dashboard) site. Please feel to reach out to me (Tom) in Discord whenever if you want a hand, I really enjoy teaching this stuff.