Docs: Add Custom Code Guide #520
Conversation
… to your service after building it. It clarifies the process of merging branches, modifying files, and more.
…clear Understanding Code Code page that explains the philosophy and goes into the modifications that might happen to non-base files.
…tom code to your service page.
…g the link on the new guide.
| 3. Amplication uses a folder structure that separates customizable and non-customizable code. | ||
| 4. The `base` folder contains files that should not be modified, as they will be overwritten by Amplication. | ||
| 5. Files outside the `base` folder can be safely customized and will be preserved across builds. | ||
| 1. All code in your Amplication project can be customized. |
There was a problem hiding this comment.
Maybe instead of saying this- we can say that custom code can be added to all files or such.
| 5. Files outside the `base` folder can be safely customized and will be preserved across builds. | ||
| 1. All code in your Amplication project can be customized. | ||
| 2. Amplication uses a specific folder structure to manage custom and generated code. | ||
| 3. The `base` folder contains generated files that Amplication updates with each build. |
There was a problem hiding this comment.
Amplication can update the files in the base folder in each build, but also may update generated code in other files
| 1. All code in your Amplication project can be customized. | ||
| 2. Amplication uses a specific folder structure to manage custom and generated code. | ||
| 3. The `base` folder contains generated files that Amplication updates with each build. | ||
| 4. Files outside the `base` folder are intended for your custom code and are preserved across builds. |
There was a problem hiding this comment.
They may not be "preserved" as the generated code can be updated there. So I would say something like-
Files outside the base folder are intended for your custom code.
| 2. Amplication uses a specific folder structure to manage custom and generated code. | ||
| 3. The `base` folder contains generated files that Amplication updates with each build. | ||
| 4. Files outside the `base` folder are intended for your custom code and are preserved across builds. | ||
| 5. Amplication uses [smart merging](/smart-git-sync) to update your project while preserving your custom code. |
There was a problem hiding this comment.
I think we should be more clear here and avoid using the word merging (as we merge nothing but suggest a PR that it can be merged).
We should say that Amplication will always respect the custom code that was created by the user and never overwrite it
| ```bash | ||
| git push origin main | ||
| ``` | ||
| 1. Base files in the `base` folder are regenerated with each build. |
There was a problem hiding this comment.
The user will get updates in the base file only in case there are relevant changes.
Not sure it's important to mention that the base files (and actually all the generated code) is regenerated every time
docs/how-to/add-custom-code.md
Outdated
|
|
||
| Amplication is designed to preserve your custom code while allowing for continuous updates to the generated code. Here's how it works: | ||
| 1. Regenerates base files with each build. | ||
| 2. Preserves non-base files containing your custom code. |
There was a problem hiding this comment.
Again- all custom code is preserved...
docs/how-to/add-custom-code.md
Outdated
|
|
||
| This approach allows you to freely add custom business logic, new endpoints, or any other customizations while still benefiting from Amplication's code generation and updates. | ||
| 1. Amplication will provide clear indications of the conflicting areas. |
There was a problem hiding this comment.
Using the known git mechanism
docs/how-to/add-custom-code.md
Outdated
|
|
||
| 4. **Conflict Resolution**: If conflicts arise, Amplication provides clear indications and allows you to resolve them manually. | ||
| While Amplication strives to preserve your custom code, conflicts may arise, especially with significant changes to your data model or entity structure. If conflicts occur: |
There was a problem hiding this comment.
Let's emphasize that the conflict resolution should take place on 'amplication' branch, and then- merge the result to the main branch
docs/how-to/add-custom-code.md
Outdated
| - While Amplication strives to maintain compatibility, major changes to your data model or entity structure may require manual updates to your custom code. | ||
| - While all code can be customized, we recommend focusing custom code in the non-base files for easier maintenance. | ||
| - Major changes to your data model or entity structure may require manual updates to your custom code. | ||
| - Client-side customization (Admin UI) is supported, but changes may not be automatically merged in future builds. Consider maintaining a separate repository for extensive client-side customizations. |
There was a problem hiding this comment.
Let's remove it. I don't think it adds value here
| --- | ||
|
|
||
| # Add custom code to your services | ||
| # Understanding Custom Code in Amplication |
There was a problem hiding this comment.
Adding to this comment-
Not sure I understand why we have two separate pages for the custom code. It seems like there is redundancy between the files and the content repeats itself.
I can understand the need to have one page to explain the concepts of the generated code, and custom code, and the other to show an example of updating custom code or such but then- we need to make sure each page has its own "uniqueness" and contribute different things to the subject.
WDYT?
…n/docs into docs/git-sync-updates
…mplementing Paz's feedback, making these pages much easier to read, and flow better.
|
Hey @PazYanoverr, I implemented your latest feedback. Also, the additional feedback you gave me on the call really helped. I implemented that too. The pages have their own uniqueness, with one focusing on implementation and the other on explanation, as suggested. My one recommendation is adding a Conclusion section to the end of the implementation guide. Now that the user has this custom code full name retrieval method, what can they do with that? Can they use it in the app, or somewhere else in their code? What are the repercussions? Can we link them to a GitHub repo for a more sophisticated example? |
|
@dericksozo this one looks good to me - please resolve the conflict and I will approve and merge it |
(docs): Adding a new guide around adding custom code / business logic to your service after building it. It clarifies the process of merging branches, modifying files, and more.
This PR takes care of #517 and #518.