Add guide on how to update a local Open SaaS app #403
Conversation
|
|
||
| ## Initial Considerations | ||
|
|
||
| It's not recommended that you merge the latest changes from the template into your app as you would in a typical monorepo setup. |
There was a problem hiding this comment.
I would explain shortly why is this so. It is because Open Saas is a template, a starter boilerplate. Not a library where you can pull in the changes. And modifications we do might be not applicable to your code any more, depending on how much you changed your code. They also might not work for your version of Wasp anymore. I wrote a bit about this in the issue, I tried to explain it there.
I would maybe even say that updating Open Saas is not sometihng we expect you to do. And that if you do it, you shoudl do it pedantically, since code might have changed quite a bit, and if you pick just one change but not the rest, it might not behave as it should. So you really gotta understand what you are doing, gotta undrestand all the changes that happened in the meantime.
The real message I would like to carry over here is that they probably shouldn't be updating their open saas app based on new open saas template, and if they do, it should be done very mindfully.
|
|
||
| This will replay every subsequent commit excluding the specified starting point (remove the `^` to be inclusive). If your codebase has diverged significantly, you may have to resolve any merge commits, but once complete, you'll have all the latest changes in your local repo. | ||
|
|
||
| ## Manually merging changes |
There was a problem hiding this comment.
I would maybe open up with this even, and make it very simple: "Hey, the simplest way is for you to manually take a look at the new commits and copy the code changes you like. Be aware they might be using new version of Wasp though, or that you might have changed the codebase too much for them to be applicable.".
Beacuse for me, this is probably the way I would do it. And I don't need any specialized knowledge.
And I would push the "smart" way of cherry-picking as the more "formal"/advanced option.
|
ok @Martinsos I made the changes and leaned more heavily on advising against updating. |
| @@ -0,0 +1,81 @@ | |||
| --- | |||
| title: How (Not) to Update Your Open SaaS App | |||
| ## If you still decide to update your app | ||
|
|
||
| If you read above, considered the risks, and still need specific improvements, we recommend that you either: | ||
| 1. Recomended: [Manually merge the changes](#manually-merging-changes). |
There was a problem hiding this comment.
| 1. Recomended: [Manually merge the changes](#manually-merging-changes). | |
| 1. Recommended: [Manually merge the changes](#manually-merging-changes). |
|
|
||
| If we make important changes to the template we may update the tag to a newer commit, so that new users will get the latest changes. That means that a tag, e.g. `wasp-v0.16-template`, may point to different commits over time, as changes are made to the template. | ||
|
|
||
| This may make it difficult to find the correct commit hash that matches the template code you started with. |
There was a problem hiding this comment.
Ah crap, yeah this makes it hard. Hm.
Btw interesting idea: we could maybe, in theory, write in their app, when they create new OpenSaas app, which commit it was created from. It's hash. When our wasp CLI is creating it on the disk, it could obtain that information from git and put it somewhere, e.g. into comment in main.wasp file. Not super trivial change, but doable.
But probably not worth bothering with that hm.
| content: | | ||
| Have an Open SaaS app in production? <a href="https://e44cy1h4s0q.typeform.com/to/EPJCwsMi">We'll send you some swag! 👕</a> | ||
| --- | ||
|
|
There was a problem hiding this comment.
Ok this is better I like it!
If you want to leave the main structure as it is, I think that is good enough.
I do have to admit I have a bit different idea of what I would go for, so I will explain it here, and you choose how much you like it / want to use from it, I won't push you.
So in my head ideal is somehwere in between the first iteration and this iteration: Not saying them they shouldn't do it, but also not saying they should :D. Now it seems to me it went a bit too far maybe (although I like this extreme better than the other one).
I would go something like this:
Why you can't really update the Open Saas based app
Open Saas is not a library or a binary, but a starter template: initial code that you start coding your Wasp app from. And once you start, that code is your own to change and modify as you like. Due to that, there is no easy way to update your Open Saas based app to include the update present in the newer Open Saas template!
This doesn't mean you can't benefit from the changes done to the latest Open Saas template, but it requires a different approach than a typical library/software update would. It is a very manual process, that requires you to pedantically and thoroughly understand the changes done to the Open Saas template and then mindfully copying and applying the relevant pieces over to your project.
And then we descirbe this manual process, and also the thing with cherry picking.
Ok now that I wrote this, I do like the idea behing it, but I do think you did somewhat beter job with the actual text. So as I said, do as you like, if you feel it is not worth it the time to do this kind of modificaiton, I get it, don't do it.
EDIT: I got to the end of PR and actually, it feels like one can't be too extreme in not recommending udpates here. If you have to ask how to update the template, you are already dangerous to yourself. Yeah, so maybe just ignore this comment.
|
|
||
| Because your codebase will naturally diverge from the template as you build your unique application, and any updates we may make to the template may not be compatible with your modified codebase, or your version of Wasp. | ||
|
|
||
| Even if you *really* want to include a new feature from the template in your app, proceed with caution and througly consider the following: |
There was a problem hiding this comment.
| Even if you *really* want to include a new feature from the template in your app, proceed with caution and througly consider the following: | |
| Even if you *really* want to include a new feature from the template in your app, proceed with caution and thoroughly consider the following: |
|
|
||
| Even if you *really* want to include a new feature from the template in your app, proceed with caution and througly consider the following: | ||
|
|
||
| - Changes to the template may be tightly coupled. Implementing one change without related ones could cause unexpected issues. |
There was a problem hiding this comment.
Nice, exactly! This is important. They would really need to understand what these changes rely on regarding the rest of the template, so copying them without understanding them -> big no no.
What they should be doing is not really updating, it is actually reading somebody else's homework and enriching your own with pieces of it. Yeah it is more learning and enriching, then it is updating.
|
|
||
| If you read above, considered the risks, and still need specific improvements, we recommend that you either: | ||
| 1. Recomended: [Manually merge the changes](#manually-merging-changes). | ||
| 2. Riskier/Advanced: [Cherry-pick the commits](#cherry-picking-git-commits) that you want to merge and deal with any merge conflicts on a case-by-case basis. |
There was a problem hiding this comment.
I think I would maybe even just remove the cherry picking part. Just describe the manual approach and that is it. Either they are exprienced enough to know what this is and then we don't need to tell them, or we are just making it easier for them to blindly copy stuff when they don't really have enough knowledge for it.
Again, do as you like, this is just an idea, I don't have strong opinion.
| This may make it difficult to find the correct commit hash that matches the template code you started with. | ||
| ::: | ||
| ## Manually merging changes | ||
| Compare your starting revision with the latest. You can find the commit hash of your starting revision in the [Open Saas GitHub repo's `main` branch](https://github.com/wasp-lang/open-saas/commits/main/). |
There was a problem hiding this comment.
But you just said they don't know the starting revision, right? I am reading this after reading the part above and I am thinking -> but didn't we just say I don't know the starting revision?
How would this finding go -> I look for what? How can I know which one is my starting revision while looking at all of them listed?
|
|
||
| This will show you the changes between your starting revision and the latest. | ||
|
|
||
| Manually apply any changes you want into your local project. |
There was a problem hiding this comment.
I would mention here that you should understand these and then apply any improvements you like to your project.
| Manually apply any changes you want into your local project. | ||
|
|
||
|
|
||
| ## Cherry-picking git commits |
There was a problem hiding this comment.
Yeah I think this is just too dangerous. It might upgrade for version of Wasp they don't have. They might merge commit without modifying their own code that depends on it. I mean in theory, this is a neat way to do it, you are going change by change and updating stuff. But you gotta have discipline to not just run through it. Yeah maybe it is ok to recommend it I guess, but I would emphasize again they should be mindful about every single commit as they merge it / accept it. Conflicts are not enough -> there might be no conflicts, and yet the rest of your codebase expects that part to not change. And you are lucky if code breaks then. If you are unlucky, you will end up with something going wrong in production, maybe even security issues. Oh yeah. Ok I would remove this.
Description
Fixes #240
Contributor Checklist