Improvements to source control integration

I am part of a team working on TLA+ modelling, using git for coordination. There are a number of things that TLA+ and/or the toolbox do that get in the way of this workflow a bit, which largely boil down to a lack of clean separation between source and generated ones.

This is kind of a meta-issue since it covers a handful of different things. I thought it better to open one issue covering all of the below than four separate issues, because I think subsequent discussion will cut across them all, but I can break it down to separate task-based issues if that’d be preferred.

Source and generated files share directories

We have arrived somewhat empirically at a .gitignore file that works ok as long as all of our models are called model, but it would be much preferable if all the files we did want to ignore were in a single directory.

PlusCal translation modifies its own source file

We don’t always use PlusCal, but when we do it works well to commit just the changes to the PlusCal code meaning that reviewing the commits is easier. This is a bit of a pain at commit time as it requires extra effort to avoid committing unwanted changes. It’s particularly tricky if one changes something below the translated code (e.g. an invariant) as tools like git add --interactive work through the changed hunks in file order.

It is also easy to forget to do the final translation before merging. Ideally we wouldn’t need to commit any translated code, as it would be considered “generated” and stored in the separate directory mentioned above.

Modification history by default

A very minor thing is the Modification History footer comment that’s included by default. Yes, you can delete it and it doesn’t come back, but is it really necessary at all?

Readability of model description

It’s nice that there’s a GUI for defining the model, but when we’re reviewing changes we look at diffs. Fortunately it’s not completely unreadable and a bit of experimentation is enough to work out how to parse the model parameter definitions, but it’d be nice for reviewers if this file were more readable.

[DaveCTurner]

Generally, the reasoning seems upside-down here. Source control management is an auxiliary tool to simplify the life of software engineers, not dictate how (programming/specification) languages should be designed.

I hold a different viewpoint. SCM is a tool, but so are programming & specification languages; both are important, and neither is above the other in terms of influencing their respective designs. Working as well as possible with other tools in the ecosystem is an important feature to me, which is why I opened this issue instead of just living with it. It is definitely an unusual design to mix source and generated code in a single file (vs, say, combining them in the UI) but it’s not unusable, and I can see why it might be preferred in some workflows.

[lemmy]

For the (common?) case in which the TLA+ is not being modified by hand I would find it very useful if it could just do the transpilation step automatically in this case, rather than raising a warning.

The Toolbox editor supports on-save transpilation since the 1.5.7 release.