Development process

[bdarcus]

Another premature detail, but wanted to document what I've been thinking if this does make it beyond the experimental stage ...

With CSL 1.0, it's been extremely difficult to figure out how we make changes. Among other things, we have no idea if anyone will implement a given change to the schemas, if we make it. And because we don't know that, we also don't know if the technical details are properly vetted.

My thought for this is to exploit github workflows and reviewer rules so that the typical way a feature would be submitted for consideration is via a PR, perhaps linked to a preceding discussion or issue that establishes the validity of the use case and the technical requirements.

Those PRs would include documented code and test coverage.

Upon approval from N reviewers, and subsequent merging (and maybe tagging), github workflows would automatically publish updated:

1. documentation (including changeglog)
2. schemas
3. code (crates)

I have not figured out exactly the style end of these updates, and there could be some technical difficulties there because of the static nature of Rust, but it would be based on the same idea.

So updating of code and documentation would happen through github-based automation, controlled by maintainer decisions as reflected in github review approvals and git tags.

Ideally here, you'd want approvals from people who are in the domain expert realm (for basic logic, use case relevance, documentation, etc.), and programmers with rust expertise on the other for the code.

In this workflow, reference code, schemas, and documentation would always be in sync, and the time and effort required to keep them so would be minimal.

PS - This is kind of like how the neovim tree-sitter project seems to work, where they have a requirement for two reviews, and the first approver requires, it seems, the (specific?) second reviewer.

PS 2 - perhaps Rust's notion of project goals and editions might also have some lessons? A video of a talk on this:

https://www.youtube.com/watch?v=7YjomcXNvTk

[Jason-Abbott]

@bdarcus the process you’ve described has been fairly standard at places I’ve worked, implying it should be approachable for typical devs. I don’t know every detail you’ve alluded to but using GitHub actions to execute arbitrary scripts (to include Docker with some Rust) to generate artifacts is also typical in my experience.

I will take a closer look at your work here. I’ve perused it a few times but not enough to get it all into my head.

[bdarcus]

Yep, @Jason-Abbott.

I think what's a little unique here, that we've been struggling with, has been that schemas, code, specification, and styles are developed independently.

The idea I have here is to merge them all (aside from the styles) in the code.

Hence, for example, the little csln-schemas binary will generate JSON schemas from the code.

But it also makes it nicely suitable to the sort of workflow automation.

It's crazy what's been involved until now for really minor changes.

No doubt the workflow question is somewhat orthogonal to the other technical questions, but I do think they overlap a fair bit.