The road to a more reliable Semagrams

[olynch]

Semagrams has gone through a lot of iteration and prototyping, and that's a good thing. But as Semagrams moves from being research software to being something that people actually use, we need to start investing not just in new features, but in stability.

There are three things that we need in order to do this.

1. API definition.
2. Tests
3. Documentation

Ultimately, the thing that matters to the user is documentation. However, documentation is not useful unless there is some guarantee that it won't be out of date. This guarantee is provided by tests. But we don't want to write tests that we will have to change immediately; we want tests that test the "external interface" not the internals. Of course, we also want to test the internals, but in a way that is less important.

Thus, the natural flow of things is APIs -> Tests -> Documentation.

Currently, Semagrams has a lot of fairly powerful APIs. The problem is that they aren't very cleanly segmented out, because as apps have been developed the "quick and dirty way", we have "pulled through" APIs and exposed the seemy underbellies.

So what we should do is look at the apps that we have, and think about the APIs that we need to "cleanly serve" these apps.

The first step in this is to list out the APIs we have:

• ACSets API
• Sprites API
• EditorState API
• Viewports API
• Generic UI API
• Actions/Bindings API

One thing to think about too is that right now core is a mix of general APIs and things that use those APIs. For instance, we have the Sprite API, and then we have some concrete Sprites. We have the ACSets API, and then we have some concrete ACSet schemas. It might be worth separating those out somehow, into separate packages or something else.

The next step is to figure out how to cleanly test different parts of this.

The ACSets API is the easiest to test, because it doesn't use any Laminar or IO stuff. The parts that use Laminar or IO are much trickier to test. Perhaps Daniel Filonik has experience with how to test UI?

We can mock the browser using Selenium or similar, but it would be best to be able to test different parts of Semagrams in isolation, rather than running an entire Semagram and then simulating keyboard presses and mouse clicks. It would be good to have a coherent way of doing this.

Finally, we need to write documentation for all exposed functionality. Of course, we already have generated API docs, but we should have something like Laminar's documentation, which walks through all of the functionality in a coherent way.

Of course, this all is an iterative process; although the logical order is API definition -> Tests -> Docs, we will of course be cycling through different parts. It may be helpful to pick a part of the codebase and go through the whole process end-to-end, so that we can see how it works; perhaps Actions/Bindings would be a good place to start.

Please comment with thoughts, and things that you would be interested in helping with.

[lukem12345]

I volunteer as a guinea pig/ reviewer on whatever docs are produced. I would like to be able to create/ edit/ visualize Decapodes from Decapodes.jl via a web app at some point. I can give feedback on where I find hangups in attempting this. I think just a quick “overview” to serve as starting point would be fine for such purposes.

If it would be helpful, I can find time to sit in on some test-writing to get some familiarity, if that must come first.

Let me know what you think!

[olynch]

Excellent! I'll send you an invite to the next Semagrams dev meeting, and we can talk then.