Updated this to reflect new structure of the repo. Also made sure tehre is no duplicate info in top level README.

Here is dope.sh, the main logic for diffing / patching.

It is written in such a way that it can also be used in other places, it is generic.

Helper wrapper for patching.

Helper wrapper for dope.sh for diffing.

The wording here is kind of confusing to me, after all, this is the Open SaaS template, right?

What about changing it to:

"This is the Open Saas project directory, which consists of template itself (app), as well as two other dirs (blog and e2e-tests1):

1..."

?

ok, I see. you're creating a template README for their future app.

Ah yes! So this is the README they get when they create the new app using the template: README for that app.

How would we know whether there are any conflicts, who reports those and how? Is it a normal Git conflict or something else?

And how do we resolve them? By editing the diff files directly?

Also, what happens if the templates change in a way that makes the diff file outdated (e.g., the diff files says "remove this line", but the template no longer contains that line)?

The patch reports them, and then you fix them in the diffs if I am correct (I keep forgetting, but I did it already. But will try it out much more in the following days).

Yeah, in that case the conflicts happens!

Truth be told, I am not 100% sure about the details of the workflow, I am also suspicious of how will this all go. I am quite sure conflicts will be happening as they should, but how complicated the resolution will be for us, and the whole workflow, is a bit hard to say at the moment. I would say there is 60% chance that this approach will be more trouble than it is worth. But let's give it a try, we have it working now, we will try to use it a bit, and if we don't like it, we can just generate the app/ one final time, put that into separate repo and go with that. So I am looking at this as an experiment, at this point the best move is to give it a limited time try.

Even if experiment shows that this is not a good workflow for opensaas, it might still be useful for automating some of the e2e tests we will want to do for Wasp, so there is that also as a secondary use case.

Ok, if you're really stoked about trying it out, we can go for it.

That said, I'll voice my concerns just sin case you haven't thought about them.

I can't see any part of the procedure this approach has a chance of improving.

It sounds like this approach has all the problems/features of just keeping a separate directory plus:

• The added inconvenience of dealing with patch and merge conflicts in diff files which are difficult for a human to read and write.

• Worse experience during commits and code reviews - You have to compare diff files instead of proper source files.

• The lack of a human-readable example app in the repo - Whoever wants to see the example app must now check out the repo and construct it themselves.

• Extra technical/arcane steps when changing the example app - Instead of updating the example app directly, now you must:

  1. Construct the example app using a custom script and diff files.
  2. Update the generated example app changes (this is the only thing you had to do before).
  3. Construct the diffs from the updated example app.

  With updates that includes multiple iterations, this feels like a lot of pain: you update something and go through the procedure, you push it, the reviewer wants it changed, you update it again (and have to go through the procedure again), you push it again...

  It's a similar problem as what we have with e2e tests, but worse. With e2e tests, you can avoid this cycle by waiting until the PR is finalized before generating the new tests. With this, you must do it every time. If you don't, the reviewer can't review your code.

All in all, since:

• All the development is done in the generated app.
• All the reviewing is done in the generated app.
• All the testing is done in the generated app (don't know if we have tests yet, but that's where it's gonna happen).
• All the reading (contributors, people wanting to use the template, etc.) is done in the generated app.

I don't think this is the way to go. We should just keep a generated app.

@sodic most of these are valid concerns! But, Chesterton's fence - if you don't know why it is there, there is probably a reason you are not seeing, right? So instead of saying we should keep a generated app, you probably should be asking what is it that you are not aware of, that made me go with this approach.

So, the reason why I did this whole diff thing instead of going with the generated appis that it is very hard to figure out how to update the generated app after you do updates to the template. I also wouldn't bother with diffs otherwise and would stick to normal code, of course.

Additionally, the part with reviewing the demo app, people looking at, ... -> those I don't think are concerns in practice, demo app is intended to be minimally different than template + for people to try it out, not to look at the code primarily.

We will see how this experiment goes, and as I mentioned previously I am aware of cons it introduces, but I don't see just having an app in there as a better solution. Instead, it might be better to just go with separate repo or something like that, although that has its own issues. I would consider having just the code in the dir next to it as the very last option, if nothing else works out.

I think this workflow, and its explanation, are confusing to the uninitiated.

In step 1, I run patch.sh and generate the opensaas.sh app (aka demo app).
Then I have to generate a new app_diff/ with diff.sh.

This is because we do not commit an app/ dir to version control. So maybe we should add this bit of info to the beginning of the workflow explanation. Something like:

"Since the demo app is just the open saas template with some small tweaks, and we want to be able to easily keep it up to date as the template changes, the demo app is defined via the diff against the template: app_diff/.

Because we do not commit/push the generated demo app in the app/ dir to version control, the typical workflow is as follows:...