Should we consider a versioning scheme for open-saas?

[Martinsos]

Since open saas has quite picked up in the usage, I was wondering if it would make sense to consider some kind of versioning scheme.

In the sense of that we have something like open-saas 1.0.0, 1.2.1, 2.0.0 .

If we don't need it (yet), then better not to over complicate, but I wanted to explore if possibly it would be useful.

1. Docs. Now with OpenSaas that uses wasp 0.12 out, we don't have docs for the one that was using wasp 0.11. Not, the biggest difference in docs is going to be regarding getting started I believe, but still, there are other differences in the doc for sure, and if I am a user of 0.11, I am not able any more to go back and take a look at the old docs without checking out the open-saas repo to an older commit and hosting them myself. And I don't know to which commit to go, since there is no easy way to figure that out (no tags).

Hm actually I don't have a strong reason except for docs.
Open saas is quite peculiar in the sense that it is a template, and once you check it out, you are good to go, and don't have a lot of reason to come back, except for docs. There are no updates to pull in. Docs are very important though.

Also, it is not so clear how we would even stick to semver: what is a major change, what is minor, what is patch? Well ok, we could figure that out I guess. Maybe it would answer the question "What would happen if I tried to merge my current project with new state of the template". Yeah, that would probably make sense. Ok, so semver could be just fine.

Another question is, are we ok with main always being the latest version of open saas that is "released"? Right now, I believe that is so -> main is always good to go. This means main must not be in a broken state, we expect it to always works, to have correct docs, and to be well tested.
This is doable if features are developed on features branches and merged into main only once they are well tested. And maybe this is the right approach at the moment.
Alternatively, we could have a release branch, similar like we do for wasp, and then we would release on it when we are ready. Github template would be pulling from it (this can be configured) and we would do thorough testing / polishing before merging main into release. This would mean we can be more nonchalant on main and break stuff a bit along the way for a short while if needed. Then it might make sense to also have a version number for each release.
I am not sure what is better here -> I would probably stick with what we have for now actually, because it is simpler, and if it works it works, but would beef up our testing game in that case and also document this in README.

Following up on that, whatever are our answers on all this questions, we should make sure we document relevant decisions / processes in the README.md, so other contributors and us at the end know what are our processes and how are we handling stuff.

Also, we should set up CI where we test open saas. Likely we will want to write some e2e tests using something like Playwright. Possibly some unit tests also. Not only will this give us confidence and enable us to iterate on open-saas faster, but it will also become a part of the template, that open-saas users also get as part of it -> they get a Github Action + tests out of the box, which in my experience is much easier to maintain once somebody has set them up, and that is what we would be doing, setting this stuff up.

Ok, so I digressed heavily here and ended up going far and beyond the title of this issue. I will stop here and wait for some feedback and initial thoughts, and then we can look into splitting this into multiple smaller issues that we can track independently.

[vincanger]

I like the testing idea. We should definitely go with that.

As far as versioning is concerned, the docs are only slightly different from v0.11.8. And where they are different, it is merely a difference in import syntax. I thought about it, and to me it makes sense to push the users to migrate to version 0.12 if the current docs don't suffice and they still need further assistance. It is less burden on us to maintain two docs versions, and helps us move forward with improving v0.12. We can always direct them to Wasp v0.11.8 docs as well. Plus, the fact that we offer a merge script that takes care of most of the process, makes it the most efficient solution.

I personally find the main/release structure a bit too bulky for a saas template. Having main be the current working version of the template makes the most sense to me, especially if it;s being backed up by tests.

The takeaway here for me is:

• add tests!
• add some info to the current Open SaaS docs banner (pictured below) that tells them they can reference v0.11.8 Wasp docs if they prefer not to migrate

how does that sound @Martinsos ?

[Martinsos]

@vincanger sounds good to me! I would keep an eye out for the case in the future that we need multiple versions of docs, or a more controlled release process, but we will know if people start complaining, or if we end up shipping bugs. Better to not overengineer right now.

I will take your list and add to it:

1. Add tests.
2. Set up CI. Should run on PRs and on main branch, at least.
3. Banner -> probably makes sense!
4. In README.md, add some info on how we are managing releasing, specifically that whatever is on main branch is also what is released, because that is what they get when they do the template thing. Btw they will not get that via wasp new hm, they will get whatever is tagged with that 0.12 tag, so that is a bit peculiar. We can at least mention that, and it would also be interesting to figure out how we want to go about it. On way could be that we have release branch that automatically gets pushed to upon main passing CI, and CI would also automatically update the latest Wasp tag. Ok I am probably looking too much ahead again.

[vincanger]

haha @Martinsos so everytime i push a new commit i update the tag to be the latest commit :)

everything else sounds good!

[Martinsos]

haha @Martinsos so everytime i push a new commit i update the tag to be the latest commit :)

everything else sounds good!

That sound quite bothersome! Also, what if somebody else commits to main, be it directly or via a merged PR and forgets to update the tag? No biggie I guess, but it is sloppy.

I would at least write down into README.md what the current process is, that way even though it is not automated, it is at least specified. And we can look into automation with time (via CI probably).